aeat.domain.calculations.registry._relations module

Relation helpers for cross-model registry dependencies.

Resolves cross-modelo source requirements and materialises relation values for a ModeloRevision filing. Relations declare which source filings and output casillas must be available before the target modelo can be calculated.

See also

aeat.domain.calculations.registry._bindings_previous_filing

Same requirement record reused by direct previous-filing carries.

aeat.domain.calculations.registry._observation_fold

Observation fold helpers used to gather source casilla values.

aeat.domain.calculations.registry._relation_aggregation

Canonical relation aggregation resolver used by this module.

class RegistryFoldRequirement(**data)[source]

Bases: BaseModel

One source-filing requirement for a cross-filing fold-in.

The single unified requirement record for both fold-in mechanisms: a cross-modelo relation fold (relation_ids / target_bindings populated) and a same-modelo direct previous_filing carry (binding_ids populated). Both the source-period and source-casilla axes are PLURAL so the record is a superset of the two prior shapes: a relation requirement fans plural periods against a single source_casilla_ids member, while a previous_filing requirement carries a single periods member against plural source_casilla_ids. legal_refs and source_refs retain the originating relation/binding grounding for operator diagnostics. Each producer emits a single-element tuple where its cardinality is one; no value shifts, only the record TYPE unifies.

Consumed by relation_source_requirements(), resolve_relation_values_from_observations(), and aeat.domain.calculations.registry.previous_filing_observation_requirements().

Parameters:

  • source_modelo (ModeloId)

  • filing_year (int)

  • filing_periods (tuple[Period, ...])

  • periods (tuple[str, ...])

  • source_casilla_ids (tuple[CasillaId, ...])

  • binding_ids (tuple[BindingId, ...])

  • relation_ids (tuple[RelationId, ...])

  • target_bindings (tuple[BindingId, ...])

  • dependency_role (str)

  • dependency_treatment (str)

  • aggregation_op (str)

  • legal_refs (tuple[LegalRefId, ...])

  • source_refs (tuple[SourceRefId, ...])

source_modelo: ModeloId
filing_year: int
filing_periods: tuple[Period, ...]
periods: tuple[str, ...]
source_casilla_ids: tuple[CasillaId, ...]
binding_ids: tuple[BindingId, ...]
relation_ids: tuple[RelationId, ...]
target_bindings: tuple[BindingId, ...]
dependency_role: str
dependency_treatment: str
aggregation_op: str
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
relation_source_requirements(revision, *, filing_year, period)[source]

Return requirement records needed to resolve relations for a filing.

Parameters:

  • revision (ModeloRevision) – The ModeloRevision whose relation declarations to inspect.

  • filing_year (int) – Target filing year; combined with each relation’s source offset to derive the expected source-modelo filing year.

  • period (str) – Target period token; filters relations by target_periods and seeds the source-period derivation.

Return type:

tuple[RegistryFoldRequirement, ...]

Returns:

RegistryFoldRequirement rows keyed by source modelo/year/period and source casilla.

resolve_relation_values(revision, external_outputs, *, period=None)[source]

Resolve typed relation values from caller-supplied external outputs.

external_outputs is keyed by relation id. Aggregation defaults to copy; {"op": "sum"} sums tuple values for annual summaries.

Parameters:

  • revision (ModeloRevision) – The ModeloRevision whose relation definitions are resolved against the supplied external outputs.

  • external_outputs (Mapping[TypeAliasType, Decimal | tuple[Decimal, ...]]) – Caller-supplied per-relation values keyed by RelationId; a decimal.Decimal under copy aggregation or a tuple of Decimals under sum.

  • period (str | None) – Optional period token; restricts active relations to those whose target_periods set contains it.

Return type:

dict[TypeAliasType, Decimal]

resolve_relation_values_from_observations(revision, observations, *, filing_year, period)[source]

Resolve relation values from normalized filed-declaration observations.

Parameters:
Return type:

dict[TypeAliasType, Decimal]

Returns:

Resolved RelationId values suitable for aeat.domain.calculations.registry._formula_runtime.calculate_registry_snapshot().

materialize_relation_binding_values(revision, relation_values, *, period=None)[source]

Copy resolved relation values into their declared target bindings.

Relation ids remain the canonical formula-runtime keys. This helper is an additive bridge for registry rows that also declare target_binding so bound casillas can consume a relation-backed value without duplicating relation resolution in the application layer.

Parameters:

  • revision (ModeloRevision) – The ModeloRevision whose relation-to-binding mappings are used to populate the returned dict.

  • relation_values (Mapping[TypeAliasType, Decimal]) – Already-resolved relation id to Decimal mapping.

  • period (str | None) – Optional period token; restricts active relations to those whose target_periods set contains it.

Return type:

dict[TypeAliasType, Decimal]

Returns:

Target BindingId values for relation-backed bound casillas.