camt053-writer-xlsx: Excel writer for parsed camt.053 statements

An Excel .xlsx writer for camt053-parsed ISO 20022 bank statements — turn a ParsedDocument into a four-sheet workbook (Metadata, Balances, Entries, Reversals) that accountants, auditors, and reconciliation macros can consume directly.

Latest release: v0.0.14 — single write_xlsx(document, path) function, 100% line + branch coverage, 100% docstring coverage.

Contents

• Overview
• Install
• Quick Start
• Sheets
• Examples
• The camt053 suite
• When not to use camt053-writer-xlsx
• Development
• Security
• Documentation
• License
• Contributing
• Acknowledgements

Overview

camt053-writer-xlsx is a small, focused companion to the camt053 ISO 20022 cash-management library. It does one thing well: given a parsed camt.053 document, write a multi-sheet Excel workbook in a stable column layout so downstream tooling can target columns by name without parsing the document model.

This package is part of the camt053 suite — a set of independently installable packages that share the camt053.services layer:

• camt053 — the core library (CLI + REST API)
• camt053-mcp — the Model Context Protocol server for AI agents
• camt053-lsp — the Language Server Protocol server for editors
• camt053-writer-xlsx — this package, the Excel writer

Install

camt053-writer-xlsx runs on macOS, Linux, and Windows and requires Python 3.10+ and pip. It pulls in camt053 and openpyxl automatically.

pip install camt053-writer-xlsx

Quick Start

from camt053 import parse_document
from camt053_writer_xlsx import write_xlsx

with open("statement.xml") as fh:
    document = parse_document(fh.read())

write_xlsx(document, "statement.xlsx")

That's a four-sheet Excel workbook ready for your accountant.

Sheets

The column layout is stable across releases; downstream tooling can target columns by name without parsing the document model. Multi-detail entries are flattened (an entry with N transaction details produces N rows that share the entry-level columns), so the workbook stays rectangular for spreadsheet consumers.

Examples

Two runnable examples live in examples/:

• 01_minimal_write.py — parse a camt.053 XML string and write it to Excel.
• 02_filter_reversals.py — build a ParsedDocument programmatically and inspect the Reversals sheet.

Both are exercised in CI on every commit.

The camt053 suite

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

flowchart LR
    A["camt.053 XML"] -->|parse_document| B["camt053"]
    B -->|ParsedDocument| C["camt053-writer-xlsx"]
    C -->|.xlsx workbook| D["Accountants / auditors"]

When not to use camt053-writer-xlsx

• You need a custom sheet layout. The four-sheet structure (Metadata / Balances / Entries / Reversals) is stable by design so downstream tooling can target columns by name. Forking the writer is the right move if your downstream needs differ.
• You need .xls (legacy binary). openpyxl writes .xlsx only; convert downstream if you must.
• You need encrypted output. Out of scope; encrypt the produced .xlsx downstream with a tool like msoffcrypto-tool.
• You want to read Excel. This package is a writer. The inverse direction (.xlsx → camt.053) is not currently in the suite; open an issue if you'd find it useful.

Development

git clone https://github.com/sebastienrousseau/camt053-writer-xlsx
cd camt053-writer-xlsx
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                       # 100% line + branch coverage gate
interrogate camt053_writer_xlsx  # 100% docstring gate
mypy camt053_writer_xlsx     # strict

Security

camt053-writer-xlsx consumes already-parsed data, not raw XML — the XXE / billion-laughs surface lives upstream in the camt053 core. Reporting practice, supported versions, and supply-chain posture (PyPI Trusted Publishing, sigstore attestations, signed tags) are documented in SECURITY.md. Vulnerabilities go via GitHub Private Vulnerability Reporting, not public issues.

Documentation

• README.md — this file
• CHANGELOG.md — release notes
• SECURITY.md — disclosure + supported versions
• SUPPORT.md — how to get help
• MAINTAINERS.md — who can merge
• examples/ — runnable scripts, exercised in CI

License

Licensed under the Apache License, Version 2.0. Any contribution submitted for inclusion shall be licensed as above, without additional terms.

Contributing

Contributions are welcome — open an issue or PR on the repository.

Acknowledgements

Built on the camt053 ISO 20022 Bank Statement library and openpyxl.