aeat.application.storage.calc_sheets._engine module

Engine driver that compiles a RegistrySnapshot into a SheetExportPlan.

The engine walks every casilla, binding, and parameter declared in the ModeloRevision embedded in the snapshot and maps each to a typed cell or range in the generated workbook plan.

The result is renderer-neutral: Google Sheets and offline XLSX renderers both consume the same SheetExportPlan. The engine stamps registry identity, formula provenance, relation prefills, styling facets, and row-set layout; the ledger-evidence facet is supplied separately when the caller has bundled aeat.domain.modelos._ledger_filing_snapshot.LedgerFilingEvidence.

registry_sha(snapshot)

Stable identity hash of the calculation surface in this RegistrySnapshot.

The hash covers casilla ids, formula expressions, and parameter values. Two snapshots that produce the same calculation graph yield the same SHA; any registry edit yields a different SHA. The pull adapter uses this to refuse merges that would silently cross a registry boundary.

Return type:

str

Parameters:

snapshot (RegistrySnapshot)

build_export_plan(snapshot, *, operator_inputs=None, relation_values=None, relation_resolver=None)

Walk a registry snapshot and produce a complete SheetExportPlan.

The plan is a pure function of snapshot, operator_inputs, and the resolved relation values: workbook renderers write exactly what is in the plan, no more, no less. Two engine runs with the same inputs yield the same plan modulo the exported_at timestamp.

Parameters:

• snapshot (RegistrySnapshot) – The validated RegistrySnapshot to export.

• operator_inputs (OperatorInputs | None) – Optional pre-populated operator-input values for the Entradas tab. Casillas not supplied here render as blank cells the operator fills in by hand.

• relation_values (RelationValues | None) – Optional pre-resolved cross-revision aggregations mirrored into the Tarifas tab. Required when the revision’s formulas consume relation leaves (annual roll-ups like modelo 190 over modelo 111); when absent and relation_resolver is also unset, the engine emits blank cells the operator must populate before the Sheet’s formulas yield correct values.

• relation_resolver (Callable[[RegistrySnapshot], RelationValues] | None) – Optional callable that resolves the snapshot’s relations from a structured source (typically the local observation store via aeat.application.calculations.resolve_relations_from_local_store). When supplied AND relation_values is None, the engine invokes the resolver and stamps each resolved value’s provenance onto the workbook so the pull adapter can detect stale prefills. Explicit relation_values take precedence over the resolver.

Return type:

SheetExportPlan

Returns:

A complete SheetExportPlan ready for the Google apply adapter or offline workbook serializer.

collect_row_sets(revision)

Collect row-producer bindings into per-grouping SheetRowSet blocks.

Parameters:

revision (ModeloRevision) – The ModeloRevision whose bindings are scanned for row-producer declarations.

Return type:

tuple[SheetRowSet, ...]

Walks revision.bindings for invoice / counterpart bindings with aggregation = { op = "rows" }, groups them by selector.grouping (typically operator_clave or operator_clave_period), and lays them out as stacked header+data blocks in the Detalle tab. Each grouping occupies a contiguous column block; groupings stack vertically with a one-row gap between blocks. The pull adapter reads row data from first_data_row downwards.

Each element in the returned tuple is a SheetRowSet.