aeat.domain.calculations.registry._queries module

Typed read API for modelo registry introspection surfaces.

RegistryQueryService wraps a ValidatedRegistryAuthority and exposes structured report objects for the CLI list, describe, casillas, formulas, and bindings commands. Queries narrow to a single ModeloDefinition and then to one ModeloRevision selected by filing year, period, and optional revision id.

class RegistryQueryService(authority)[source]

Bases: object

Stable Python facade over the validated modelo registry authority.

Parameters:

authority (ValidatedRegistryAuthority)

list_modelos(*, year=None, domain=None)[source]

Return a catalogue listing of all registered modelos.

Each entry is a lightweight ModeloListRow carrying only summary fields — no revision details are resolved. The rows are sorted ascending by modelo code.

Parameters:

  • year (int | None) – When supplied, restricts the listing to modelos that have at least one revision whose period_selector covers the given filing year. None returns all registered modelos.

  • domain (TaxDomain | None) – When supplied, restricts the listing to modelos whose registry TaxDomain equals the requested tax family (e.g. TaxDomain.IVA). None returns every family. The year and domain filters compose: passing both narrows to modelos that satisfy each.

Return type:

ModeloListReport

Returns:

A ModeloListReport containing the matching rows.

source_inventory()[source]

Report every BindingSourceKind the committed registry declares, and where.

Walks every committed modelo revision and every binding it declares, grouping by the binding’s source kind. The result records, per source kind, the committed revisions that declare it and the per-revision binding count. This is a pure registry introspection surface — it does not consult the live calculation mesh — so it stays inside the domain boundary. A caller in the application layer joins this inventory against the disposition registry (build_binding_source_dispositions) to prove that every declared source kind is enrolled or explicitly deferred, never silently blank (the no-dormant-source-resolvers connectivity contract).

Return type:

RegistrySourceInventoryReport

Returns:

A RegistrySourceInventoryReport whose rows are sorted by the source kind’s string value; each row’s sites are sorted by (modelo, revision_id).

support_matrix()[source]

Return the registry-wide per-modelo support/capability matrix.

For every modelo the authority can load, builds a ModeloEntry capturing supported revisions, calc/manifest/export/extractor capability flags, declared per-ejercicio casilla renames, declared deprecation (support-removal) decisions, and declared AEAT-portal cross-references — every field read or folded directly from the loaded registry, never hand-maintained (see no-dormant-source-resolvers / no-silent-under-declaration).

Return type:

ModeloSupportMatrixReport

Returns:

A ModeloSupportMatrixReport whose entries are sorted by modelo_id.

describe_modelo(modelo, *, period=None, as_of=None)[source]

Return a full describe report for one modelo and its resolved revision.

Resolves the revision using the same precedence logic as the other query methods: when period is a bare registry token (e.g. "1T", "0A"), the revision that declares it is selected; when period is None, the latest revision by valid_from is returned. Use describe_modelo_for_scope when the filing year must participate in revision selection.

Parameters:

  • modelo (str) – Short numeric identifier for the modelo (e.g. "303").

  • period (str | None) – Optional period narrowing. Accepted forms are bare registry period tokens ("1T", "0A", "01"-"12") or declared non-date tokens such as "alta".

  • as_of (date | None) – Optional calendar date for validity gating. Defaults to today when None.

Return type:

ModeloDescribeReport

Returns:

A ModeloDescribeReport for the resolved revision.

Raises:

RegistryValidationError – When modelo is not registered, the period is not declared by any revision, or no revision covers the requested scope.

describe_modelo_for_scope(modelo, *, filing_year, period, as_of=None)[source]

Return a ModeloDescribeReport for a scope.

Return type:

ModeloDescribeReport

Parameters:

  • modelo (str)

  • filing_year (int)

  • period (str)

  • as_of (date | None)

casillas(modelo, *, period=None, as_of=None, input_kind=None, required=None, form_number=None)[source]

Return the casilla (numbered-box) listing for a resolved modelo revision.

A casilla is a numbered input box on an AEAT tax form. The listing includes every casilla in the resolved revision, optionally filtered to a subset by kind, required flag, or form page number.

Parameters:

  • modelo (str) – Short numeric identifier for the modelo (e.g. "303").

  • period (str | None) – Optional period narrowing; see describe_modelo for accepted forms.

  • as_of (date | None) – Optional calendar date for validity gating.

  • input_kind (InputKind | None) – When supplied, restricts rows to casillas of the given InputKind (e.g. InputKind.MANUAL, InputKind.COMPUTED).

  • required (bool | None) – When supplied, restricts rows to casillas whose required flag matches this value.

  • form_number (str | None) – When supplied, restricts rows to casillas on the given physical form page or sub-form.

Return type:

ModeloCasillasReport

Returns:

A ModeloCasillasReport for the resolved revision, containing the filtered casilla rows.

Raises:

RegistryValidationError – When the modelo or period is not registered, or no revision covers the requested scope.

casillas_for_scope(modelo, *, filing_year, period, as_of=None, input_kind=None, required=None, form_number=None)[source]

Return a ModeloCasillasReport for a scope.

Return type:

ModeloCasillasReport

Parameters:
casilla(modelo, casilla, *, period=None, as_of=None)[source]

Return the full semantic detail for one casilla on a resolved revision.

Addresses a single casilla by its canonical id or its printed number and surfaces the authoritative label, legal/source grounding, input kind, and — when the casilla is computed — the resolved formula expression. Revision selection follows the same precedence as describe_modelo().

Parameters:

  • modelo (str) – Short numeric identifier for the modelo (e.g. "303").

  • casilla (str) – Casilla id or printed number to look up.

  • period (str | None) – Optional period narrowing; see describe_modelo().

  • as_of (date | None) – Optional calendar date for validity gating.

Return type:

ModeloCasillaDetailReport

Returns:

A ModeloCasillaDetailReport for the addressed casilla.

Raises:

RegistryValidationError – When the modelo or period is not registered, no revision covers the requested scope, or the casilla id/number is not defined by the resolved revision.

casilla_for_scope(modelo, casilla, *, filing_year, period, as_of=None)[source]

Return a ModeloCasillaDetailReport for a scope.

Return type:

ModeloCasillaDetailReport

Parameters:
bindings_for_scope(modelo, *, filing_year, period, as_of=None)[source]

Return bindings for a specific filing scope (already-parsed year + period).

Unlike bindings, this method accepts the already-parsed filing_year integer and registry period string (e.g. "1T", "01") produced by the CLI’s period-parsing step. This avoids re-parsing a user-facing period string when the caller already holds the decomposed values.

Return type:

ModeloBindingsReport

Returns:

A ModeloBindingsReport for the requested filing scope.

Parameters:

  • modelo (str)

  • filing_year (int)

  • period (str)

  • as_of (date | None)

formulas_for_scope(modelo, *, filing_year, period, as_of=None)[source]

Return a ModeloFormulasReport for a scope.

Return type:

ModeloFormulasReport

Parameters:

  • modelo (str)

  • filing_year (int)

  • period (str)

  • as_of (date | None)

bindings_for_year(modelo, *, filing_year, as_of=None)[source]

Return a ModeloBindingsReport for filing_year.

bindings with no period resolves the latest revision, which for a multi-revision modelo (e.g. Modelo 100, one revision per renta year) reports binding ids for the wrong year. This method instead selects the revision whose period_selector covers filing_year — the same revision a work unit created for the same (modelo, filing_year) resolves — so the reported binding ids are the ones the calculation will accept.

Return type:

ModeloBindingsReport

Parameters:

  • modelo (str)

  • filing_year (int)

  • as_of (date | None)

bindings(modelo, *, period=None, as_of=None)[source]

Return the full binding listing for a resolved modelo revision.

A binding maps a financial-data source to a casilla or formula input. For year-specific binding ids (e.g. when a multi-revision modelo publishes different binding names per renta year) prefer bindings_for_year or bindings_for_scope so the resolved revision matches the one the calculation engine will use.

Parameters:

  • modelo (str) – Short numeric identifier for the modelo (e.g. "130").

  • period (str | None) – Optional period narrowing; see describe_modelo for accepted forms. When None, the latest revision is used.

  • as_of (date | None) – Optional calendar date for validity gating.

Return type:

ModeloBindingsReport

Returns:

A ModeloBindingsReport for the resolved revision.

Raises:

RegistryValidationError – When the modelo or period is not registered, or no revision covers the requested scope.

formulas(modelo, *, period=None, as_of=None)[source]

Return the full formula listing for a resolved modelo revision.

Each row exposes one formula’s target_casilla_id and its complete input dependency set (casillas, bindings, parameters, and relation references), letting contributors inspect what drives a computed casilla without reading the raw registry TOML.

Parameters:

  • modelo (str) – Short numeric identifier for the modelo (e.g. "200").

  • period (str | None) – Optional period narrowing; see describe_modelo for accepted forms. When None, the latest revision is used.

  • as_of (date | None) – Optional calendar date for validity gating.

Return type:

ModeloFormulasReport

Returns:

A ModeloFormulasReport for the resolved revision.

Raises:

RegistryValidationError – When the modelo or period is not registered, or no revision covers the requested scope.