aeat.adapters.inbound.financial.providers._csv module

CSV financial provider with bank-layout-aware parsing.

Provides CsvProvider, an implementation of FinancialProvider that ingests bank CSV exports for the BBVA, Santander, CaixaBank and Revolut layouts. Each layout is described by a frozen CsvBankLayout carrying the header aliases, date-format hint, and decimal-separator hint the parser needs.

Successful rows become ParsedLedgerRow objects: the stored RawTransaction carries an absolute amount and provenance, while TransactionDirection records the source flow.

class CsvColumnMap(**data)[source]

Bases: BaseModel

Alias sets for one bank CSV layout.

Each tuple lists the lower-cased header strings the parser will treat as equivalent for the corresponding logical column. The _layout_score() helper scores a candidate header row by the number of these aliases it satisfies.

Variables:

  • booked_date – Aliases for the posting date column.

  • value_date – Aliases for the value date column.

  • amount – Aliases for the signed amount column.

  • currency – Aliases for the optional currency column.

  • description – Aliases for the free-form description column.

  • counterparty – Aliases for the optional counterparty column.

  • external_id – Aliases for the optional external transaction id.

Parameters:
booked_date: tuple[str, ...]
value_date: tuple[str, ...]
amount: tuple[str, ...]
direction: tuple[str, ...]
currency: tuple[str, ...]
description: tuple[str, ...]
counterparty: tuple[str, ...]
external_id: tuple[str, ...]
class CsvBankLayout(**data)[source]

Bases: BaseModel

Named bank CSV layout supported by the provider.

Variables:

  • bank_name – Human-readable bank identifier embedded in synthetic transaction ids and detection diagnostics.

  • columns – Header aliases for every logical column.

  • day_first_dates – Whether the bank prints dates in DD/MM/YYYY (the European default) or YYYY-MM-DD.

  • decimal_separator – Decimal separator the bank uses; , for Spanish banks, . for Revolut.

Parameters:
bank_name: str
columns: CsvColumnMap
day_first_dates: bool
decimal_separator: Literal[',', '.']
CSV_LAYOUTS: tuple[CsvBankLayout, ...]

Ordered tuple of bank layouts the CSV provider will try to match.

class ParsedTabularTransactionRow(provider_transaction_id, booked_date, value_date, amount, direction, currency, description, counterparty)[source]

Bases: object

Typed projection shared by CSV and spreadsheet bank-layout rows.

Parameters:
provider_transaction_id: str
booked_date: date
value_date: date | None
amount: Decimal
direction: TransactionDirection | None
currency: str
description: str
counterparty: str | None
class CsvProvider[source]

Bases: FinancialProvider

Ingest raw transactions from bank CSV exports.

Detects the bank layout by scoring the first ten rows of the decoded text against every entry in CSV_LAYOUTS, then streams the data rows through build_raw_transaction(). The decoder honours the financial_default_csv_encoding setting as the preferred encoding before falling back to a fixed UTF-8 / CP-1252 / ISO-8859-1 sequence.

CSV layouts can provide either a source-signed amount or an explicit direction column. The adapter resolves that flow once at the parse boundary and emits magnitude-only raw transactions.

name: ClassVar[str]
supported_extensions: ClassVar[frozenset[str]]
source_format: ClassVar[SourceFormat]
verification_source: ClassVar[CorpusVerificationSource]
provisional_pending_specimen: ClassVar[bool]
validate_source(path)[source]

Validate CSV structure, encoding, and layout support.

Return type:

ProviderValidation

Returns:

A ProviderValidation with the validation outcome.

Parameters:

path (Path)

ingest(path)[source]

Yield ParsedLedgerRow records (magnitude + direction) from the CSV source.

Return type:

Iterator[ParsedLedgerRow]

Parameters:

path (Path)