aeat.domain.calculations.registry._workbook_parity module¶

Official AEAT workbook parity discovery and verification backend.

Discovers, scans, and executes AEAT official workbooks against a RegistrySnapshot to verify that registry formulas match the published AEAT calculation workbooks.

class WorkbookScanOptions(per_file_timeout_seconds=15.0, max_formula_refs=500)[source]¶

Bases: object

Controls for bounded workbook discovery.

Parameters:

per_file_timeout_seconds (float)
max_formula_refs (int)

per_file_timeout_seconds: float¶

max_formula_refs: int¶

discover_workbooks(root)[source]¶

Return every official workbook artefact below root.

Return type:: tuple[Path, ...]
Parameters:: root (Path)

scan_workbook(path, *, root, options=None)[source]¶

Scan one workbook and classify formula coverage.

Return type:

WorkbookArtefactReport

Returns:

A WorkbookArtefactReport describing the workbook’s formula coverage.

Parameters:

path (Path)
root (Path)
options (WorkbookScanOptions | None)

inventory_workbook_coverage(root, *, options=None, limit=None, previous_reports=())[source]¶

Scan official workbook artefacts and return WorkbookArtefactReport coverage records.

Return type:

tuple[WorkbookArtefactReport, ...]

Parameters:

root (Path)
options (WorkbookScanOptions | None)
limit (int | None)
previous_reports (Iterable[WorkbookArtefactReport])

detect_workbook_runner()[source]¶

Resolve the local sanctioned spreadsheet recalculation runner.

LibreOffice headless (or, on Windows, Excel COM) is required infrastructure for the workbook parity backend. This resolver does not attempt a graceful fallback: if no runner is locatable, it raises so the caller surfaces the missing dependency instead of silently downgrading evidence quality.

Return type:: WorkbookRunnerAvailability
Returns:: A WorkbookRunnerAvailability describing the detected runner.

run_workbook_with_libreoffice(workbook_path, *, inputs, outputs, executable=None)[source]¶

Run a local XLSX workbook with LibreOffice headless and return outputs.

Return type:

Mapping[TypeAliasType, Decimal | int | str | bool | None]

Parameters:

workbook_path (Path)
inputs (Mapping[WorkbookCellRef, Decimal | int | str | bool])
outputs (Mapping[WorkbookOutputId, WorkbookCellRef])
executable (str | None)

convert_binary_xls_with_libreoffice(workbook_path, *, root, executable=None)[source]¶

Convert one official binary XLS in isolated storage and return a WorkbookConversionReport.

Return type:

WorkbookConversionReport

Parameters:

workbook_path (Path)
root (Path)
executable (str | None)

converted_binary_xls_with_libreoffice(workbook_path, *, root, executable=None)[source]¶

Yield a temporary XLSX converted from official binary XLS input.

Return type:

Iterator[Path]

Parameters:

workbook_path (Path)
root (Path)
executable (str | None)

run_registry_workbook_parity(*, snapshot, synthetic_input, workbook_path, workbook, output_cells, registry_outputs, date_context, relation_values=None, tolerance=Decimal('0'), executable=None)[source]¶

Execute one registry-vs-workbook parity comparison and return a WorkbookParityRunReport.

Parameters:

snapshot (RegistrySnapshot) – The RegistrySnapshot providing the registry formulas to compare.
synthetic_input (SyntheticInputSet) – SyntheticInputSet whose values seed both sides of the comparison (operator inputs and registry bindings).
workbook_path (Path) – Path to the AEAT calculation workbook to execute.
workbook (WorkbookArtefactReport) – WorkbookArtefactReport describing the workbook artefact; must report kind FORMULA_FORM.
output_cells (Mapping[TypeAliasType, WorkbookCellRef]) – Mapping of registry output id to the workbook WorkbookCellRef carrying its computed value.
registry_outputs (Mapping[TypeAliasType, TypeAliasType]) – Mapping of workbook output ids to registry output ids, used to align both sides of the comparison.
date_context (Mapping[str, date]) – Date-axis context forwarded to the registry formula runtime.
relation_values (Mapping[TypeAliasType, Decimal] | None) – Optional resolved registry relation values seeded into the registry runtime.
tolerance (Decimal) – Absolute Decimal tolerance accepted between workbook and registry outputs; defaults to Decimal("0").
executable (str | None) – Optional LibreOffice executable override used when converting binary XLS workbooks.

Return type:

WorkbookParityRunReport

parse_workbook_cell_ref(value, *, default_sheet=None)[source]¶

Parse a workbook cell reference from registry configuration.

Return type:

WorkbookCellRef

Returns:

The parsed WorkbookCellRef with sheet and coordinate fields.

Parameters:

value (str)
default_sheet (str | None)

run_workbook_with_excel_com(workbook_path, *, inputs, outputs)[source]¶

Run a local XLSX workbook with Excel COM and return selected output values.

The workbook is opened read-only, link updates are disabled, alerts are disabled, and it is closed with SaveChanges=False.

Return type:

Mapping[TypeAliasType, Decimal | int | str | bool | None]

Parameters:

workbook_path (Path)
inputs (Mapping[WorkbookCellRef, Decimal | int | str | bool])
outputs (Mapping[WorkbookOutputId, WorkbookCellRef])

compare_registry_to_workbook(*, synthetic_input, workbook, runner, expected_workbook_values, actual_registry_values, output_cells, registry_snapshot_id=None, legal_refs=None, source_refs=None, tolerance=Decimal('0'))[source]¶

Build a deterministic parity comparison report from already-computed values.

Return type:

WorkbookParityRunReport

Returns:

A WorkbookParityRunReport comparing registry output to workbook cells.

Parameters:

synthetic_input (SyntheticInputSet)
workbook (WorkbookArtefactReport)
runner (WorkbookRunnerAvailability)
expected_workbook_values (Mapping[WorkbookOutputId, Decimal | int | str | bool | None])
actual_registry_values (Mapping[WorkbookOutputId, Decimal | int | str | bool | None])
output_cells (Mapping[WorkbookOutputId, WorkbookCellRef])
registry_snapshot_id (str | None)
legal_refs (Mapping[WorkbookOutputId, tuple[LegalRefId, ...]] | None)
source_refs (Mapping[WorkbookOutputId, tuple[SourceRefId, ...]] | None)
tolerance (Decimal)

verify_workbook_backend(root, *, scan_limit=None, per_file_timeout_seconds=10.0, previous_report=None, fail_on_scan_error=True, require_formula_runner=False)[source]¶

Verify the workbook parity backend and return a WorkbookBackendVerificationReport.

Return type:

WorkbookBackendVerificationReport

Parameters:

root (Path)
scan_limit (int | None)
per_file_timeout_seconds (float)
previous_report (WorkbookBackendVerificationReport | None)
fail_on_scan_error (bool)
require_formula_runner (bool)

assert_workbook_scan_clean(report)[source]¶

Raise when discovery could not inspect every workbook artefact.

Return type:: None
Parameters:: report (WorkbookBackendVerificationReport)

assert_formula_workbook_runner_ready(report)[source]¶

Sanity gate: confirm the verification report carries an available runner.

detect_workbook_runner() raises explicitly when no LibreOffice or Excel COM runner can be located, so by the time a WorkbookBackendVerificationReport exists its runner.status must already be “available”. This helper is retained as a documentation surface and a defensive guard against future schema drift; it never fails on a freshly produced report.

Return type:: None
Parameters:: report (WorkbookBackendVerificationReport)