aeat.adapters.outbound.google._calc_sheets_apply module

Live Google Sheets adapter that materialises a SheetExportPlan.

The adapter is the outbound boundary for application.storage.calc_sheets: the engine produces a pure SheetExportPlan, and this module turns the plan into a real spreadsheet inside the operator’s aeat-vault/ Drive folder. Every Drive folder and Sheets spreadsheet the adapter touches carries the appProperties.aeat_vault_app=aeat ownership marker so the operator’s pre-existing Drive content is isolated from app-owned artefacts.

Composition:

  • Drive v3 hosts the parent folder structure aeat-vault/calc-sheets/{modelo}-{period}-{year}/ and the spreadsheet file metadata.

  • Sheets v4 reshapes the spreadsheet: tabs, cell values, formulas, protected ranges, and developer metadata stamping the engine version + registry SHA.

All Google calls route through execute_request(), which raises typed OutboundStorageError subclasses on Drive / Sheets failures. This adapter adds OutboundStorageConflictError when it refuses foreign Drive content.

One-way contract: this adapter is an export mirror only. Google Sheets is never an authority for tax data — the workbook is a human-readable projection of registry-grounded engine output, not an input of record. Operator edits made in the sheet are read back through adapters.outbound.google._calc_sheets_pull, which gates every pull on the Drive ownership marker and a registry-SHA metadata match before the caller may consume them; a workbook that fails either gate is refused, never silently trusted. No path in this package writes Sheets content into the local store, the registry, or an AEAT submission.

class CalcSheetsApplyResult(**data)[source]

Bases: BaseModel

Outcome of one apply cycle.

Returned by apply_export_plan() after a SheetExportPlan has been materialised. Carries the spreadsheet’s Drive file id, its Sheets URL, the aeat-vault/calc-sheets/<...>/ Drive folder id, and the counts of value cells, formula cells, row-set headers, protected ranges, and tabs written during the apply cycle.

Parameters:

  • spreadsheet_id (str)

  • spreadsheet_url (str)

  • folder_id (str)

  • value_cells_written (int)

  • formula_cells_written (int)

  • protected_ranges_written (int)

  • row_set_headers_written (int)

  • tab_count (int)

spreadsheet_id: str
spreadsheet_url: str
folder_id: str
value_cells_written: int
formula_cells_written: int
protected_ranges_written: int
row_set_headers_written: int
tab_count: int
apply_export_plan(plan, *, credentials, root_folder_id)[source]

Materialise a SheetExportPlan as a Google Sheets workbook.

The adapter is idempotent at the spreadsheet level: applying the same plan twice updates the same spreadsheet rather than creating a duplicate, provided the per-period subfolder + spreadsheet title remain stable.

Parameters:
Return type:

CalcSheetsApplyResult

Returns:

A CalcSheetsApplyResult with the spreadsheet location and write counts surfaced by aeat config google sync calc export.

Raises: