aeat.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, ...]]

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_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_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.