cadrumo.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 cadrumo-vault/ Drive folder. Every Drive folder and Sheets spreadsheet the adapter touches carries the appProperties.cadrumo_vault_app=cadrumo ownership marker so the operator’s pre-existing Drive content is isolated from app-owned artefacts.

Composition:

  • Drive v3 hosts the parent folder structure cadrumo-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 CalcSheetsApplyPreconditionCondition(*values)[source]

Bases: StrEnum

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

API_CLIENT_AVAILABLE
ROOT_FOLDER_ID_VALID
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 cadrumo-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:

data (Any)

spreadsheet_id: str
spreadsheet_url: str
folder_id: str
value_cells_written: NonNegativeInt
formula_cells_written: NonNegativeInt
protected_ranges_written: NonNegativeInt
row_set_headers_written: int
tab_count: int
class CalcSheetsExportPreview(**data)[source]

Bases: BaseModel

What apply_export_plan() would clear and (re)write, computed with no write call.

Returned by preview_export_plan(), which reads Drive and Sheets state only: it never creates a folder or a spreadsheet, never backfills an ownership marker on a fresh lookup, and never issues a batchClear or batchUpdate write. The three facts a dry-run promises per the decision record: the per-tab ranges the apply would clear, how many value cells would actually change against the current read-back, and how many formula cells the apply would (unconditionally) rewrite — the live apply always rewrites every formula cell it carries rather than diffing formula text against a computed result, so this preview reports the same count rather than inventing a comparison the real write does not make either.

folder_id, spreadsheet_id and spreadsheet_url are None only when no matching target exists yet: the first export for a given modelo, period and year has nothing on Drive to look up, so every value cell previews as new content and there is nothing to clear.

Parameters:

data (Any)

spreadsheet_exists: bool
folder_id: str | None
spreadsheet_id: str | None
spreadsheet_url: str | None
ranges_to_clear: tuple[str, ...]
value_cells_changed: NonNegativeInt
value_cells_unchanged: NonNegativeInt
formula_cells_to_write: NonNegativeInt
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:

  • plan (SheetExportPlan) – The pure SheetExportPlan produced by build_export_plan().

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

  • root_folder_id (str) – The operator’s Drive root folder id (the same folder GoogleDriveProvider uses for the ciphertext mirror).

Return type:

CalcSheetsApplyResult

Returns:

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

Raises:
preview_export_plan(plan, *, credentials, root_folder_id)[source]

Preview what apply_export_plan() would clear and (re)write, writing nothing.

Resolves the same cadrumo-vault/calc-sheets/{modelo}-{period}-{year}/ target apply_export_plan() resolves, through the SAME read-only lookup (_find_folder() / _find_spreadsheet()) — never the create path — so a preview cannot disagree with a real apply about which spreadsheet it is describing. No folder or spreadsheet is created, and neither values.batchClear nor values.batchUpdate nor spreadsheets.batchUpdate is ever called.

A target that does not yet exist previews via _new_target_export_preview(): every cell is new content and there is nothing to clear, because creating the target to answer the question would be exactly the write a preview exists to avoid.

Parameters:
Return type:

CalcSheetsExportPreview

Returns:

A CalcSheetsExportPreview describing what a real apply would touch.

Raises:

  • OutboundStorageValidationError – When root_folder_id is blank, or an app-owned Drive entry carries no usable id.

  • OutboundStorageError – When Drive or Sheets rejects a read request, or the adapter finds a same-named Drive entry that is not app-owned — the same refusal a real apply would raise at the same lookup.