aeat.adapters.outbound.aeat.export._formats._deserialise module¶

Fichero-BOE deserialiser for explicit fixed-width specs.

Round-trip inverse of adapters.outbound.aeat.export._formats._serialise.serialise(). Takes a fichero-BOE byte payload plus a RecordFieldSpec tuple and yields a ParsedRecord carrying the per-field values (as strings, datetime.date for date fields, or decimal.Decimal for currency) plus metadata.

Use this module when the caller already has adapter-local RecordFieldSpec or SegmentSpec declarations and needs a byte-level round-trip check. The application export-verification flow parses registry layouts through domain.calculations.registry.parse_export_payload() so it can compare a file against the canonical domain.calculations.registry.ExportLayoutDefinition.

See also

adapters.outbound.aeat.export._formats._serialise.serialise(): Explicit-spec serialiser that produces the bytes parsed here.
domain.calculations.registry.ParsedExportPayload: Registry-level parsed payload used by the application verifier.

class ParsedRecord(**data)[source]¶

Bases: BaseModel

Typed result of parsing a fichero-BOE record.

Strict / frozen / extra="forbid" per the boundary-record mandate. Each field value is keyed by field_id; currency fields also appear in casilla_values keyed by casilla_id for easy cross-reference against application.filing.ModeloDraft.

Variables:

field_values – Every field_id mapped to its parsed value (strings, datetime.date, or decimal.Decimal).
casilla_values – Casilla-keyed currency values; a subset of field_values filtered to fields with a non-None casilla_id.
raw_length – Byte length of the parsed content, excluding the optional CRLF terminator.

Parameters:

field_values (Mapping[str, str | Decimal | date])
casilla_values (Mapping[CasillaId, Decimal])
raw_length (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])])

See also

RecordFieldSpec: Field declarations that drive the parser.
domain.calculations.registry.ParsedExportPayload: Registry-level parser result for application export verification.

field_values: Mapping[str, str | Decimal | date]¶: Every field_id mapped to its parsed value.

casilla_values: Mapping[CasillaId, Decimal]¶: Casilla-keyed currency values (subset of field_values).

raw_length: Annotated[int, Field(ge=0)]¶: Byte length of the parsed content (excluding CRLF).

deserialise(payload, *, specs, encoding, total_length)[source]¶

Parse a fichero-BOE byte payload into a ParsedRecord.

Parameters:

payload (bytes) – Full on-wire byte sequence (content + optional CRLF).
specs (tuple[RecordFieldSpec, ...]) – The ordered RecordFieldSpec tuple describing the fixed-width layout.
encoding (Literal['cp1252', 'iso-8859-1', 'iso-8859-15']) – Wire encoding matching the serialiser’s choice.
total_length (int) – Expected content-byte count (excludes CRLF).

Return type:

Returns:

A ParsedRecord carrying field and casilla values.

Raises:

AeatExportFormatError – On length mismatch, literal mismatch, or decode errors (unparseable date, non-ASCII currency, etc.).

class ParsedEnvelope(**data)[source]¶

Bases: BaseModel

Result of parsing a multi-segment fichero-BOE envelope.

The envelope-level analogue of ParsedRecord. Each segment’s ParsedRecord is addressable by segment_id so callers can diff a specific page without walking every segment.

Variables:

segments – Per-segment parsed records keyed by segment_id.
merged_casilla_values – Flat view of every casilla across every segment. Convenient for verification paths that compare a filing against AEAT’s record per casilla_id without caring which envelope segment the value lived in.
merged_field_values – Flat view of every field_id across every segment. Envelope-level headers surface here so CLI consumers can present them without walking segments. Field IDs that collide across segments (for example a repeated envelope marker repeated in header and trailer) must carry the same value; divergent collisions raise at deserialisation time, mirroring the casilla-level contract.

Parameters:

segments (Mapping[str, ParsedRecord])
merged_casilla_values (Mapping[CasillaId, Decimal])
merged_field_values (Mapping[str, str | Decimal | date])

See also

SegmentSpec: Segment declarations consumed by deserialise_envelope().
domain.calculations.registry.parse_export_payload(): Registry-level parser for application export verification.

segments: Mapping[str, ParsedRecord]¶: Per-segment parsed records keyed by segment_id.

merged_casilla_values: Mapping[CasillaId, Decimal]¶: Flat view of every casilla across every segment.

merged_field_values: Mapping[str, str | Decimal | date]¶: Flat view of every field_id across every segment.

deserialise_envelope(payload, *, segments, encoding)[source]¶

Parse a multi-segment fichero-BOE envelope.

Consumes the payload in segment order, slicing total_length bytes per segment. The final CRLF is optional (the caller may have stripped it before hashing).

Parameters:

payload (bytes) – Concatenated segment bytes with an optional trailing CRLF.
segments (tuple[SegmentSpec, ...]) – Ordered tuple of SegmentSpec describing each segment’s layout.
encoding (Literal['cp1252', 'iso-8859-1', 'iso-8859-15']) – Wire encoding shared across the envelope.

Return type:

ParsedEnvelope

Returns:

A ParsedEnvelope with per-segment records plus merged casilla and field views.

Raises:

AeatExportFormatError – If the payload length does not match the sum of segment lengths, any segment fails its shape check, or a casilla / field id collides with a divergent value across segments.