cadrumo.domain.calculations.registry.bindings_previous_filing module

Previous-filing binding selectors, requirements, and resolvers.

The ModeloRevision supplies previous_filing BindingDefinition declarations; this module turns those selectors into RegistryFoldRequirement source requirements and resolved BindingId values.

See also

cadrumo.domain.calculations.registry.bindings

Public import surface that re-exports these previous-filing helpers.

cadrumo.domain.calculations.registry.relations

Relation-fold sibling that materialises cross-modelo source values.

cadrumo.domain.calculations.registry.observation_fold

Shared fold helpers for observed casilla values.

class PreviousFilingSourceReference(source_modelo, required_periods, source_casilla_ids, filing_year_delta=0, max_year_delta=None, has_variable_year_offset=False)[source]

Bases: object

Canonical source reference extracted from a typed previous-filing selector.

The reference names the source ModeloId, required periods, and source CasillaId values declared by one previous-filing binding selector.

filing_year_delta and max_year_delta ride along so a build-time year-coverage check can derive the exact source-year interval a selector requires without re-parsing the selector a second time.

has_variable_year_offset is True for a provider whose temporal member is the expanding span or a period offset: both produce PER-ANCHOR year deltas (PreviousFilingProvider.required_period_anchors_for_target() returns several (period_year_delta, period) pairs, each with its own offset) rather than the single uniform offset a coverage check keyed on one interval can represent.

Parameters:

  • source_modelo (ModeloId)

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

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

  • filing_year_delta (int)

  • max_year_delta (int | None)

  • has_variable_year_offset (bool)

source_modelo: TypeAliasType
required_periods: tuple[str, ...]
source_casilla_ids: tuple[TypeAliasType, ...]
filing_year_delta: int
max_year_delta: int | None
has_variable_year_offset: bool
previous_filing_source_reference(binding)[source]

Return the PreviousFilingSourceReference for a previous_filing binding.

The supplied BindingDefinition is parsed through the same selector model used by previous_filing_observation_requirements().

Return type:

PreviousFilingSourceReference

Parameters:

binding (BindingDefinition)

periodic_carry_bindings_for_period(revision, *, period=None)[source]

Return the revision’s periodic carry bindings with the periods they cover.

A periodic carry is a binding whose provider names a source modelo and a PERIOD-RELATIVE temporal member – the target-period offset or the prior- quarter expanding span. Both members state a source window that moves with the target period rather than naming a fixed one, which is what makes the declaration a carry between consecutive filings of a periodic modelo.

The provider kind is deliberately not part of the test: the same carry may be declared through a previous_filing provider or through a relation_prefill one, and a consumer asking which periods a modelo carries between filings must see both.

The covered periods come from the binding’s own target_periods applicability when it declares one. When it does not, they are derived from the revision’s filing schedules: a schedule period is covered when the temporal member yields a source anchor for it, so a member that cannot interpret a cadence (the expanding span against a monthly code) simply does not cover it rather than being assumed to.

Core types: ModeloRevision.

Return type:

tuple[tuple[BindingDefinition, tuple[str, ...]], ...]

Parameters:
previous_filing_observation_requirements(revision, *, filing_year, period)[source]

Return source requirements needed by direct previous-filing bindings.

The ModeloRevision is scanned for direct previous_filing bindings, and each selector becomes a RegistryFoldRequirement naming source modelo/year/period, BindingId consumers, and source casilla ids.

Return type:

tuple[RegistryFoldRequirement, ...]

Parameters:
resolve_previous_filing_binding_values(revision, observations, *, filing_year, period, activity_start_date=None, excluded_binding_ids=None)[source]

Resolve direct previous-filing bindings from observed filed declarations.

The ModeloRevision supplies the binding selectors and aggregation operators; observations supply the filed casilla values they fold. The returned mapping is keyed by BindingId and carries resolved decimal.Decimal values for formula runtime consumption.

Return type:

dict[TypeAliasType, Decimal]

Parameters:
class PreviousFilingProvider(**data)[source]

Bases: BaseModel

Typed provider model for a previous_filing binding declaration.

The source coordinate is split in two: source_modelo plus the source casilla ids name WHICH filed values are read, and temporal names WHEN they were filed, relative to the target filing context. The temporal axis is the shared closed union, so the six mutually exclusive period fields this model used to carry – and the hand-written validators that policed their legal combinations – are replaced by members that cannot express an illegal combination at all.

Parameters:

data (Any)

kind: Literal[BindingSourceKind.PREVIOUS_FILING]
source_modelo: ModeloId
temporal: BindingTemporalSelector
source_casilla_ids: tuple[CasillaId, ...]
source_casilla_id: CasillaId | None
required_source_casilla_ids: tuple[CasillaId, ...] | None
grouping: Literal['per_grupo_member'] | None
property required_periods: tuple[str, ...]

Return the source periods the temporal member names, if any.

same_target_context, the period offset, and the expanding span name no fixed period set: their periods depend on the target period and are produced by required_period_anchors_for_target() instead.

property uniform_filing_year_delta: int

Return the single year offset every anchor shares, or zero.

Only FilingYearOffset states one uniform offset. The period offset and the expanding span carry a per-anchor year delta instead, which is why has_variable_year_offset exists.

property has_variable_year_offset: bool

Whether the anchors carry per-anchor year deltas rather than one offset.

property max_year_delta: int | None

Return the absolute bound on anchor year deltas the member declares.

required_period_anchors_for_target(target_period)[source]

Return source year-offset and period anchors for a target period.

Each year offset is the TOTAL distance from the target filing year, so a caller derives the source year as filing_year + year_delta and never adds uniform_filing_year_delta a second time.

Return type:

tuple[tuple[int, str], ...]

Parameters:

target_period (str)

validate_previous_filing_binding(binding)[source]

Validate a previous_filing binding at registry-build time.

Accumulating list[str] validator: validates the selector shape against PreviousFilingProvider and lifts the previous-filing op/source invariants for a BindingDefinition to build time, preserving the underlying pydantic field error.

Return type:

list[str]

Parameters:

binding (BindingDefinition)

is_direct_previous_filing_binding(binding)[source]

Whether binding carries a DIRECT previous-filing selector shape.

Every real caller passes a source == "previous_filing" binding (the only source this predicate is meaningful for), so binding.provider is already hydrated into PreviousFilingProvider by construction (the BindingProvider union hydrates it at construction). Reading through the declared model – _previous_filing_selector, the same helper previous_filing_observation_requirements() and _aggregate_previous_filing_binding() already call – rather than string-literal dict.get() keys means a field rename on PreviousFilingProvider fails loud instead of silently making every direct binding register as non-direct: this predicate backs the registry-build refusal (_validate_relation_sources.py) that a previous_filing binding must satisfy the direct-selector shape or declare relation_prefill instead, so a silently wrong False here is a validation gate going quiet, not a benign miss.

Return type:

bool

Parameters:

binding (BindingDefinition)

previous_filing_binding_source_casilla_ids(binding)[source]

Return the source casilla ids a previous_filing binding targets.

The canonical, typed way to ask “which casilla(s) does this previous_filing binding read from” – delegates to the same _previous_filing_source_ids() normalisation every other consumer of this selector uses, so a caller reading only the singular source_casilla_id key via a raw selector_as_dict(binding).get(...) silently misses any binding declaring the plural source_casilla_ids form instead, indistinguishable from “this binding targets no casilla at all”. Reading through PreviousFilingProvider also means a renamed source_casilla_id/source_casilla_ids field raises here, rather than silently returning an empty tuple for every binding.

Returns an empty tuple for a binding that is not previous_filing at all – a real, different fact from a malformed or drifted selector.

Return type:

tuple[TypeAliasType, ...]

Parameters:

binding (BindingDefinition)