pain001-loader-xlsx 0.0.69

| | | -> LoaderResult | +----------+---------------+ +----------+---------------+ | | | extension dispatch (.xlsx) | v v +------+-------+ +------+-------+ | pain001 | | openpyxl | | registry | | read_only | +--------------+ +--------------+

pain001 v0.0.54 ships a formal plugin contract; this package
exposes one Python class that satisfies it. Wired into pain001 via
a single line in this package's `pyproject.toml`:

```toml
[project.entry-points."pain001.loaders"]
xlsx = "pain001_loader_xlsx.loader:XlsxLoader"

That is all the integration there is. pain001 discovers the entry point at process start via importlib.metadata.entry_points and dispatches by extension. There is no global state, no central registry to update, nothing to subclass.

Layout

The first sheet of the workbook is read. Row 1 is the header (column names become dict keys); rows 2..N are the data records. Cells are read with openpyxl's data_only=True so formulas resolve to their cached last-saved value — what the user sees in Excel is what pain001 gets.

The IBAN guard, explained

Excel's "General" cell format silently coerces a numeric-looking string like 0023012345... into the integer 23012345..., dropping the leading zeros. This is a known data-corruption mode in SAP / Oracle / Workday exports. To protect against it the loader refuses any row whose debtor_account_IBAN / creditor_account_IBAN / charge_account_IBAN cell is typed as a number, and tells the user to re-type the column as Text:

workbook 'payments.xlsx' column 'debtor_account_IBAN' contains
a numeric value (89370400440532013000) where an IBAN string is
expected. Excel's 'General' cell format silently strips leading
zeros from IBANs; re-type the column as 'Text' (in Excel: select
the column, Format Cells -> Number -> Text) and re-export.

Caught early, the warning saves the user from wiring an IBAN with a missing digit to a bank.

Using the loader from Python

For Lambdas, ETL pipelines, or just inspecting an Excel file's records before generation, you can use XlsxLoader directly without going through pain001's dispatch:

from pain001_loader_xlsx import XlsxLoader

loader = XlsxLoader()
result = loader.load("payments.xlsx")

print(result.source_hint)  # -> "payments.xlsx"
print(len(result.rows))  # -> 42
print(result.rows[0]["id"])  # -> "MSG-0001"

Streaming variant for batches that don't fit in memory:

for chunk in loader.load_streaming("big-payments.xlsx", chunk_size=1000):
    process(chunk.rows)

The runnable version of this snippet (and a couple of others) lives in examples/.

The pain001 suite

pain001-loader-xlsx is part of a set of independently installable packages built around the pain001 library — pick whichever ones your stack needs:

flowchart LR
    A["payments.xlsx"] -->|extension dispatch| B["pain001-loader-xlsx"]
    B -->|LoaderResult| C["pain001"]
    C -->|render + XSD validate| D["ISO 20022 pain.001 XML"]

When not to use pain001-loader-xlsx

• You can export CSV cleanly. A .csv round-trip skips an entire transitive dependency tree (openpyxl + its handful of deps). pain001's built-in CSV loader is preferred when you have the choice.
• You need multi-sheet support. The first sheet wins; cross-sheet payment batches need to be consolidated first.
• You need .xls (legacy binary format). Out of scope. Convert to .xlsx first, or use a different loader.
• Your data isn't payment-record-shaped. This loader is a thin pain001 input adapter, not a general-purpose Excel reader.

Development

pain001-loader-xlsx uses standard Python tooling — no Poetry, just pip + pyproject.toml.

git clone https://github.com/sebastienrousseau/pain001-loader-xlsx.git
cd pain001-loader-xlsx
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Quality gates (kept in lockstep with CI):

Current state (v0.0.54): 12 tests passing, 100% line + branch coverage, ruff + mypy clean, interrogate 100% docstring coverage.

Security

• No filesystem writes. The loader reads from an Excel file path and yields plain dicts; it does not create, modify, or delete files.
• No code execution. openpyxl's read_only=True mode does not evaluate macros (Excel VBA is not executed). data_only=True returns the cached last-saved value of formulas — no formula engine runs.
• IBAN safety: the loader refuses any row whose IBAN cells are numeric (see Layout), avoiding the "Excel silently dropped a leading zero" data-corruption mode.
• Dependencies are pinned via pyproject.toml (openpyxl >= 3.1, < 4) and audited by GitHub's Dependabot.

To report a vulnerability, please use GitHub private vulnerability reporting rather than a public issue.

Documentation

• Runnable examples: examples/
• Release history: CHANGELOG.md
• pain001 plugin contract: docs/plugins.md upstream
• openpyxl docs: openpyxl.readthedocs.io

Contributing

Contributions are welcome — see the contributing guide (or the upstream pain001 contributing guide if a per-repo one has not landed yet). Thanks to all the contributors who have helped build pain001-loader-xlsx.

License

Licensed under the Apache License, Version 2.0. Built on openpyxl and the pain001 plugin contract.

Any contribution submitted for inclusion shall be licensed as above, without additional terms.

pain001.com · PyPI · GitHub