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.md
• Benchmarks — headline numbers; full table at docs/BENCHMARKS.md
• Features — 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
• License

Install

As a Python library

python -m pip install pain001-loader-xlsx

Latest release: v0.0.74: text cells carry what Excel displays (OOXML _xHHHH_ escapes are decoded) and a cell XML cannot carry is refused; requires pain001 >= 0.0.74. 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.10 or newer. CI tests 3.10–3.14 on Linux. See toolchain policy; no distro-system-Python claim is made.

Quick Start

pain001 plugins list --kind loader --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.

Capabilities at a glance

Ecosystem comparison

This matrix describes the repository's scope, not an independently benchmarked comparison with competitors.

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.

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

Run the self-checking scripts under examples/. Tests cover valid and malformed inputs and integration with the core contract.

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.

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.