pain001-loader-xlsx
Load Excel payment records through the pain001 plugin contract.
Contents¶
Getting started
Install: PyPI and source
Requirements: toolchain floor, platforms
Quick Start: use the installed companion
The pain001-loader-xlsx ecosystem
The pain001-loader-xlsx ecosystem: core and this companion
Library reference
Capabilities at a glance: the current surface by theme
Ecosystem comparison: short matrix; full table at
docs/COMPARISON.mdBenchmarks: headline numbers; full table at
docs/BENCHMARKS.mdFeatures: module-level capability list
Configuration: core options
Examples: runnable example index
Operational
When not to use pain001-loader-xlsx: limitations
Development: make targets, fuzzing, CI
Security: guarantees and compliance
Documentation: all reference docs
Stability guarantees: SemVer axis, output stability, minimum toolchain discipline
Install¶
As a Python library¶
python -m pip install pain001-loader-xlsx
Latest release: v0.0.90: released in lockstep with the pain001 suite, for Python 3.11+; the loader is unchanged and requires
pain001 >= 0.0.90. See CHANGELOG.md.
Published packages and development checkouts are distinct. Test unreleased changes on this companion’s development branches against the matching core branch. Versions track core 0.0.x releases.
Requirements¶
Python 3.11 or newer. CI tests 3.11–3.14 on Linux. See toolchain policy; no distro-system-Python claim is made.
Quick Start¶
pain001 plugins list --kind loader --format json
pain001 -t pain.001.001.03 -d payments.xlsx -o output
Supply payments.xlsx with core template column names; examples/
creates synthetic workbooks. -o specifies an output directory, not a filename.
The pain001-loader-xlsx ecosystem¶
This independently installed companion delegates payment behavior to core. Coordinated versioning does not imply branch changes have been released.
Component |
Purpose |
Use case |
|---|---|---|
Generation and validation |
Shared contracts and XML engine |
Capabilities at a glance¶
Area |
Capability |
Status |
|---|---|---|
Integration |
Excel loading and streaming |
Test-gated companion package |
Ecosystem comparison¶
This matrix describes the repository’s scope, not an independently benchmarked comparison with competitors.
Project |
Generate payment XML |
Real settlement |
Synthetic bank replies |
|---|---|---|---|
pain001-loader-xlsx |
Delegates to core |
No |
Not a bank service |
See docs/COMPARISON.md for the evidence and complete matrix.
Benchmarks¶
CI smoke-runs benchmarks. No hardware-independent throughput or latency promise is made; use the generated run report for measurements.
Scenario |
Result |
Environment |
|---|---|---|
Adapter operations |
Run-specific |
Python, hardware and dependency versions recorded per run |
See docs/BENCHMARKS.md for methodology and full results.
Features¶
XlsxLoader implements AbstractLoader via the pain001.loaders entry point.
It reads .xlsx/.xlsm, first sheet only, row 1 as headers. Read-only, data-only
openpyxl access returns cached formula values, which can be stale or absent;
no formulas or macros are evaluated.
Numeric IBAN cells are rejected with column-specific Text-format guidance.
Text-valued IBAN cells are accepted even with General formatting. Excel date,
time and datetime objects are rejected; use ISO-8601 text. Formatting a damaged
identifier as Text cannot restore lost digits: recover the source value.
Text cells carry what Excel displays: OOXML _xHHHH_ escapes such as
_x000D_ are decoded, and a character XML cannot carry is refused with its
column, row and code point. Streaming yields bounded chunks and workbooks
close on errors.
Configuration¶
Install alongside core for extension dispatch. XlsxLoader.load(path) returns
LoaderResult; load_streaming(path, chunk_size) yields chunks. Refer to
core’s generated CLI help for generation flags.
Examples¶
Each script builds a synthetic workbook in a temporary directory, checks
its own output and exits 0; tests/test_examples.py runs every one in CI.
Example |
Shows |
|---|---|
Load a two-row workbook through |
|
A numeric IBAN cell refused with Excel’s Text-format guidance |
See examples/README.md for how to run them.
When not to use pain001-loader-xlsx¶
No legacy .xls, multi-sheet merging, formula evaluation or identifier repair.
Convert legacy files explicitly and preserve account values as text at source.
This is a payment-record adapter, not a general spreadsheet engine.
Development¶
make install
make check
python scripts/render_readme.py --check
python benches/bench_load_xlsx.py --quick
Coverage is gated at 100% line and branch. CI installs only hash-pinned
requirements/*.txt (make pip-compile regenerates them), audits each with
pip-audit, holds every function to the complexity ceilings, and fuzzes text
cells with Atheris. See CONTRIBUTING.md and
DEVELOPMENT.md. README is generated from the canonical
layout and docs/readme-values.json; CI rejects drift.
Security¶
Read-only workbook loading does not run macros or evaluate formulas. Numeric IBAN, temporal-cell and control-character guards reject known spreadsheet coercions. Loading a workbook does not prove its accounts, amounts or bank rules are correct. The project holds the OpenSSF Best Practices passing badge.
Report vulnerabilities according to SECURITY.md.
Documentation¶
What is pain.001? · User manual · API reference · Developer guide · Family map
Stability guarantees¶
Versions advance in coordinated 0.0.1 steps with core. The maintainer opens
releases. Contract and output changes need
compatibility review. No stronger platform or stability guarantee is implied.
License¶
Dual-licensed under Apache-2.0 OR MIT, at your option. See LICENSE. Dependencies retain their own licences.