aeat.adapters.outbound.aeat.export._formats._serialise module

Fichero-BOE serialiser for explicit fixed-width specs.

The serialiser is format-generic: one serialise() drives every caller-supplied layout represented as a validated tuple of RecordFieldSpec entries. The caller supplies:

• field layout, validated before use.

• content byte length excluding the CRLF terminator.

• wire encoding for the payload.

• required header field_id values the draft MUST provide.

The caller passes casilla values plus a headers mapping for metadata fields (identity, year, period, and so on). CRLF terminator ownership stays with this function; the per-field encoders in adapters.outbound.aeat.export._formats._record_spec do not emit line endings.

The active application export path renders domain.calculations.registry.ExportLayoutDefinition records through application.filing.export_draft(); this module is the lower-level explicit-spec serialiser paired with adapters.outbound.aeat.export._formats._deserialise.deserialise().

See also

domain.calculations.registry.ExportRecordDefinition

Canonical registry record declaration consumed by the application export renderer.

adapters.outbound.aeat.export.AeatExportFormatError

Error raised for fixed-width layout and value violations.

HeaderValue

strings for text/numeric fields; dates for DATE fields.

Type:

Header values

serialise(*, casilla_values, headers, specs, encoding, total_length, required_field_ids=frozenset({}))

Emit a fichero-BOE payload for one filing draft.

Parameters:

• casilla_values (Mapping[TypeAliasType, Decimal]) – Per-casilla numeric values. Missing casillas default to decimal.Decimal zero — AEAT expects every CURRENCY field filled, zero-padded when not declared.

• headers (Mapping[str, str | date]) – Metadata fields keyed by field_id. Dates must be datetime.date instances; other scalar text and numeric fields are strings.

• specs (tuple[RecordFieldSpec, ...]) – Ordered tuple of adapters.outbound.aeat.export._formats._record_spec.RecordFieldSpec entries.

• encoding (Literal['cp1252', 'iso-8859-1', 'iso-8859-15']) – Wire encoding for the payload (typically "cp1252").

• total_length (int) – Expected content-byte count, excluding CRLF.

• required_field_ids (frozenset[str]) – field_id values the caller guarantees must be present in headers; missing required fields raise AeatExportFormatError before any bytes are emitted.

Return type:

bytes

Returns:

The total_length + 2 byte payload (content + CRLF).

Raises:

AeatExportFormatError – On missing required headers, on serialised-length mismatch, or from the individual encoders on overflow or non-encoding-compatible characters.

serialise_envelope(*, casilla_values, headers, segments, encoding, required_field_ids=frozenset({}))

Emit a multi-segment fichero-BOE envelope.

Some AEAT record layouts use an XML-tagged envelope of ordered segments rather than a flat record. This helper serialises each segment via serialise() and concatenates the results. The CRLF terminator is appended ONCE at the end.

Parameters:

• casilla_values (Mapping[TypeAliasType, Decimal]) – Per-casilla values shared across every segment.

• headers (Mapping[str, str | date]) – Metadata header fields shared across every segment. Individual segments reference whichever headers they declare; unused headers are ignored per-segment.

• segments (tuple[SegmentSpec, ...]) – Ordered tuple of adapters.outbound.aeat.export._formats._record_spec.SegmentSpec to emit. Callers supplying the envelope decide which optional segments are present.

• encoding (Literal['cp1252', 'iso-8859-1', 'iso-8859-15']) – Wire encoding shared across segments.

• required_field_ids (frozenset[str]) – Fail-fast check applied ONCE at envelope start; individual segments do not re-check.

Return type:

bytes

Returns:

The full envelope byte payload with a single trailing CRLF.

Raises:

AeatExportFormatError – Same conditions as serialise(), plus any per-segment width mismatch.