cadrumo.adapters.inbound.financial.providers.base module

Shared provider contracts and ingest helpers.

Defines the FinancialProvider ABC together with the validation record ProviderValidation, the provider error hierarchy (FinancialProviderError, InvalidFinancialSourceError, UnsupportedFinancialSourceError, BankStatementParseError), and the parsing / provenance helpers concrete providers reuse to emit RawTransaction records with consistent RawProvenance.

Providers emit ParsedLedgerRow objects: the source sign is consumed at the adapter boundary into a TransactionDirection, while the stored raw amount is an absolute magnitude.

Provider corpus discipline

Every concrete FinancialProvider subclass must declare two class-level corpus attributes:

verification_source

A string literal describing how the corpus fixtures were obtained:

• "real_bank_corpus_pdf" — sanitised PDFs from real bank statements held by the operator.

• "synthetic_from_bank_published_text" — PDFs generated from sanitised text dumps published in third-party open-source corpora (e.g., portfolio-performance); structure matches real layouts but origin is reconstructed.

• "no_corpus" — no corpus is currently held. The provider must also set provisional_pending_specimen = True.

provisional_pending_specimen

True when no real-corpus PDF has been parsed to confirm the provider produces correct output. Providers with no_corpus must set this True; providers with a confirmed corpus round-trip set it False.

The test suite in test_pdf_n26.py and the detection-invariant test enforce these attributes at collection time so a newly enrolled provider cannot silently ship without the declaration.

CorpusVerificationSource

Allowed values for FinancialProvider.verification_source.

alias of Literal[‘real_bank_corpus_pdf’, ‘synthetic_from_bank_published_text’, ‘no_corpus’]

exception FinancialProviderError(message=None, *, context=None, translated_message=None)

Bases: CadrumoError

Base error raised by financial-ingest providers.

Subclasses core.errors.hierarchy.CadrumoError so the application layer can catch every provider failure with one except clause.

Parameters:

• message (str | None)

• context (Mapping[str, object] | None)

• translated_message (str | None)

Return type:

None

code

exception FinancialProviderConfigError(message=None, *, context=None, translated_message=None)

Bases: FinancialProviderError

Raised when a FinancialProvider subclass declaration is invalid.

Fired by __init_subclass__ when the concrete provider class is missing or carries an invalid verification_source or provisional_pending_specimen class variable.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• translated_message (str | None)

Return type:

None

code

exception UnsupportedFinancialSourceError(message=None, *, context=None, translated_message=None)

Bases: FinancialProviderError

Raised when no provider can interpret a source document.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• translated_message (str | None)

Return type:

None

code

exception InvalidFinancialSourceError(message=None, *, context=None, translated_message=None)

Bases: FinancialProviderError

Raised when a source document is unreadable or structurally invalid.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• translated_message (str | None)

Return type:

None

code

exception FinancialValidationError(message=None, *, context=None, translated_message=None)

Bases: FinancialProviderError

Raised when a specific field (date, amount) fails domain validation.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• translated_message (str | None)

Return type:

None

code

exception BankStatementParseError(message=None, *, missing=(), malformed=(), ambiguous=(), coverage=None)

Bases: FinancialProviderError

Raised when a bank statement PDF cannot be fully parsed.

Carries structured attributes that allow callers to assert on the failure kind without parsing the message string — the same pattern as DeclaracionParseError and JustificanteParseError.

This error is appropriate for PDF-specific parse failures where the document was accepted by format detection but extraction produced incomplete or malformed results. Low-level structural failures (file unreadable, wrong bank marker) continue to raise InvalidFinancialSourceError.

Variables:

• missing – Tuple of field or row identifiers that produced no match in the PDF text (e.g. a required header field absent).

• malformed – Tuple of field identifiers whose captured value could not be coerced to the target type (date, amount, currency).

• ambiguous – Tuple of field identifiers that matched more than one region in the PDF.

• coverage – Fraction of expected transaction rows successfully extracted (Decimal). None when the error is not a coverage failure.

Parameters:

• message (str | None)

• missing (tuple[str, ...])

• malformed (tuple[str, ...])

• ambiguous (tuple[str, ...])

• coverage (Decimal | None)

Return type:

None

code

class ProviderValidation(**data)

Bases: BaseModel

Typed validation result returned before ingest.

Variables:

• is_valid – Whether the source document can be ingested.

• warnings – Human-readable warning strings; non-empty even when is_valid is True (e.g., a missing currency column).

• detected_encoding – Provider-specific encoding marker, when applicable (CSV byte decoding, OFX parser tag, etc.).

• detected_dialect – Compact provider-specific dialect / layout description used in operator diagnostics.

• unavailable_optional_extra – Machine identity of the optional extra whose absence made this provider unusable, carried as the canonical extra / import_name / importable fact triple rather than an installation instruction. Present only when a provider declined because its extra is not installed; the operator-facing recovery is resolved downstream from these facts, never rendered here.

Parameters:

data (Any)

is_valid: bool

warnings: tuple[str, ...]

detected_encoding: str | None

detected_dialect: str | None

unavailable_optional_extra: Mapping[str, str | bool] | None

class FinancialProvider

Bases: ABC

Abstract base class for file-backed raw transaction providers.

Concrete subclasses must declare name, supported_extensions, source_format, verification_source, and provisional_pending_specimen and implement ingest() plus validate_source(). The shared build_provenance() helper centralises RawProvenance construction so every emitted RawTransaction carries consistent provenance metadata.

See the module docstring for the corpus discipline contract that verification_source and provisional_pending_specimen jointly enforce.

Variables:

• name – Stable provider identifier embedded in synthetic transaction ids and provenance records.

• supported_extensions – Lowercase file extensions (including the leading dot) the provider accepts.

• source_format – Source-format enum used for provenance.

• verification_source – Corpus provenance declaration; one of "real_bank_corpus_pdf", "synthetic_from_bank_published_text", or "no_corpus".

• provisional_pending_specimen – True when no confirmed corpus round-trip has been performed for this provider. Providers with verification_source = "no_corpus" must set this True.

name: ClassVar[str]

supported_extensions: ClassVar[frozenset[str]]

source_format: ClassVar[SourceFormat]

verification_source: ClassVar[Literal['real_bank_corpus_pdf', 'synthetic_from_bank_published_text', 'no_corpus']]

provisional_pending_specimen: ClassVar[bool]

can_handle(path)

Return whether the provider is a plausible match for path.

Parameters:

path (Path) – Candidate source document.

Return type:

bool

Returns:

True if path exists and its extension is in supported_extensions. Content sniffing is left to validate_source() and detect_provider().

abstractmethod ingest(path)

Yield parsed ledger rows from path.

Implementations must produce one ParsedLedgerRow per source row (via build_raw_transaction()), each carrying a magnitude domain.transactions.raw_transaction.RawTransaction plus the domain.transactions.enums.TransactionDirection derived from the source sign at the parse boundary, with provenance built via build_provenance().

Parameters:

path (Path) – Source document to ingest.

Return type:

Iterator[ParsedLedgerRow]

Returns:

An iterator that yields one parsed ledger row per source row.

Raises:

InvalidFinancialSourceError – When the document cannot be parsed or a row is malformed.

abstractmethod validate_source(path)

Validate path before ingesting it.

Parameters:

path (Path) – Candidate source document.

Return type:

ProviderValidation

Returns:

A ProviderValidation describing whether the document is ingestable and surfacing any warnings.

build_provenance(*, path, source_sha256, source_row_index)

Create the common provenance record for one source row.

Parameters:

• path (Path) – Source document path; resolved to its absolute form before storage.

• source_sha256 (str) – Lowercase SHA-256 of the source bytes.

• source_row_index (int) – 1-based row index within the source.

Return type:

RawProvenance

Returns:

A RawProvenance record stamped with the current UTC ingestion timestamp and the provider’s name / source_format.

describe_dialect(dialect)

Return a compact human-readable dialect description.

Return type:

str

Parameters:

dialect (type[Dialect])

normalize_header(value)

Normalize a column header for alias matching.

Underscores fold to spaces: a tool-exported statement writes value_date where a bank writes Value Date, and both name the same column.

Return type:

str

Parameters:

value (str)

archive_cell_text(value)

Coerce a source value to a stripped string for raw-field storage.

Binds the raw-field archive’s rendering policy — a booking stamp is stored ISO-8601 rather than however str() happens to print it — onto the shared cell coercer, so the twelve call sites in this package state the policy once instead of each carrying the keyword.

Return type:

str

Parameters:

value (object)

parse_date_value(value, *, day_first=True, label='date')

Parse a bank-statement date or date-time into a date.

Return type:

date

Parameters:

• value (object)

• day_first (bool)

• label (str)

parse_amount_value(value, *, decimal_separator=None)

Parse bank-export numeric text into Decimal without float coercion.

Float coercion is forbidden because bank exports carry exact cents; intermediate floats would silently round (e.g., 1234.56 → 1234.5599999...). The parser preserves the sign convention of the source — bracketed (123.45) and trailing-minus 123.45- both decode to a negative decimal.Decimal.

Parameters:

• value (object) – Raw cell value; accepted as Decimal, int, float (re-parsed via str), or text.

• decimal_separator (Optional[Literal[<DecimalSeparator.COMMA: ','>, <DecimalSeparator.PERIOD: '.'>]]) – Optional explicit decimal separator. When omitted, the parser infers it from the rightmost occurrence of , or . in the text.

Return type:

Decimal

Returns:

A Decimal preserving the printed precision and sign.

Raises:

FinancialValidationError – When the value is empty, carries scientific notation (which sanitisation would silently rewrite into a plausible wrong magnitude rather than fail), or cannot be parsed.

synthesize_transaction_id(*, provider_name, source_sha256, source_row_index)

Build a deterministic synthetic transaction identifier.

Return type:

str

Parameters:

• provider_name (str)

• source_sha256 (str)

• source_row_index (int)

class ParsedLedgerRow(**data)

Bases: BaseModel

One parsed source row: a magnitude RawTransaction + its flow.

The provider observes the bank export’s sign (or native debit/credit signal) once, at the parse boundary, to choose a TransactionDirection; it then stores the absolute magnitude on raw and discards the sign. Downstream the import action carries direction straight onto the Transaction, never re-deriving flow from a sign that no longer exists.

Variables:

• raw – The verbatim per-row RawTransaction carrying the non-negative magnitude amount.

• direction – The authoritative flow direction derived from the source sign at the parse boundary.

Parameters:

data (Any)

raw: RawTransaction

direction: TransactionDirection

direction_from_signed_amount(signed_amount)

Map a source-signed amount to the authoritative TransactionDirection.

A negative source amount is an OUTGOING flow (money out); a positive source amount is INCOMING (money in). The sign is consumed exactly once here, at the adapter boundary, and discarded; the stored amount is the absolute magnitude. A zero amount carries no flow and is rejected by build_raw_transaction() before this is called.

Return type:

TransactionDirection

Parameters:

signed_amount (Decimal)

build_raw_transaction(*, provider, path, source_sha256, source_row_index, provider_transaction_id, booked_date, value_date, amount, currency, counterparty, description, raw_fields)

Create one ParsedLedgerRow from a source-signed amount.

amount is the source-signed value as the parser read it. Its sign is consumed here to choose the TransactionDirection, then the stored RawTransaction carries the absolute magnitude (flow lives in direction, never in the sign). A zero-amount row carries no flow and is refused at the parse boundary, consistent with the manual ledger path.

Raises:

InvalidFinancialSourceError – When amount is zero.

Return type:

ParsedLedgerRow

Parameters:

• provider (FinancialProvider)

• path (Path)

• source_sha256 (str)

• source_row_index (int)

• provider_transaction_id (str)

• booked_date (date)

• value_date (date | None)

• amount (Decimal)

• currency (str)

• counterparty (str | None)

• description (str)

• raw_fields (Mapping[str, str])

default_currency()

Return the configured project-default financial currency.

Every provider falls back to this value when a source omits a per-row currency, so it reaches the persisted RawTransaction on the fallback branch without passing through any column-level check. The financial_base_currency setting itself declares no shape, so it is validated here — at the single owner of the fallback — against the same normalise_iso_4217_currency() policy the per-column and per-statement paths use.

Raises:

FinancialValidationError – financial_base_currency is not a three-letter ISO 4217 code. Failing here names the misconfigured setting, instead of surfacing an opaque record-validation error once the value has already been copied onto a parsed row.

Return type:

str