cadrumo.adapters.inbound.financial.providers.ofx module

OFX financial provider backed by ofxtools.

Provides OfxProvider, an FinancialProvider implementation that wraps ofxtools to ingest every statement block exposed by an OFX or QFX file. The _OfxAccountLike, _OfxStatementLike and _OfxTransactionLike Protocol surfaces let the adapter type-check against the spec-validated aggregates ofxtools returns without coupling to the library’s descriptor-driven model classes.

ofxtools is a strict, OFX-spec-conformant parser: it validates the header, the SIGNON block, and every required statement element (a BANKTRANLIST carries DTSTART / DTEND, an STMTRS carries a LEDGERBAL) at conversion time, raising on a malformed document rather than silently degrading. Real bank exports are spec-conformant, so the strictness is a correctness gain over the previous permissive parser.

Each OFX transaction is projected into a ParsedLedgerRow; the signed TRNAMT value determines TransactionDirection and the stored raw transaction keeps the absolute magnitude plus OFX-native raw fields.

ofxtools is GPL-3.0-only and therefore capability-gated behind the ofx optional extra: the import is lazy, guarded by require_optional_extra(), so a bare-core install keeps the rest of the ledger import surface and refuses OFX sources with the extra’s typed machine identity rather than a rendered installation command.

class OfxProvider

Bases: FinancialProvider

Ingest raw transactions from OFX and QFX files.

Multi-statement OFX files emit transactions from every statement block; the provider names the account in the synthetic transaction id and copies the OFX-native fields (ACCTID, TRNTYPE, DTPOSTED, TRNAMT, FITID, NAME, MEMO) into raw_fields for downstream auditing. The provider remains format-level: application ledger import owns persistence and bucket events.

name: ClassVar[str]

supported_extensions: ClassVar[frozenset[str]]

source_format: ClassVar[SourceFormat]

verification_source: ClassVar[CorpusVerificationSource]

provisional_pending_specimen: ClassVar[bool]

validate_source(path)

Validate that the OFX file can be parsed and carries at least one transaction.

Without the ofx optional extra installed this degrades along the detection contract: a source that does not look like OFX is reported as a plain probe miss carrying the extra’s machine identity (so --provider auto detection of other formats keeps working), while a source that clearly IS OFX raises the typed MissingOptionalExtraError — never a silent “no provider matched”. Neither branch renders an installation command; the recovery is resolved downstream from the extra’s typed identity.

Return type:

ProviderValidation

Returns:

A ProviderValidation with the validation outcome.

Raises:

MissingOptionalExtraError – If the source looks like an OFX/QFX document but the ofx extra is not installed.

Parameters:

path (Path)

ingest(path)

Yield ParsedLedgerRow records (magnitude + direction) from every OFX statement.

Return type:

Iterator[ParsedLedgerRow]

Parameters:

path (Path)