cadrumo.domain.calculations.registry.temporal module

Temporal selection for registry-backed modelo revisions.

Selects exactly one ModeloRevision from a ModeloDefinition given a filing year, period, and optional date constraint.

class RevisionSelectionMetadata(**data)[source]

Bases: RegistryModel

Complete immutable metadata required by the canonical revision selector.

id: RevisionId
valid_from: date
valid_to: date | None
period_selector: PeriodSelector
deadline_windows: tuple[DeadlineWindowDefinition, ...]
contains_date(coordinate)[source]

Return whether the coordinate lies inside the governed period window.

Return type:

bool

Parameters:

coordinate (date)

classmethod from_revision(revision)[source]

Project exactly the fields consumed by temporal selection.

Core types: ModeloRevision.

Return type:

RevisionSelectionMetadata

Parameters:

revision (ModeloRevision)

class ModeloDirectoryMetadata(**data)[source]

Bases: RegistryModel

Complete modelo-level metadata without duplicating revision payloads.

id: str
title_localization_key: str
official_name_localization_key: str
tax_domain: str
cadence: ModeloCadence
jurisdiction: Literal['ES-AEAT']
calculation_class: CalculationClassField
output_sensitivity: SensitivityClassField
capabilities: ModeloFilingCapabilities
legal_refs: LegalRefs
source_refs: SourceRefs
inception: ModeloInceptionField | None
pending_ejercicio_ordenes: PendingEjercicioOrdenes
property title: str

Return the strict official-Spanish Modelo title, as the materialized view does.

classmethod from_modelo(modelo)[source]

Capture every modelo field needed to reconstruct a selected snapshot.

Core types: ModeloDefinition.

Return type:

ModeloDirectoryMetadata

Parameters:

modelo (ModeloDefinition)

class RevisionEndpointSourceEnrollment(**data)[source]

Bases: RegistryModel

Small source-membership projection for one historical endpoint.

revision_id: RevisionId
source_refs: SourceRefs
revision_endpoint_source_ids(modelo, revision)[source]

Return the compiler’s canonical source-enrollment basis for one endpoint.

Core types: ModeloDefinition, ModeloRevision.

Return type:

tuple[str, ...]

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

Bases: RegistryModel

Point-addressed revision selection metadata for one modelo.

modelo_id: str
modelo: ModeloDirectoryMetadata
revisions: tuple[RevisionSelectionMetadata, ...]
endpoint_source_enrollments: tuple[RevisionEndpointSourceEnrollment, ...]
pending_ejercicio_ordenes: tuple[PendingEjercicioOrden, ...]
supported_filing_years: SupportedFilingYearsCatalogue | None
endpoint_source_ids(revision_id)[source]

Return the admitted source ids for one exact revision endpoint.

Return type:

tuple[str, ...]

Parameters:

revision_id (RevisionId)

materialize(revision)[source]

Reconstruct one immutable modelo view around a selected revision of this directory.

The view carries only the selected payload; its revision-identity references still resolve against every revision this directory declares.

Raises:

RegistryValidationError – When the view is not a valid modelo, for example when the revision references one its directory lacks.

Parameters:

revision (ModeloRevision)

Return type:

ModeloDefinition

Core types: ModeloRevision.

Return type:

ModeloDefinition

Parameters:

revision (ModeloRevision)

classmethod from_modelo(modelo, *, support=None)[source]

Build a deterministic directory without embedding revision payloads.

Core types: ModeloDefinition.

Return type:

ModeloRevisionDirectory

Parameters:
class RevisionTemporalResolution(revision, requested_filing_year, authored_filing_year, projection_direction)[source]

Bases: Generic

An authored revision selected for one requested filing coordinate.

Parameters:
revision: TypeVar(RevisionT, bound= _SelectableRevision)
requested_filing_year: int
authored_filing_year: int
projection_direction: TemporalProjectionDirection
revision_temporal_resolution(revision, *, filing_year, period, support)[source]

Describe requested identity and authored provenance for a selected revision.

Return type:

RevisionTemporalResolution[TypeVar(RevisionT, bound= _SelectableRevision)]

Parameters:
select_revision_for_year(modelo, *, filing_year, on=None, support=None)[source]

Select exactly one revision for a filing year and effective date.

This is the year-only authority for read-only revision-wide surfaces such as bindings discovery. Callers that already have its revision may materialise a snapshot with that explicit revision_id rather than independently selecting again.

Parameters:

  • modelo (ModeloDefinition) – The ModeloDefinition whose declared revisions are searched for the one matching filing_year and on.

  • filing_year (int) – AEAT filing year used to narrow revisions by their period_selector.

  • on (date | None) – Optional reference date at which the revision must be the applicable design: inside the tax periods it governs, or inside a filing window it declares for this coordinate.

  • support (SupportedFilingYearsCatalogue | None) – Optional registry envelope that hard-gates the request and carries a year beyond its authored horizon back to that horizon.

Return type:

ModeloRevision

select_revision_metadata_for_year(directory, *, filing_year, on=None, support=None)[source]

Select metadata with the exact canonical year-scoped rules.

Return type:

RevisionSelectionMetadata

Parameters:
select_revision(modelo, *, filing_year, period, on=None, revision_id=None, support=None)[source]

Select exactly one ModeloRevision for a filing period.

Parameters:

  • modelo (ModeloDefinition) – The ModeloDefinition to select a revision from.

  • filing_year (int) – AEAT filing year used to narrow revisions by period_selector.

  • period (str) – Period token (e.g. "1T", "0A", "ALTA"); case-insensitive against the revision’s declared periods.

  • on (date | None) – Optional reference date at which the revision must be the applicable design: inside the tax periods it governs, or inside a filing window it declares for this coordinate.

  • revision_id (TypeAliasType | None) – Optional explicit revision id; restricts candidates to the matching revision when supplied.

  • support (SupportedFilingYearsCatalogue | None) – Optional registry envelope that hard-gates the request and carries a year beyond its authored horizon back to that horizon.

Return type:

ModeloRevision

select_revision_metadata(directory, *, filing_year, period, on=None, revision_id=None, support=None)[source]

Select complete revision metadata through the canonical period rules.

Return type:

RevisionSelectionMetadata

Parameters:
select_authored_revision_metadata(directory, *, filing_year, period, on=None)[source]

Select the revision the law applies to a coordinate, outside the support envelope.

The support envelope gates what the product will FILE, not which design the law applied to a past period. Reading a carried prior filing needs the latter, so this selects only among revisions whose own period selector covers the exact coordinate and never projects a year onto another authored edition.

Return type:

RevisionSelectionMetadata

Parameters: