aeat.application.storage.calc_sheets._layout module

Layout planner mapping every casilla, binding, and parameter onto a Sheets cell address.

Operates on a ModeloRevision.

The mapping is a pure function of the revision (and an optional filing date for temporal bracket filtering). Two engine runs over the same revision yield the same layout, and the pull adapter can therefore round-trip a workbook back into casilla-id space without consulting the source registry at runtime.

Layout strategy

  • The Entradas tab lists every operator-input casilla (input_kind in {“manual”, “bound”, “informational”}). Each row carries {section, display_number, label, value} with the value cell anchored in column D. Bindings the formulas reference appear in their own rows below the casilla rows so the operator can review and override pre-resolved values.

  • The Cálculos tab lists every computed casilla. Each row carries {section, display_number, label, formula_value} with the formula cell anchored in column D.

  • The Tarifas tab mirrors every parameter referenced (directly or via a lookup_bracket_by_ccaa dispatch table) by a computed casilla’s formula expression. Scalar parameters occupy a single cell; bracket_table parameters occupy a header row plus one row per temporally-active bracket entry.

Bracket tables filter out entries that are not valid on the supplied bracket_filter_date so the row sequence emitted to Tarifas matches the runtime’s _resolve_bracket selection exactly. That keeps MATCH(_, lower_bound, 1) honest in the translator’s closed-form lookup_bracket expansion.

class BracketRanges(**data)[source]

Bases: BaseModel

A1 ranges for the lower-bound, fixed-addition, and marginal-rate columns of one bracket-table parameter.

These ranges occupy the Tarifas tab. The translator’s lookup_bracket handler resolves a bracket lookup against them via:

INDEX(fixed_addition, MATCH(base, lower_bound, 1)) + INDEX(marginal_rate, MATCH(base, lower_bound, 1)) * (base - INDEX(lower_bound, MATCH(base, lower_bound, 1)))

The ranges always hold one row per bracket entry that is temporally active for the snapshot’s filing date — out-of-window entries are filtered before layout so the sort-1 MATCH contract stays clean.

Parameters:

  • parameter (ParameterId)

  • lower_bound (str)

  • fixed_addition (str)

  • marginal_rate (str)

  • row_count (int)

parameter: ParameterId
lower_bound: str
fixed_addition: str
marginal_rate: str
row_count: int
class SheetLayout(**data)[source]

Bases: BaseModel

Resolved cell addresses for every casilla, binding, and parameter.

Parameters:
revision_id: RevisionId
entradas_cells: Mapping[CasillaId, SheetCellAddress]
calculos_cells: Mapping[CasillaId, SheetCellAddress]
binding_cells: Mapping[BindingId, SheetCellAddress]
date_binding_cells: Mapping[BindingId, SheetCellAddress]
filing_year: int
parameter_cells: Mapping[ParameterId, ParameterCell]
relation_cells: Mapping[RelationId, SheetCellAddress]
entradas_rows: tuple[_CasillaRow, ...]
calculos_rows: tuple[_CasillaRow, ...]
binding_rows: tuple[_BindingRow, ...]
tariff_anchors: Mapping[ParameterId, SheetCellAddress]
bracket_ranges: Mapping[ParameterId, BracketRanges]
bracket_entries: Mapping[ParameterId, tuple[BracketEntry, ...]]
address_for(casilla_id)[source]

Resolve a casilla reference to the SheetCellAddress holding its value.

Computed casillas resolve to their Calculos cell; input casillas resolve to their Entradas cell. The translator uses this to compile a FormulaExpression casilla leaf into an A1 reference.

Return type:

SheetCellAddress

Parameters:

casilla_id (CasillaId)

address_for_binding(binding)[source]
Return type:

SheetCellAddress

Parameters:

binding (BindingId)

address_for_date_binding(binding)[source]
Return type:

SheetCellAddress

Parameters:

binding (BindingId)

address_for_relation(relation)[source]
Return type:

SheetCellAddress

Parameters:

relation (RelationId)

plan_layout(revision, *, bracket_filter_date=None, excluded_casilla_ids=frozenset({}))[source]

Plan tab + row + column addresses for every casilla and parameter.

Parameters:

  • revision (ModeloRevision) – The validated ModeloRevision to lay out.

  • bracket_filter_date (date | None) – When supplied, bracket-table parameters are filtered to entries temporally valid on this date so the Tarifas rows the engine emits match the registry runtime’s _resolve_bracket selection. When None, every bracket entry is emitted in lower_bound order.

  • excluded_casilla_ids (frozenset[TypeAliasType]) – Casillas to omit from the layout entirely. The engine uses this to drop internal_only computed casillas whose custom runtime-dispatch formula op has no closed-form Sheets translation (the M303 régimen-simplificado módulos advisory-support figures): they are absent from the AEAT official Diseño de Registros and cannot be rendered as a live spreadsheet formula, so they do not belong in the official-structure workbook.

Return type:

SheetLayout

Returns:

A SheetLayout carrying cell addresses for every casilla, binding, parameter, and relation defined on the revision.