cadrumo.application.calculations.row_set_assembly module

Reassemble pull-side row-set records into typed observations.

The pull adapter captures RowSetEdit Detalle-tab detail rows as a flat tuple of RowSetCellEdit records grouped by the row-set’s grouping key. To consume those rows in the local-store ingest path the codebase needs typed observations of the matching domain shape (for example, WithholdingObservation for modelo 190 / 193, or Modelo720RowObservation for modelo 720). Each assembler looks up binding selectors in the ModeloRevision supplied by the caller.

The assemblers in this module bridge the two: they walk a row-set’s cells, group them by row_index, look up each cell’s binding in the revision to derive its BindingRowSetSelector row_field key, and construct the matching observation type from the per-row field mapping plus a small set of synthesized defaults (source_id, transaction_date) that the Detalle layout doesn’t carry.

Each assembler is self-contained per source kind so the per-modelo field mapping is explicit at the call site rather than threaded through a generic abstraction. The module only reassembles typed observations; persistence stays in the source-specific repository helpers. Adding a new detail-record source adds a new assembler here and a dispatch entry for its row-set grouping.

See also

binding_row_set_selector()

Typed projection used to read row-set selector fields without probing raw selector dictionaries.

RowSetGroupingKind

Closed grouping-axis values consumed by this module’s dispatcher.

registry

Registry-side row-value resolvers that perform the inverse operation for export and sheet population.

assemble_observations_for_grouping(grouping, cells, revision, *, filing_year)[source]

Dispatch the right assembler based on the row-set’s grouping value.

The dispatcher maps registry-authored grouping tokens onto the closed RowSetGroupingKind axis, then returns an AssembledObservations payload whose source-kind discriminator names the typed observation family produced.

Parameters:

  • grouping (str) – Row-set grouping token; selects which assembler runs (withholding / related_party / foreign_asset / atribucion / refund / donativo).

  • cells (Iterable[_RowCellShape]) – Per-row cell shapes consumed by the chosen assembler.

  • revision (ModeloRevision) – The ModeloRevision used to look up typed BindingRowSetSelector projections.

  • filing_year (int) – AEAT filing year carried through to the produced observations’ provenance.

Return type:

tuple[str, tuple[WithholdingObservation, ...]] | tuple[str, tuple[RelatedPartyOperationObservation, ...]] | tuple[str, tuple[Modelo720RowObservation, ...]] | tuple[str, tuple[AtributionMemberObservation, ...]] | tuple[str, tuple[RefundOperationObservation, ...]] | tuple[str, tuple[DonativoDonorObservation, ...]] | tuple[str, tuple[Gasto193Observation, ...]] | tuple[str, tuple[Withholding296Observation, ...]]

Returns a 2-tuple (source_kind, observations) where source_kind identifies the assembler that ran (withholding / related_party / foreign_asset / atribucion / refund / donativo). Raises RegistryValidationError for groupings that have no matching assembler — those are registry layout declarations the application layer cannot consume yet.

assemble_observations_for_snapshot(grouping, cells, snapshot)[source]

Assemble one row set against the authoritative selected registry snapshot.

This is the application command at the row-observation boundary. It deliberately accepts a RegistrySnapshot rather than a caller-selected ModeloRevision so its assembly uses the same law-selected revision and filing year as calculation. It delegates all grouping and row validation to the closed dispatcher.

The returned typed observations are an input to a source-specific resolver or handoff. This command does not infer source ownership, construct row identities or provenance, choose a row-to-casilla materialisation, or write a calculation revision; those facts remain owned by the applicable source slice and the existing calculation source mesh.

Parameters:

  • grouping (str) – Registry-authored row-set grouping token.

  • cells (Iterable[_RowCellShape]) – Cells captured by an inbound surface or another application caller. The command does not claim that any particular adapter is a calculation ingress.

  • snapshot (RegistrySnapshot) – The validated registry snapshot selected for the work context.

Return type:

tuple[str, tuple[WithholdingObservation, ...]] | tuple[str, tuple[RelatedPartyOperationObservation, ...]] | tuple[str, tuple[Modelo720RowObservation, ...]] | tuple[str, tuple[AtributionMemberObservation, ...]] | tuple[str, tuple[RefundOperationObservation, ...]] | tuple[str, tuple[DonativoDonorObservation, ...]] | tuple[str, tuple[Gasto193Observation, ...]] | tuple[str, tuple[Withholding296Observation, ...]]

Returns:

The closed typed observation union produced by the grouping dispatcher.

Raises:

RegistryValidationError – If the grouping is not assembled by the application or any supplied row is invalid.

assemble_withholding_observations(cells, revision, *, filing_year)[source]

Reassemble per-perceptor withholding observations from row-set cells.

Parameters:

  • cells (Iterable[_RowCellShape]) – Row-set cells exported from the calc sheet.

  • revision (ModeloRevision) – The ModeloRevision used to map binding ids to row fields.

  • filing_year (int) – Calendar year of the filing; used to derive default dates.

Return type:

tuple[WithholdingObservation, ...]

Synthesised fields (not carried by the Detalle tab):

  • source_id – derived from the row index for traceability.

  • transaction_date – defaults to the filing-year end since modelo 190 / 193 are annual summaries.

  • country_code – defaults to ES per the AEAT diseno de registro convention for unspecified perceptors.

  • clave is NOT synthesised. A missing clave raises RegistryValidationError because the Modelo 190/193 distinct percepciones count is keyed by perceptor plus clave/subclave; supplied values are validated against RetencionClave.

Each element in the returned tuple is a WithholdingObservation.

Reassemble per-operation related-party observations from row-set cells.

Parameters:

  • cells (Iterable[_RowCellShape]) – Per-row cell shapes the assembler projects into typed observations.

  • revision (ModeloRevision) – The ModeloRevision used to look up typed row-set selector projections.

  • filing_year (int) – AEAT filing year carried through to each observation’s provenance.

Return type:

tuple[RelatedPartyOperationObservation, ...]

Returns a tuple of RelatedPartyOperationObservation instances.

assemble_foreign_asset_observations(cells, revision, *, filing_year)[source]

Reassemble per-asset Modelo 720 rows from row-set cells.

Parameters:

  • cells (Iterable[_RowCellShape]) – Row-set cells exported from the calc sheet.

  • revision (ModeloRevision) – The ModeloRevision used to map binding ids to row fields.

  • filing_year (int) – Calendar year of the filing; used to derive default acquisition dates.

Return type:

tuple[Modelo720RowObservation, ...]

Each element in the returned tuple is a Modelo720RowObservation.

assemble_atribucion_observations(cells, revision, *, filing_year)[source]

Reassemble per-member atribución observations from row-set cells (modelo 184).

Parameters:

  • cells (Iterable[_RowCellShape]) – Per-row cell shapes the assembler projects into typed member observations.

  • revision (ModeloRevision) – The ModeloRevision used to look up typed row-set selector projections.

  • filing_year (int) – AEAT filing year carried through to each observation’s provenance.

Return type:

tuple[AtributionMemberObservation, ...]

Each element in the returned tuple is an AtributionMemberObservation.

assemble_refund_observations(cells, revision, *, filing_year)[source]

Reassemble Modelo 360 refund-operation records from row-set cells.

Parameters:

  • cells (Iterable[_RowCellShape]) – Row-set cells exported from the calc sheet.

  • revision (ModeloRevision) – The ModeloRevision used to map binding ids to row fields.

  • filing_year (int) – Calendar year of the filing; used to derive default operation dates.

Return type:

tuple[RefundOperationObservation, ...]

Each element in the returned tuple is a RefundOperationObservation.

assemble_withholding296_observations(cells, revision, *, filing_year)[source]

Reassemble Modelo 296 perceptor rows from row-set cells.

Parameters:

  • cells (Iterable[_RowCellShape]) – Row-set cells exported from the calc sheet.

  • revision (ModeloRevision) – The ModeloRevision used to map binding ids to row fields.

  • filing_year (int) – Calendar year of the filing; used to derive default dates.

Return type:

tuple[Withholding296Observation, ...]

assemble_gasto193_observations(cells, revision, *, filing_year)[source]

Reassemble Modelo 193 gastos-relationship rows from row-set cells.

Parameters:

  • cells (Iterable[_RowCellShape]) – Row-set cells exported from the calc sheet.

  • revision (ModeloRevision) – The ModeloRevision used to map binding ids to row fields.

  • filing_year (int) – Calendar year of the filing; used to derive default dates.

Return type:

tuple[Gasto193Observation, ...]

Synthesised fields (not carried by the Detalle tab):

  • source_id – derived from the row index for traceability.

  • transaction_date – defaults to the filing-year end since modelo 193 is an annual summary.

assemble_donativo_observations(cells, revision, *, filing_year)[source]

Reassemble Modelo 182 per-donor donativo records from row-set cells.

Parameters:

  • cells (Iterable[_RowCellShape]) – Row-set cells exported from the calc sheet.

  • revision (ModeloRevision) – The ModeloRevision used to map binding ids to row fields.

  • filing_year (int) – Calendar year of the filing; used to derive the default transaction date.

Return type:

tuple[DonativoDonorObservation, ...]

Each element in the returned tuple is a DonativoDonorObservation.