Changelog¶
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.
Every package in the
pain001 suite ships
the same version number — the core, pain001-mcp, pain001-lsp,
pain001-loader-xlsx and pain001-loader-mt101. If the core is at
0.0.60 then so is this package, so there is no compatibility table to
consult. Versions advance in 0.0.1 steps along the 0.0.x line;
0.1.0 follows 0.0.999.
PAIN001_API_VERSION still guards the plugin contract at load time — a
plugin built against a newer contract than its host raises rather than
misbehaving — but it is a safety net, not the versioning rule. See
pain001.suite, which a daily job checks against PyPI.
[Unreleased]¶
[0.0.90] - 2026-11-16¶
Changed¶
Release 0.0.90 in lockstep with the pain001 suite.
Requires pain001 0.0.90, the suite version this release ships in lockstep with.
[0.0.89] - 2026-11-16¶
Changed¶
Release 0.0.89 in lockstep with the pain001 suite.
Requires pain001 0.0.89, the suite version this release ships in lockstep with.
The hash-pinned development sets take this week’s Dependabot updates: ruff 0.17.5, filelock 4.2.10, myst-parser 5.2.0 with mdit-py-plugins 0.7.0, and complexipy 9.0.0.
The complexity ratchet’s
compare()is split into_regressions()and_stale(): complexipy 9 scores it at cognitive 18, over the ceiling of 15. The report it produces is unchanged.
Fixed¶
make pip-compileresolvesrequirements/docs.inat Python 3.11.5, the oldest version soupsieve 4 supports, and stops on the first failure. At 3.11 the docs set could not resolve and the loop swallowed the error, leavingdocs.txtstale.PIP_COMPILE_FLAGSpasses extra uv flags, such as-P myst-parser.The README’s Quick Start lists loaders with
pain001 plugins list --kind loader --format json: pain001 0.0.89 removes the deprecated--jsonflag it used.
[0.0.88] - 2026-11-14¶
Changed¶
Release 0.0.88 in lockstep with the pain001 suite.
Requires pain001 0.0.88, the suite version this release ships in lockstep with.
Suite Consistency pins the core’s ecosystem check at
404ebb9, the pain001 0.0.88 release, which audits the five SDK repositories with the rest of the family; the job is now named “Every family publication agrees”. Regenerated from pain001’sscripts/render_ecosystem_workflows.py.AGENTS.md counts the fourteen suite repositories: the Go, Java, Rust, .NET and C++ SDKs joined the family at 0.0.88.
Security¶
The docs toolchain requires soupsieve 4.0 or newer: earlier versions have a polynomial-time denial of service in the descendant combinator (GHSA-mmhr-3c5m-f64f). Only the hash-pinned docs set contained it, so the published package is unaffected. The docs set now compiles from Python 3.11.5, the oldest version soupsieve 4 supports.
[0.0.87] - 2026-11-12¶
Changed¶
Release 0.0.87 in lockstep with the pain001 suite.
Requires pain001 0.0.87, the suite version this release ships in lockstep with.
Suite Consistency no longer runs on another workflow’s completion (
workflow_run). It audits the family daily and on dispatch, as the core’s does, since that trigger runs with the default branch’s trust whatever started it. Regenerated from pain001’sscripts/render_ecosystem_workflows.py.
Added¶
The README’s Security section names the project’s OpenSSF Best Practices passing badge, meeting the OpenSSF Best Practices silver criterion
documentation_achievements.
Fixed¶
Suite Consistency pins the core’s ecosystem check at
febcd0a, which accepts the five pain001 SDK repositories as known members not yet released. From the 0.0.86 release until this change every scheduled run failed on them as undeclared repositories.ROADMAP.mdlisted mutation testing as a candidate althoughmutation.ymlalready runs it; it is now under Shipped.
[0.0.86] - 2026-11-11¶
Added¶
Add a code of conduct (adapted from Contributor Covenant 2.1, the suite’s shared text), issue forms, a pull request template, AGENTS.md and a markdownlint CI job (
docs-lint.yml, configured in.markdownlint-cli2.jsonc).Run the README Quick Start verbatim in the test suite (
tests/test_readme.py): it builds a workbook from core’spain.001.001.03template rows, lists the loaders and generates XML, so a CLI or entry-point change fails CI instead of a reader’s terminal.Add
.editorconfig, a.pre-commit-config.yamlwith hooks pinned by commit SHA (pre-commit-hooks 6.0.0, ruff 0.17.4, codespell 2.4.3), a devcontainer that installs the new hash-pinnedrequirements/dev.txtand runsmake check, and a codespell job indocs-lint.yml(make docs-lintruns it with markdownlint).
Changed¶
Release 0.0.86 in lockstep with the pain001 suite and require core pain001 0.0.86; the locks resolve its published artifacts.
Rewrite
DEVELOPMENT.mdas the single developer entry point: toolchain, the local command for every CI job, the test layout, the README pipeline and the release model. CorrectCONTRIBUTING.md, which named atests/test_stress.pyand aperfmarker that do not exist, and includeARCHITECTURE.mdin the manual.The README template is now byte-identical to the portfolio’s canonical
README-TEMPLATE.md, the docs badge and Documentation links point at the published manual, and the Examples section indexes both scripts.tests/test_readme.pyfails CI on drift from the sources, an unresolved{{TOKEN}}, a dangling relative link or a section out of the canonical order.The manual’s footer links the author’s name on every page, and
docs.ymlfails a build where a page lacks it. A separateLink checkjob (make linkcheck) runs Sphinx linkcheck over external links, andtests/test_docs_links.pychecks every repository-relative link in the Markdown sources offline.
[0.0.85] - 2026-11-10¶
Changed¶
Release 0.0.85 in lockstep with the pain001 suite and require core pain001 0.0.85; the locks resolve its published artifacts.
SUPPORT.md and GOVERNANCE.md point questions at GitHub issues (the suite does not use GitHub Discussions), say there is no paid tier, SLA or out-of-hours cover, and drop the commercial-support contact. The suite list names the MT101 loader and links the family map.
[0.0.84] - 2026-11-09¶
Added¶
Audit all nine suite repositories and their publication channels daily and after publishing workflows, using the shared checker pinned to a core commit.
Changed¶
CI actions: github/codeql-action 4.39.3, sigstore/cosign-installer 4.1.3 and softprops/action-gh-release 3.0.4 (Dependabot #59).
Release 0.0.84 with the suite and require core pain001 0.0.84. Regenerate dependency locks from the published core artifacts.
[0.0.83] - 2026-11-09¶
Released in lockstep with pain001 0.0.83. Nothing in this loader changed
beyond the version and the pain001 floor. The core’s 0.0.83 changes
are to XML signing and signature verification; the XML it writes from
workbook rows is the same as with 0.0.82.
Changed¶
Requires
pain001 >= 0.0.83, < 1(pyproject.tomlandrequirements/runtime.in; every requirement file that pinspain001regenerated with the command in its header).
[0.0.82] - 2026-11-09¶
Released in lockstep with pain001 0.0.82. Nothing in this loader changed
beyond the version and the pain001 floor. The loader passes your
workbook’s columns through, so the core’s 0.0.82 changes apply to
them: for pain.001.001.04 to .08, a valid IBAN column is written as
<IBAN> and a non-empty service_level_code column as
PmtTpInf/SvcLvl/Cd, and rows whose service_level_code values
differ are refused, as they already were for .03 and .09 to .13.
Changed¶
Requires
pain001 >= 0.0.82, < 1(pyproject.tomlandrequirements/runtime.in; every requirement file that pinspain001regenerated with the command in its header).Development tools: ruff 0.17.4 and filelock 4.2.9 (Dependabot #54 and #55).
[0.0.81] - 2026-11-08¶
Released in lockstep with pain001 0.0.81. Nothing in this loader changed
beyond the version and the pain001 floor. In 0.0.81 the core checks
every IBAN and BIC and refuses rows that mix payment batches when it
loads them, so rows this loader returns are checked the same way as a
CSV file’s.
Changed¶
Requires
pain001 >= 0.0.81, < 1(pyproject.tomlandrequirements/runtime.in; every requirement file that pinspain001regenerated with the command in its header).
[0.0.80] - 2026-11-07¶
Released in lockstep with pain001 0.0.80, a security release of the
core’s REST API
(GHSA-vv3x-jpvc-w468).
Nothing in this loader changed beyond the version and the pain001
floor.
Changed¶
Requires
pain001 >= 0.0.80, < 1(pyproject.tomlandrequirements/runtime.in); every hash-pinned requirements file that carriespain001now pins 0.0.80.
[0.0.79] - 2026-11-07¶
Released in lockstep with pain001 0.0.79. The loader is unchanged:
this release moves the pain001 floor to 0.0.79, as the suite’s
lockstep policy requires, and has the release workflow write the
release page itself.
Changed¶
Requires
pain001 >= 0.0.79, < 1(pyproject.tomlandrequirements/runtime.in); every hash-pinned requirements file that carriespain001now pins 0.0.79.The release page is written by the release workflow in the suite’s shape. A last
release-notesjob runsscripts/release_notes.py publishonce every asset is attached: the title ispain001-loader-xlsx X.Y.Z, the Highlights come fromreleases/vX.Y.Z.md, What’s Changed lists the pull requests merged since the previous release, and Checksums gives the SHA-256 of every asset. The 0.0.77 and 0.0.78 pages had to be rewritten by hand.tests/test_release_notes.pyfails a pull request whose CHANGELOG dates the version whilereleases/vX.Y.Z.mdis missing or has other than 2 to 4 highlights. Both files are vendored byte-identical frompain001.
[0.0.78] - 2026-11-07¶
Released in lockstep with pain001 0.0.78, which adds faces
(projections of a pain.001 document into UK Open Banking, Berlin Group
and ISO 20022 element names). The loader is unchanged: this release
moves the pain001 floor to 0.0.78, as the suite’s lockstep policy
requires.
Changed¶
Requires
pain001 >= 0.0.78, < 1(pyproject.tomlandrequirements/runtime.in).
[0.0.77] - 2026-11-06¶
Released in lockstep with pain001 0.0.77. The loader is unchanged:
this release moves the pain001 floor to 0.0.77, as the suite’s
lockstep policy requires, and carries the dependency updates merged
since 0.0.75. 0.0.76 was prepared on 2026-11-05 but never tagged or
published, so its changes ship here.
Changed¶
Requires
pain001 >= 0.0.77, < 1(pyproject.tomlandrequirements/runtime.in).Development and CI tools: hatchling 1.33.0, pytest 9.2.0, pytest-benchmark 5.3.1, mypy 2.4.1, ruff 0.17.3, complexipy 8.3.0, mutmut 3.8.1 and certifi 2026.10.23; every requirement file regenerated with the command in its header.
CI: one stable required check per versioned matrix.
[0.0.75] - 2026-10-27¶
Released in lockstep with pain001 0.0.75. The loader is unchanged:
this release moves the Python floor to 3.11 with the rest of the suite
and clears an advised filelock from the audit tree.
Security¶
requirements/audit.txtpinned filelock 4.1.0 for Python 3.10 (GHSA-9vhv-jxww-xfm5, GHSA-567q-5qvw-pf92, GHSA-v4x8-3wr5-3wq8), which pip-audit on 3.12 skipped because of its marker.audit.innow floorsfilelock >= 4.2.1, and with the 3.10 entries gone the tree pins 4.2.4.
Removed¶
Python 3.10 support. The floor is 3.11 (
requires-python = ">=3.11"), the pain001 suite’s decision for 0.0.75: 3.10 reaches end of life in October 2026, and current hypothesis releases need 3.11, which broke Dependabot’s resolver for siblings on a 3.10 floor. CI tests 3.11 to 3.14; ruff and mypy target 3.11; the 3.10 classifier, thetomlibackport and the 3.10 branch inscripts/check_suite_consistency.pyare gone, andmake pip-compilecompiles for 3.11 (only the packages for 3.10 leave). pip keeps 3.10 users on pain001-loader-xlsx 0.0.74.
Changed¶
ruff 0.17.2 in the lint tree (Dependabot #36) and the GitHub Actions group’s five updates (#37).
[0.0.74] - 2026-10-21¶
Aligns pain001-loader-xlsx on the suite’s 0.0.74. The suite skips
0.0.73, which only pain001-mcp published; this package goes from
0.0.72 to 0.0.74.
Changed¶
Requires
pain001 >= 0.0.74, < 1, the family’s release; the floor was0.0.56.Behaviour change: the generated XML changes for cells starting with
=,+,-or@. 0.0.72 prefixed them with a single quote, as the core’s CSV loader then did; pain001 0.0.74 keeps CSV values raw by default (its ADR-0008), because XML is never evaluated and the quote changed the payment (-5became'-5,+44 20 7946 0000gained a quote). This loader now keeps them raw too, numeric cells included, so a sheet and its CSV export render the same XML. The core’s opt-insanitize_formulais aload_csv_datakeyword, not part of the loader plugin interface, so there is no XLSX equivalent.
Fixed¶
Text cells now carry what Excel displays. OOXML stores a carriage return as
_x000D_and a literal_xHHHH_as_x005F_xHHHH_(ECMA-376, ST_Xstring); openpyxl returns them undecoded, so a multi-line cell reached the payment asLine1_x000D_LFLine2instead of the CR LF its CSV export carries. The escapes are now decoded, and the XML equals the equivalent CSV’s again.A text cell holding a character XML 1.0 cannot carry (most C0 controls, lone surrogates, U+FFFE, U+FFFF) is refused with its column, row and code point. Before, the escape text itself, such as
_x0007_, went into the payment field. A workbook that loaded with such a cell now raisesValueError.scripts/check_suite_consistency.pycompared the tree with the pain001 core’s PyPI release; it now compares it with this package’s own, so a bump that was never released is caught in the window after the core ships.GitHub releases are titled
pain001-loader-xlsx <version>by the release workflow, not with the bare tag.Wheel metadata no longer carries an Apache-only licence classifier;
License-Expression: Apache-2.0 OR MITstates the licence.
Security¶
Every
pip installin CI installs a hash-pinnedrequirements/*.txt(OpenSSF Scorecard Pinned-Dependencies), and a new CI job runspip-auditon each. The audit, build and docs trees requirecertifi >= 2026.10.19(GHSA-6q48-6c7w-9gw2).Text cells are fuzzed with Atheris on every change, from a committed corpus that
tests/test_fuzz.pyalso replays.
Added¶
A complexity gate (
scripts/check_complexity.py, cyclomatic 10, cognitive 15, Halstead difficulty 30, 60 lines per function) against an empty, CI-enforced baseline.make audit,make pip-compile,make complexity,make fuzzandmake demo; a VHS demo in the README.
[0.0.72] - 2026-09-28¶
Security¶
Shield cells from CSV/Excel formula injection by disarming leading formula triggers (
=,+,-,@,\t,\r) in string fields when loading workbooks.
Added¶
Add SLSA Level 3 provenance attestations to release artifacts.
Changed¶
Version aligned to
0.0.72across allpain001suite packages.The README and the documentation index link What is pain.001?, an explainer of the message’s structure, versions and a schema-valid example.
[0.0.71] - 2026-09-26¶
Documentation¶
Generate the canonical README, check drift in CI, and replace stale feature, tool-count and safety claims with current source-backed guidance.
Fixed¶
Close workbook resources on malformed input and early iterator termination, as well as after successful loading (pain001#180).
[0.0.70] - 2026-09-13¶
Aligns the pain001 suite on 0.0.70: the core’s rail rules now read the
CSV pipeline’s column names, and its optional dependencies load on use
rather than on import. Nothing in this package changed.
Changed¶
Version aligned to
0.0.70across all fivepain001packages.SECURITY.md’s supported-version table follows the bump.
[0.0.69] - 2026-09-12¶
Aligns the pain001 suite on 0.0.69, the core’s third example-corpus
release: the tier 2 and 3 market packs, the CSV pipeline extension and
the pain.001 twin foundation (lossless ISO JSON twins with their
schemas). Nothing in this package changed.
Changed¶
Version aligned to
0.0.69across all fivepain001packages.SECURITY.md’s supported-version table follows the bump.
[0.0.68] - 2026-09-12¶
Aligns the pain001 suite on 0.0.68, the core’s second example-corpus
release: the tier-1 market packs (UK, SEPA core, US, CH, SE), coverage
files named by recipe and focus, and the tooling to apply a bank’s own
guideline privately. Nothing in this package changed.
Changed¶
Version aligned to
0.0.68across all fivepain001packages.SECURITY.md’s supported-version table follows the bump.
[0.0.67] - 2026-09-12¶
Aligns the pain001 suite on 0.0.67, the core’s first example-corpus
release: validated pain.001 example files per country and rail with
their provenance, and the schema coverage sets. Nothing in this package
changed.
Changed¶
Version aligned to
0.0.67across all fivepain001packages.SECURITY.md’s supported-version table follows the bump.
[0.0.66] - 2026-09-12¶
Aligns the pain001 suite on 0.0.66, the core release that adds
cross-record duplicate detection, the /api/v1/ui dashboard, GPG
flags and OpenTelemetry spans. Nothing in this package changed.
Changed¶
Version aligned to
0.0.66across all fivepain001packages.SECURITY.md’s supported-version table follows the bump.
[0.0.65] - 2026-08-29¶
Aligns the pain001 suite on one version number, and adds the gates this
repository was missing.
Added¶
benches/bench_load_xlsx.py, which measures the only thing that separatesloadfromload_streaming: peak memory. At 10,000 rows, streaming and releasing each chunk peaks 4.5× lower (1.96 MB against 8.73 MB) and stays roughly flat as the file grows. Time is unchanged — openpyxl’s parsing dominates both paths.A third column,
materialised, showing thatlist(load_streaming(...))costs exactly whatload()costs. It is there because the first version of this benchmark measured streaming that way and reported that streaming saves nothing — a wrong number that looked plausible. Callers make the same mistake in real code: the saving comes from consuming a chunk and letting it go.docs/benchmarks.md,CONTRIBUTING.md.scripts/check_suite_consistency.pyand a scheduledSuite Consistencyworkflow comparing this tree, and every published member, against PyPI.tests/test_suite_conformance.py, the shared suite conformance gate.
Changed¶
Version aligned to
0.0.65across all fivepain001packages, which had drifted to0.0.62,0.0.64,0.0.63,0.0.62and0.0.63.SECURITY.md’s supported-version table follows the bump.
Removed¶
The stray
v0.1.0tag. It was pushed in error on 2026-08-20 against a tree that briefly declared0.1.0, was never released to PyPI and had no GitHub release, and contradicted the suite’s0.0.xnumbering. The line it interrupted continued correctly at0.0.61.
[0.0.63] - 2026-08-28¶
Changed¶
A plain
pytestnow enforces the same 100% coverage floor CI does.--cov,--cov-branchand--cov-report=term-missingmove into[tool.pytest.ini_options] addopts. Before this, runningpytestlocally measured no coverage at all: the developer saw green and learned otherwise from the build.The gate itself was never missing — CI has always run
--cov-fail-under=100, so nothing could regress ontomainunnoticed. What was missing was the local half of it.The floor is stated once. It was in two places, the
--cov-fail-underflag inci.ymlandfail_underunder[tool.coverage.report], which is how two numbers meant to be equal stop being equal. pytest-cov honoursfail_underfrom the coverage config, so the flag is gone from bothaddoptsand the workflow and the number lives in exactly one place.CI now runs
pytest tests/ --cov-report=xml -v; only the XML report is CI-specific.
Verification¶
Coverage was already 100% and remains so. The gate was mutation-tested: adding a function no test calls drops coverage below the floor and fails the run, locally as well as in CI.
[0.0.62] - 2026-08-21¶
Added¶
Benchmarks for streaming throughput and value normalisation. The 0.0.61 set measured a full load, its scaling, and that
load_streamingdoes not hold every row. Two gaps remained.Streaming should also cost roughly what a full load costs, and does: 0.94x, 1.13x and 1.25x across chunk sizes. The guard is against chunking becoming expensive in its own right — re-opening the workbook per chunk, say — which would keep every row correct and leave the memory assertion passing while making the API pointless for the large files it exists for.
to_textruns once per cell, so it scales with the sheet rather than the row count: ~1.67us per cell, roughly 30ms of a ~156ms 2000-row load. Not dominant — openpyxl’s parsing is — but the largest piece this package owns.
[0.0.61] - 2026-08-20¶
Suite release with pain001 0.0.61. No change in this package.
The core’s 0.0.61 is a performance release — libxml2 XSD validation and a fix for quadratic CSV diagnostics — and neither touches this loader, which reads spreadsheets and goes through neither path. The version moves because every member of the suite ships the same number.
Note that 0.0.60 was never published for this package. It was prepared and tagged, but the tag failed before the publish step and the suite had moved to 0.0.61 by the time it was corrected, so 0.0.60 is skipped and this release carries its contents: values normalised to text, and temporal cells refused. See the 0.0.60 entry below for the detail.
[0.0.60] - 2026-08-20¶
Joins the suite’s version line. The previous number said this package
“targets the 0.0.X release of pain001” while 0.0.54 required
pain001>=0.0.56 — a version claiming to belong to a release it
predates.
An earlier draft resolved that by moving to 0.1.0 and declaring the
loaders independently versioned. That was the wrong way round: the rule
was right and the metadata was wrong. 0.0.60 matches the core and
every other member, and carries the breaking change below.
Fixed¶
Cell values are strings, matching
csv.DictReader. pain001 renders XML from whatever a loader returns, and its CSV loader yields strings. This loader returned Excel’s native types, so a cell displaying100.00— stored as the float100.0— reached the XML as100.0where the CSV path produced100.00. Same spreadsheet, two different amounts, depending on which container it arrived in.Numeric cells are now rendered through the cell’s
number_format, which is the only record of the intended precision, so100.0with format0.00emits"100.00".Breaking: callers reading
result.rows[...]now receivestrwhere they previously receivedint/float. That is the shape pain001 has always consumed.Excel date/time cells are refused. They previously passed through untouched, so a
datetimeobject reached pain001 and stringified as2026-03-01 00:00:00— a value no ISO 20022 date field accepts. Excel stores dates as offsets against a workbook epoch and the 1900 and 1904 systems differ by four years, so the loader will not guess. The error names the sheet, column and row, and says to format the column as Text and use ISO-8601 — completing the date-handling requirement of pain001#180.
[0.0.54] - 2026-07-18¶
Changed¶
Require
pain001 >= 0.0.56— the release that ships thepain001.pluginssubstrate this loader auto-discovers through. (The substrate landed on PyPI in pain001 0.0.56, alongside the 0.0.55 path-injection hardening; the CI git-branch fallback used while it was in flight is removed.)
[0.0.53] - 2026-06-20¶
Added¶
Initial release of pain001-loader-xlsx, a third-party loader
plugin that teaches the pain001
ISO 20022 payment library to read payment data directly from Excel
.xlsx / .xlsm files. Drop-in: install both packages and .xlsx
files dispatch automatically.
XlsxLoader— implements the structuralpain001.plugins.AbstractLoaderProtocol without subclassing. Just exposesmeta,extensions,load, andload_streaming.First-sheet header dispatch — row 1 becomes the dict keys, rows 2..N become the records. Cells are read with
openpyxl’sdata_only=Trueso formulas resolve to their cached last-saved value.Streaming variant —
load_streaming(path, chunk_size)honours pain001’s--streamingmode.IBAN safety guard — refuses any row whose
debtor_account_IBAN/creditor_account_IBAN/charge_account_IBANcell is typed as a number, surfacing a clear remediation pointing at Excel’s “Format Cells > Number > Text” workflow. Protects against the silent leading-zero-stripping that breaks SAP / Oracle / Workday exports.Entry-point auto-discovery — registered via the standard
pain001.loadersentry-point group inpyproject.toml; pain001 picks the loader up at process start with no manual wiring.Two runnable examples at
examples/that double as integration tests in CI.
Requirements¶
Python 3.10 or later.
pain001 >= 0.0.54, < 1— the plugin substrate (pain001.plugins) ships in pain001 v0.0.54. The package metadata declares this dependency explicitly;pipwill pull a compatible pain001 automatically.openpyxl >= 3.1, < 4.
Quality gates¶
Gate |
Status |
|---|---|
pytest |
12 tests passing |
Line + branch coverage |
100% (enforced via |
Docstring coverage (interrogate) |
100% |
ruff lint + format |
clean |
mypy |
clean |
Examples in CI |
2/2 run as integration tests |
Suite alignment¶
Package |
Version |
|---|---|
0.0.53 |
|
0.0.53 |
|
0.0.53 |
|
|
0.0.53 |