pain001-loader-xlsx logo

pain001-loader-xlsx

Load Excel payment records through the pain001 plugin contract.

Build Registry Docs OpenSSF Scorecard License: Apache-2.0 OR MIT Python 3.11 or newer

pain001-loader-xlsx demo: examples/01_load_xlsx.py loads two payment rows from a workbook it writes, then examples/02_iban_safety_guard.py shows a numeric IBAN cell refused with Excel's Text-format guidance


Contents

Getting started

The pain001-loader-xlsx ecosystem

Library reference

Operational


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

pain001

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

01_load_xlsx.py

Load a two-row workbook through XlsxLoader and read LoaderResult.rows

02_iban_safety_guard.py

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.