aeat.domain.transactions._raw_transaction module

Strict raw transaction boundary models for ingest.

Defines the upstream-immutable records every transaction parser must emit, before they are wrapped in domain.transactions.Transaction:

class SourceFormat(*values)[source]

Bases: StrEnum

Closed taxonomy of supported raw-transaction input formats.

Variables:

  • CSV – Bank statement CSV export.

  • XLSX – Bank statement Excel workbook.

  • OFX – Open Financial Exchange feed.

  • PDF – PDF statement (parsed text layer).

  • MANUAL – Hand-entered transaction.

CSV
XLSX
OFX
PDF
MANUAL
class RawProvenance(**data)[source]

Bases: BaseModel

Per-row provenance pinned to one RawTransaction.

Variables:

  • source_path – Basename of the source file (the filename only, never a resolved absolute path). The file’s content identity is carried by source_sha256; storing only the basename keeps provenance human-readable without baking a host-specific absolute path into the persisted and exported record (which would leak the operator’s directory layout and mutate across operating systems on rehydration).

  • source_sha256 – 64-character lowercase hex SHA-256 digest of the source file.

  • source_row_index – One-based row index within the source file.

  • source_format – Closed SourceFormat discriminator.

  • ingested_at – Timezone-aware UTC timestamp of the ingest run.

  • provider_name – Non-blank logical name of the upstream financial provider.

Parameters:
source_path: Path
source_sha256: str
source_row_index: int
source_format: SourceFormat
ingested_at: datetime
provider_name: str
class RawTransaction(**data)[source]

Bases: BaseModel

Verbatim per-row transaction record emitted by an ingest parser.

Variables:

  • provider_transaction_id – Provider-assigned native identifier; never normalised beyond a strip + non-blank check. This is the bank/feed’s own id for the row, distinct from the content-addressed domain.transactions.Transaction.transaction_id hash the domain derives from it.

  • booked_date – Date the transaction posted to the account.

  • value_date – Optional value date; falls back to booked_date when None.

  • amount – Non-negative magnitude decimal.Decimal in currency. Flow direction is carried solely by domain.transactions.Transaction.direction; the sign is never stored on the amount.

  • currency – Three-letter ISO 4217 currency code, uppercase.

  • counterparty – Optional counterparty descriptor; trimmed and collapsed to None when blank.

  • description – Non-blank narrative.

  • provenance – Per-row RawProvenance metadata.

  • raw_fields – Frozen mapping of original source columns to stringified values, preserved verbatim for audit.

Parameters:
provider_transaction_id: str
booked_date: date
value_date: date | None
amount: Decimal
currency: str
counterparty: str | None
description: str
provenance: RawProvenance
raw_fields: Mapping[str, str]
property display_counterparty: str

Return counterparty coerced to an empty string when absent.

CSV importers may produce RawTransaction rows whose counterparty column is blank; _normalize_counterparty() collapses those to None so the domain model carries the true absent signal. The CLI ledger surface (list / view / payable / collectible) renders the field through a typed payload that expects str rather than str | None so the display layer can keep its column contract uniform. Routing the coercion through this property removes three identical raw.counterparty or "" call-site repeats and centralises the decision so future display tweaks (placeholder strings, ellipses) land in one place.