pain001-loader-xlsx v0.0.54 teaches the Pain001 core to read payment batches straight from Excel .xlsx and .xlsm workbooks. No "Save As CSV" step, no encoding surprises, no silently corrupted account numbers.
Install it and it just works: the loader registers under the pain001.loaders entry point and is auto-discovered — pain001 -t pain.001.001.09 -d payments.xlsx -o out/ needs no further configuration.
pip install pain001 pain001-loader-xlsx
01. The IBAN safety guard#
Excel converts anything that looks like a number into a number. An IBAN pasted into a General-formatted cell can lose structure before you ever export it — and a corrupted debtor account is exactly the kind of error that surfaces as a bank-side rejection days later.
The loader refuses to let that happen. If any cell in the debtor_account_IBAN, creditor_account_IBAN, or charge_account_IBAN columns arrives as a numeric type, the load stops with a clear error telling you to re-format the column as Text. Matching is case-insensitive, and the failure happens before a single record is validated — fail fast, fail loud.
02. Behaviour, precisely#
- Formats:
.xlsxand.xlsm. Legacy.xls(BIFF) is not supported. - Formulas: resolved to their last-saved cached values (
data_only=True); macros in.xlsmfiles are never executed. - Structure: first worksheet only; row 1 is the header, rows 2..N are records.
- Memory: workbooks are opened read-only, and
load_streaming(path, chunk_size)yields fixed-size chunks so multi-hundred-thousand-row batches never load fully into memory — pairing naturally with the core CLI's--streamingmode. - Failure modes: a workbook with no sheets or a first sheet with no header row raises a precise
ValueErrorrather than producing an empty batch.
03. A well-behaved plugin#
The loader conforms structurally to the core's AbstractLoader protocol — no subclassing, no tight coupling — and declares its plugin API version so the core can refuse incompatible combinations cleanly. Like every package in the suite, it is tested to 100% line and branch coverage in CI.
FAQ#
Why not just export CSV from Excel?
CSV export is where leading zeros die and encodings drift. Reading the workbook directly preserves cell types, catches numeric-IBAN corruption at load time, and removes a manual step from a process that runs on deadlines.
Does it validate the IBANs themselves?
The guard is a type-level defence at ingestion. Full IBAN checksum validation (ISO 13616 mod-97) happens immediately afterwards in the core validation pipeline — two layers, each doing one job.
What about multi-sheet workbooks?
Out of scope by design. One sheet, one batch keeps the audit trail unambiguous. Split multi-sheet workbooks upstream, or convert per sheet.