cadrumo.adapters.outbound.google.calc_sheets_pull module

Read operator-edited Sheets cells back into structured records.

Pairs with calc_sheets_apply. The export side materialises a SheetExportPlan as a real Google Sheets workbook; this module reads the operator’s edits back out, validates the workbook is still bound to the RegistrySnapshot the engine compiled it from, and returns typed records the caller can inspect, compute from, or assemble into ledger / filing inputs.

Two safety gates fire before any value is read:

  1. Drive ownership marker — the spreadsheet must carry the appProperties.cadrumo_vault_app=cadrumo marker. Reading values from a spreadsheet that lacks the marker would mix operator content with foreign Drive files and break the cadrumo-vault/ isolation contract.

  2. Registry-SHA and layout-engine metadata match — the spreadsheet’s developer metadata must declare cadrumo_registry_sha = <snapshot.registry_sha> and cadrumo_modelo_id / cadrumo_revision_id / cadrumo_filing_year / cadrumo_period / cadrumo_engine_version matching the caller’s snapshot and live layout compiler. A mismatch means the workbook was compiled against a different registry slice or coordinate layout — casilla identity/layout, formula chains, and bracket tables may have shifted. The pull is refused with a typed error before coordinates are read.

The pull adapter does NOT mutate any local state; it returns a PullResult and leaves applying the edits to the caller.

See also

pull_operator_edits() reads the workbook, compute_from_pull() maps a matching pull into RegistryCalculationResult.

class CalcSheetsPullPreconditionCondition(*values)[source]

Bases: StrEnum

Closed terminal conditions owned by the calculation-sheet pull adapter.

API_CLIENT_AVAILABLE
SPREADSHEET_ID_VALID
OWNERSHIP_METADATA_VALID
OWNERSHIP_ALIGNED
DEVELOPER_METADATA_LIST_VALID
DEVELOPER_METADATA_ENTRY_VALID
DEVELOPER_METADATA_CONSISTENT
SNAPSHOT_ALIGNED
RELATION_SOURCE_REFS_VALID
EDIT_VALUE_FINITE
EDIT_CASILLA_DECLARED
EDIT_CASILLA_INPUT
pull_operator_edits(snapshot, *, spreadsheet_id, credentials)[source]

Read operator-edited cells back from a workbook into typed records.

This is the readback entrypoint behind aeat config google sync calc pull. It verifies the Drive ownership marker, reads developer metadata, classifies metadata against snapshot, reads operator/binding/relation cells plus Detalle row-set blocks, and returns a PullResult.

Parameters:

  • snapshot (RegistrySnapshot) – The RegistrySnapshot the workbook was compiled against. Used to derive the layout (cell addresses for every casilla / binding / relation) and to validate the workbook’s developer-metadata stamps.

  • spreadsheet_id (str) – The Drive file id of the workbook to read. Must already exist and carry the appProperties.cadrumo_vault_app=cadrumo ownership marker.

  • credentials (Credentials) – A google.oauth2.credentials.Credentials-shaped object carrying a refresh + access token with at least the drive.file + spreadsheets scopes.

Return type:

PullResult

Returns:

A PullResult carrying the operator edits, binding edits, relation edits, and the metadata-match verdict. A non-matching stamp is refused before the live layout is derived, so no operator cells are read under coordinates that may have shifted since export.

Raises:
compute_from_pull(snapshot, pull)[source]

Run the local Decimal runtime against a PullResult.

Maps each edit family back to the runtime contract:

  • value flows into runtime inputs, with Decimal("0") substituted for None so the runtime’s “every non-computed casilla has a value” precondition holds.

  • value is routed by the binding’s typed_enum declaration: numeric bindings flow into binding_values as Decimals; enum bindings flow into enum_binding_values as plain strings.

  • value flows into relation_values as Decimals, with Decimal("0") substituted for None.

Refuses to compute when the workbook’s metadata stamps do not match the supplied snapshot (pull.metadata_match != "matches"). The caller is responsible for handling stale workbooks before invoking this helper.

Parameters:

  • snapshot (RegistrySnapshot) – The RegistrySnapshot the workbook was compiled against. Used to derive input casilla identifiers, active relation periods, and the metadata-match gate.

  • pull (PullResult) – The PullResult carrying the operator-edited cells to compute from.

Return type:

RegistryCalculationResult

Returns:

A RegistryCalculationResult produced by calculate_registry_snapshot().

Raises:

OutboundStorageConflictError – When pull does not bind to snapshot by metadata verdict and registry-SHA stamp.