bankstatementparser-writer-xlsx 0.0.10__tar.gz

bankstatementparser_writer_xlsx-0.0.10/LICENSE

@@ -0,0 +1,189 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work.
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to the Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by the Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding any notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2023-2026 Sebastien Rousseau
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

bankstatementparser_writer_xlsx-0.0.10/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: bankstatementparser-writer-xlsx
+Version: 0.0.10
+Summary: Excel (.xlsx) writer for bankstatementparser-parsed bank statements.
+License: Apache-2.0
+License-File: LICENSE
+Keywords: bank-statements,bankstatementparser,xlsx,excel,openpyxl,accounting,reconciliation
+Author: Sebastien Rousseau
+Author-email: sebastian.rousseau@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Dist: bankstatementparser (>=0.0.9)
+Requires-Dist: openpyxl (>=3.1,<4)
+Requires-Dist: pandas (>=2.0)
+Project-URL: Homepage, https://bankstatementparser.com
+Project-URL: Repository, https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx
+Description-Content-Type: text/markdown
+
+# bankstatementparser-writer-xlsx: Excel writer for parsed bank statements
+
+[![PyPI Version][pypi-badge]][pypi-url]
+[![Python Versions][python-versions-badge]][pypi-url]
+[![License][license-badge]][license-url]
+[![Coverage][coverage-badge]][ci-url]
+
+**An Excel `.xlsx` writer for data parsed by
+[`bankstatementparser`][core]** — turn parsed transactions (a pandas
+`DataFrame`, a list of `Transaction` objects, or a list of plain dicts)
+into a polished workbook that accountants, auditors, and reconciliation
+macros can open directly.
+
+> **Latest release: v0.0.10** — single `write_xlsx(data, path, ...)`
+> function, 100% line + branch coverage, 100% docstring coverage,
+> `mypy --strict` clean.
+
+## Contents
+
+- [Overview](#overview)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Input shapes](#input-shapes)
+- [Value coercion](#value-coercion)
+- [The summary sheet](#the-summary-sheet)
+- [Examples](#examples)
+- [When not to use this package](#when-not-to-use-this-package)
+- [Development](#development)
+- [Security](#security)
+- [Documentation](#documentation)
+- [License](#license)
+- [Contributing](#contributing)
+- [Acknowledgements](#acknowledgements)
+
+## Overview
+
+`bankstatementparser-writer-xlsx` is a small, focused companion to the
+[`bankstatementparser`][core] library. It does one thing well: given
+already-parsed bank-statement records, write a clean Excel workbook with
+a bold header row, one row per transaction, auto-sized columns, and an
+optional second `Summary` sheet.
+
+The package consumes _parsed_ data — it does not read PDFs, CSVs, or
+XML itself. Parsing (and the security surface that comes with untrusted
+input) lives upstream in the [`bankstatementparser`][core] core.
+
+## Install
+
+`bankstatementparser-writer-xlsx` runs on macOS, Linux, and Windows and
+requires **Python 3.10+**. It pulls in `bankstatementparser`,
+`openpyxl`, and `pandas` automatically.
+
+```bash
+pip install bankstatementparser-writer-xlsx
+```
+
+## Quick start
+
+```python
+from bankstatementparser import CsvStatementParser
+from bankstatementparser_writer_xlsx import write_xlsx
+
+parser = CsvStatementParser("statement.csv")
+df = parser.parse()                      # a pandas DataFrame
+write_xlsx(df, "statement.xlsx")         # one polished workbook
+```
+
+That's an Excel workbook ready for your accountant. Add a summary sheet
+in one extra argument:
+
+```python
+from bankstatementparser import CsvStatementParser
+from bankstatementparser_writer_xlsx import write_xlsx
+
+parser = CsvStatementParser("statement.csv")
+df = parser.parse()
+write_xlsx(df, "statement.xlsx", summary=parser.get_summary())
+```
+
+## Input shapes
+
+`write_xlsx(data, path, *, sheet_name="Transactions", summary=None)`
+accepts three input shapes and normalises each to a flat table:
+
+| Input | Column order |
+| :--- | :--- |
+| `pandas.DataFrame` (from a parser's `.parse()`) | the DataFrame's own column order |
+| `list[bankstatementparser.Transaction]` | the stable `Transaction` field order |
+| `list[dict]` | the union of keys, in first-seen order |
+
+A header row (bold) is written to the `sheet_name` sheet, followed by
+one row per record. Columns are auto-sized to their widest cell (capped
+so wide descriptions don't run off-screen).
+
+**Empty input** is accepted: an empty `list` writes an empty sheet (no
+header), while an empty `DataFrame` that still carries column labels
+writes a header-only sheet.
+
+## Value coercion
+
+Spreadsheet cells can't hold arbitrary Python objects, so the writer
+coerces the rich types the parser emits:
+
+| Python type | Written as |
+| :--- | :--- |
+| `decimal.Decimal` | `float` (Excel has no decimal type; floats aggregate natively) |
+| `datetime.date` / `datetime.datetime` | native Excel date cell (unchanged) |
+| `str`, `int`, `float`, `bool`, `None` | unchanged |
+| anything else | `str(value)` |
+
+## The summary sheet
+
+If you pass `summary=` a mapping (for example a parser's
+`get_summary()` result), the writer adds a second sheet titled
+`Summary` with a bold `Key` / `Value` header and one row per item:
+
+```python
+from decimal import Decimal
+
+from bankstatementparser_writer_xlsx import write_xlsx
+
+transactions = [
+    {"date": "2026-06-01", "description": "Salary", "amount": Decimal("3000.00")},
+    {"date": "2026-06-03", "description": "Coffee Shop", "amount": Decimal("-4.20")},
+]
+
+write_xlsx(
+    transactions,
+    "out.xlsx",
+    summary={
+        "account_id": "DE89370400440532013000",
+        "transaction_count": 128,
+        "total_amount": Decimal("12045.67"),
+        "currency": "EUR",
+    },
+)
+```
+
+## Examples
+
+Five runnable examples live in [`examples/`](examples/) and are
+exercised in CI on every commit. Together they cover every supported
+input shape and option of `write_xlsx`:
+
+- [`01_write_dataframe.py`](examples/01_write_dataframe.py) — write a
+  pandas `DataFrame` to a single sheet.
+- [`02_write_transactions.py`](examples/02_write_transactions.py) —
+  write a list of `Transaction` objects in stable field order.
+- [`03_write_dicts.py`](examples/03_write_dicts.py) — write a list of
+  plain `dict` records (union of keys).
+- [`04_write_with_summary.py`](examples/04_write_with_summary.py) —
+  write a DataFrame plus a second `Summary` sheet via `summary=`.
+- [`05_custom_sheet_name.py`](examples/05_custom_sheet_name.py) — rename
+  the transactions sheet with `sheet_name=`.
+
+## When not to use this package
+
+- **You need a custom sheet layout.** The single-sheet (+ optional
+  Summary) structure is intentionally simple. Compose your own
+  `openpyxl` workbook if you need pivot-ready, multi-sheet layouts.
+- **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.
+
+## Development
+
+```bash
+git clone https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx
+cd bankstatementparser-writer-xlsx
+poetry env use python3.12
+poetry install
+poetry run pytest        # 100% line + branch coverage gate
+poetry run ruff check bankstatementparser_writer_xlsx tests
+poetry run mypy bankstatementparser_writer_xlsx
+poetry run interrogate -c pyproject.toml bankstatementparser_writer_xlsx
+```
+
+## Security
+
+`bankstatementparser-writer-xlsx` consumes already-parsed data, not raw
+statement files — the PDF/CSV/XML parsing surface lives upstream in the
+[`bankstatementparser`][core] core. Reporting practice, supported
+versions, and supply-chain posture are documented in
+[`SECURITY.md`](SECURITY.md).
+
+## Documentation
+
+- [`README.md`](README.md) — this file
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — module map and design decisions
+- [`CHANGELOG.md`](CHANGELOG.md) — release notes
+- [`ROADMAP.md`](ROADMAP.md) — what's next
+- [`SECURITY.md`](SECURITY.md) — disclosure + supported versions
+- [`examples/`](examples/) — runnable scripts, exercised in CI
+
+## License
+
+Licensed under the [Apache License, Version 2.0][license-url]. 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](https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx).
+
+## Acknowledgements
+
+Built on the [`bankstatementparser`][core] library and
+[openpyxl](https://openpyxl.readthedocs.io/).
+
+[core]: https://github.com/sebastienrousseau/bankstatementparser
+[pypi-url]: https://pypi.org/project/bankstatementparser-writer-xlsx/
+[license-url]: https://opensource.org/license/apache-2-0/
+[ci-url]: https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx/actions/workflows/ci.yml
+[pypi-badge]: https://img.shields.io/pypi/v/bankstatementparser-writer-xlsx.svg?style=for-the-badge
+[python-versions-badge]: https://img.shields.io/pypi/pyversions/bankstatementparser-writer-xlsx.svg?style=for-the-badge
+[license-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge
+[coverage-badge]: https://img.shields.io/badge/Coverage-100%25-brightgreen?style=for-the-badge
+

bankstatementparser_writer_xlsx-0.0.10/README.md

@@ -0,0 +1,220 @@
+# bankstatementparser-writer-xlsx: Excel writer for parsed bank statements
+
+[![PyPI Version][pypi-badge]][pypi-url]
+[![Python Versions][python-versions-badge]][pypi-url]
+[![License][license-badge]][license-url]
+[![Coverage][coverage-badge]][ci-url]
+
+**An Excel `.xlsx` writer for data parsed by
+[`bankstatementparser`][core]** — turn parsed transactions (a pandas
+`DataFrame`, a list of `Transaction` objects, or a list of plain dicts)
+into a polished workbook that accountants, auditors, and reconciliation
+macros can open directly.
+
+> **Latest release: v0.0.10** — single `write_xlsx(data, path, ...)`
+> function, 100% line + branch coverage, 100% docstring coverage,
+> `mypy --strict` clean.
+
+## Contents
+
+- [Overview](#overview)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Input shapes](#input-shapes)
+- [Value coercion](#value-coercion)
+- [The summary sheet](#the-summary-sheet)
+- [Examples](#examples)
+- [When not to use this package](#when-not-to-use-this-package)
+- [Development](#development)
+- [Security](#security)
+- [Documentation](#documentation)
+- [License](#license)
+- [Contributing](#contributing)
+- [Acknowledgements](#acknowledgements)
+
+## Overview
+
+`bankstatementparser-writer-xlsx` is a small, focused companion to the
+[`bankstatementparser`][core] library. It does one thing well: given
+already-parsed bank-statement records, write a clean Excel workbook with
+a bold header row, one row per transaction, auto-sized columns, and an
+optional second `Summary` sheet.
+
+The package consumes _parsed_ data — it does not read PDFs, CSVs, or
+XML itself. Parsing (and the security surface that comes with untrusted
+input) lives upstream in the [`bankstatementparser`][core] core.
+
+## Install
+
+`bankstatementparser-writer-xlsx` runs on macOS, Linux, and Windows and
+requires **Python 3.10+**. It pulls in `bankstatementparser`,
+`openpyxl`, and `pandas` automatically.
+
+```bash
+pip install bankstatementparser-writer-xlsx
+```
+
+## Quick start
+
+```python
+from bankstatementparser import CsvStatementParser
+from bankstatementparser_writer_xlsx import write_xlsx
+
+parser = CsvStatementParser("statement.csv")
+df = parser.parse()                      # a pandas DataFrame
+write_xlsx(df, "statement.xlsx")         # one polished workbook
+```
+
+That's an Excel workbook ready for your accountant. Add a summary sheet
+in one extra argument:
+
+```python
+from bankstatementparser import CsvStatementParser
+from bankstatementparser_writer_xlsx import write_xlsx
+
+parser = CsvStatementParser("statement.csv")
+df = parser.parse()
+write_xlsx(df, "statement.xlsx", summary=parser.get_summary())
+```
+
+## Input shapes
+
+`write_xlsx(data, path, *, sheet_name="Transactions", summary=None)`
+accepts three input shapes and normalises each to a flat table:
+
+| Input | Column order |
+| :--- | :--- |
+| `pandas.DataFrame` (from a parser's `.parse()`) | the DataFrame's own column order |
+| `list[bankstatementparser.Transaction]` | the stable `Transaction` field order |
+| `list[dict]` | the union of keys, in first-seen order |
+
+A header row (bold) is written to the `sheet_name` sheet, followed by
+one row per record. Columns are auto-sized to their widest cell (capped
+so wide descriptions don't run off-screen).
+
+**Empty input** is accepted: an empty `list` writes an empty sheet (no
+header), while an empty `DataFrame` that still carries column labels
+writes a header-only sheet.
+
+## Value coercion
+
+Spreadsheet cells can't hold arbitrary Python objects, so the writer
+coerces the rich types the parser emits:
+
+| Python type | Written as |
+| :--- | :--- |
+| `decimal.Decimal` | `float` (Excel has no decimal type; floats aggregate natively) |
+| `datetime.date` / `datetime.datetime` | native Excel date cell (unchanged) |
+| `str`, `int`, `float`, `bool`, `None` | unchanged |
+| anything else | `str(value)` |
+
+## The summary sheet
+
+If you pass `summary=` a mapping (for example a parser's
+`get_summary()` result), the writer adds a second sheet titled
+`Summary` with a bold `Key` / `Value` header and one row per item:
+
+```python
+from decimal import Decimal
+
+from bankstatementparser_writer_xlsx import write_xlsx
+
+transactions = [
+    {"date": "2026-06-01", "description": "Salary", "amount": Decimal("3000.00")},
+    {"date": "2026-06-03", "description": "Coffee Shop", "amount": Decimal("-4.20")},
+]
+
+write_xlsx(
+    transactions,
+    "out.xlsx",
+    summary={
+        "account_id": "DE89370400440532013000",
+        "transaction_count": 128,
+        "total_amount": Decimal("12045.67"),
+        "currency": "EUR",
+    },
+)
+```
+
+## Examples
+
+Five runnable examples live in [`examples/`](examples/) and are
+exercised in CI on every commit. Together they cover every supported
+input shape and option of `write_xlsx`:
+
+- [`01_write_dataframe.py`](examples/01_write_dataframe.py) — write a
+  pandas `DataFrame` to a single sheet.
+- [`02_write_transactions.py`](examples/02_write_transactions.py) —
+  write a list of `Transaction` objects in stable field order.
+- [`03_write_dicts.py`](examples/03_write_dicts.py) — write a list of
+  plain `dict` records (union of keys).
+- [`04_write_with_summary.py`](examples/04_write_with_summary.py) —
+  write a DataFrame plus a second `Summary` sheet via `summary=`.
+- [`05_custom_sheet_name.py`](examples/05_custom_sheet_name.py) — rename
+  the transactions sheet with `sheet_name=`.
+
+## When not to use this package
+
+- **You need a custom sheet layout.** The single-sheet (+ optional
+  Summary) structure is intentionally simple. Compose your own
+  `openpyxl` workbook if you need pivot-ready, multi-sheet layouts.
+- **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.
+
+## Development
+
+```bash
+git clone https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx
+cd bankstatementparser-writer-xlsx
+poetry env use python3.12
+poetry install
+poetry run pytest        # 100% line + branch coverage gate
+poetry run ruff check bankstatementparser_writer_xlsx tests
+poetry run mypy bankstatementparser_writer_xlsx
+poetry run interrogate -c pyproject.toml bankstatementparser_writer_xlsx
+```
+
+## Security
+
+`bankstatementparser-writer-xlsx` consumes already-parsed data, not raw
+statement files — the PDF/CSV/XML parsing surface lives upstream in the
+[`bankstatementparser`][core] core. Reporting practice, supported
+versions, and supply-chain posture are documented in
+[`SECURITY.md`](SECURITY.md).
+
+## Documentation
+
+- [`README.md`](README.md) — this file
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — module map and design decisions
+- [`CHANGELOG.md`](CHANGELOG.md) — release notes
+- [`ROADMAP.md`](ROADMAP.md) — what's next
+- [`SECURITY.md`](SECURITY.md) — disclosure + supported versions
+- [`examples/`](examples/) — runnable scripts, exercised in CI
+
+## License
+
+Licensed under the [Apache License, Version 2.0][license-url]. 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](https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx).
+
+## Acknowledgements
+
+Built on the [`bankstatementparser`][core] library and
+[openpyxl](https://openpyxl.readthedocs.io/).
+
+[core]: https://github.com/sebastienrousseau/bankstatementparser
+[pypi-url]: https://pypi.org/project/bankstatementparser-writer-xlsx/
+[license-url]: https://opensource.org/license/apache-2-0/
+[ci-url]: https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx/actions/workflows/ci.yml
+[pypi-badge]: https://img.shields.io/pypi/v/bankstatementparser-writer-xlsx.svg?style=for-the-badge
+[python-versions-badge]: https://img.shields.io/pypi/pyversions/bankstatementparser-writer-xlsx.svg?style=for-the-badge
+[license-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge
+[coverage-badge]: https://img.shields.io/badge/Coverage-100%25-brightgreen?style=for-the-badge

bankstatementparser_writer_xlsx-0.0.10/bankstatementparser_writer_xlsx/__init__.py

@@ -0,0 +1,30 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Excel (.xlsx) writer for parsed ``bankstatementparser`` data.
+
+Exposes :func:`write_xlsx`, which serialises parsed bank-statement
+records (a pandas DataFrame, a list of
+:class:`bankstatementparser.Transaction` objects, or a list of plain
+dicts) to a polished ``.xlsx`` workbook.
+"""
+
+from __future__ import annotations
+
+from .writer import write_xlsx
+
+__all__ = ["write_xlsx", "__version__"]
+
+__version__ = "0.0.10"

bankstatementparser_writer_xlsx-0.0.10/bankstatementparser_writer_xlsx/writer.py

@@ -0,0 +1,353 @@
+# Copyright (C) 2023-2026 Sebastien Rousseau.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Excel ``.xlsx`` writer for parsed bank-statement data.
+
+This module turns the output of a
+[`bankstatementparser`](https://github.com/sebastienrousseau/bankstatementparser)
+parser into a polished Excel workbook via
+[openpyxl](https://openpyxl.readthedocs.io/).
+
+The single public entry point is :func:`write_xlsx`, which accepts any
+of three input shapes and normalises them to a flat, rectangular table:
+
+* a :class:`pandas.DataFrame` (as returned by a parser's ``.parse()``),
+* a list of :class:`bankstatementparser.Transaction` objects, or
+* a list of plain ``dict`` row records.
+
+The resulting workbook has a bold header row followed by one row per
+record on the ``Transactions`` sheet, with column widths auto-sized for
+readability. An optional ``summary`` mapping (e.g. the output of a
+parser's ``get_summary()``) is written to a second ``Summary`` sheet as
+key/value rows.
+
+Value coercion
+--------------
+Cells must hold spreadsheet-friendly values, so the writer coerces the
+rich Python types the parser emits:
+
+* :class:`decimal.Decimal` is written as a ``float`` (Excel has no
+  decimal type; floats sort and aggregate natively in spreadsheets).
+* :class:`datetime.date` and :class:`datetime.datetime` are written
+  unchanged — openpyxl serialises them as native Excel date cells.
+* Every other value is written as-is when openpyxl accepts it
+  (``str``, ``int``, ``float``, ``bool``, ``None``) and otherwise
+  stringified via ``str()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from datetime import date, datetime
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+from openpyxl import Workbook
+from openpyxl.styles import Font
+from openpyxl.utils import get_column_letter
+
+__all__ = ["write_xlsx"]
+
+# Stable column order for ``Transaction`` rows. Mirrors the field order
+# of ``bankstatementparser.Transaction`` so two runs over the same data
+# always produce the same workbook layout.
+_TRANSACTION_COLUMNS: tuple[str, ...] = (
+    "account_id",
+    "currency",
+    "amount",
+    "booking_date",
+    "value_date",
+    "description",
+    "normalized_description",
+    "reference",
+    "transaction_id",
+    "counterparty",
+    "source",
+    "source_index",
+    "source_method",
+    "confidence",
+    "category",
+    "transaction_hash",
+)
+
+# Hard upper bound on auto-sized column width, in characters. Wide free
+# text (descriptions) would otherwise push columns off-screen.
+_MAX_COLUMN_WIDTH = 60
+
+
+def write_xlsx(
+    data: Any,
+    path: str | Path,
+    *,
+    sheet_name: str = "Transactions",
+    summary: Mapping[str, Any] | None = None,
+) -> Path:
+    """Write parsed bank-statement ``data`` to a ``.xlsx`` workbook.
+
+    Args:
+        data: The records to serialise. One of:
+
+            * a :class:`pandas.DataFrame` (as returned by a
+              ``bankstatementparser`` parser's ``.parse()`` method) —
+              its columns define the header order;
+            * a list of :class:`bankstatementparser.Transaction`
+              objects — serialised with a stable column order;
+            * a list of plain ``dict`` records — the header is the
+              union of keys in first-seen order.
+
+            An empty list (or empty DataFrame) is accepted and writes a
+            header-only sheet (header omitted entirely when no columns
+            can be determined).
+        path: The output ``.xlsx`` file path. The parent directory must
+            already exist; an existing file is overwritten.
+        sheet_name: The title of the sheet holding the transaction rows.
+            Defaults to ``"Transactions"``.
+        summary: Optional mapping (e.g. a parser's ``get_summary()``
+            result) written to a second ``"Summary"`` sheet as one
+            ``key``/``value`` row per item, under a bold ``Key``/``Value``
+            header.
+
+    Returns:
+        The :class:`~pathlib.Path` of the written workbook.
+
+    Raises:
+        TypeError: If ``data`` is neither a DataFrame, nor a list/tuple
+            of ``Transaction`` objects, nor a list/tuple of ``dict``
+            records (and is not empty).
+        ValueError: If ``data`` is a non-empty sequence whose items mix
+            ``dict`` and non-``dict`` types, or contain an unsupported
+            item type.
+    """
+    columns, rows = _normalise(data)
+
+    workbook = Workbook()
+    sheet = workbook.active
+    sheet.title = sheet_name
+    _write_table(sheet, columns, rows)
+
+    if summary is not None:
+        summary_sheet = workbook.create_sheet("Summary")
+        _write_summary(summary_sheet, summary)
+
+    output = Path(path)
+    workbook.save(output)
+    return output
+
+
+def _normalise(data: Any) -> tuple[list[str], list[list[Any]]]:
+    """Normalise any supported ``data`` shape to columns and rows.
+
+    Args:
+        data: The input passed to :func:`write_xlsx`.
+
+    Returns:
+        A ``(columns, rows)`` pair where ``columns`` is the ordered
+        header and ``rows`` is a list of cell-value lists aligned to it.
+
+    Raises:
+        TypeError: If ``data`` is of an unsupported top-level type.
+        ValueError: If a sequence mixes ``dict`` and non-``dict`` items
+            or contains an unsupported item type.
+    """
+    if isinstance(data, pd.DataFrame):
+        return _normalise_dataframe(data)
+    if isinstance(data, list | tuple):
+        return _normalise_sequence(data)
+    raise TypeError(
+        "write_xlsx() expects a pandas DataFrame, a list of "
+        "Transaction objects, or a list of dict records; got "
+        f"{type(data).__name__}"
+    )
+
+
+def _normalise_dataframe(frame: Any) -> tuple[list[str], list[list[Any]]]:
+    """Normalise a :class:`pandas.DataFrame` to columns and rows.
+
+    Args:
+        frame: The DataFrame to convert. Its column order is preserved.
+
+    Returns:
+        A ``(columns, rows)`` pair with one row per DataFrame record.
+    """
+    columns = [str(column) for column in frame.columns]
+    rows = [
+        [_coerce(value) for value in record]
+        for record in frame.itertuples(index=False, name=None)
+    ]
+    return columns, rows
+
+
+def _normalise_sequence(
+    records: Sequence[Any],
+) -> tuple[list[str], list[list[Any]]]:
+    """Normalise a list/tuple of Transactions or dicts to a table.
+
+    Args:
+        records: A sequence of ``Transaction`` objects or ``dict``
+            records. May be empty.
+
+    Returns:
+        A ``(columns, rows)`` pair. An empty sequence yields empty
+        columns and rows.
+
+    Raises:
+        ValueError: If the items mix ``dict`` and non-``dict`` types or
+            an item is neither a ``dict`` nor a ``model_dump``-capable
+            object.
+    """
+    if not records:
+        return [], []
+
+    dict_records = [_to_record(record) for record in records]
+    columns: list[str] = []
+    seen: set[str] = set()
+    for record in dict_records:
+        for key in record:
+            if key not in seen:
+                seen.add(key)
+                columns.append(key)
+
+    rows = [
+        [_coerce(record.get(column)) for column in columns]
+        for record in dict_records
+    ]
+    return columns, rows
+
+
+def _to_record(record: Any) -> dict[str, Any]:
+    """Convert a single sequence item to an ordered ``dict`` record.
+
+    Args:
+        record: A ``dict`` or a ``Transaction``-like object exposing a
+            ``model_dump()`` method.
+
+    Returns:
+        An ordered ``dict`` of column name to value. ``Transaction``
+        objects use the stable column order in
+        :data:`_TRANSACTION_COLUMNS`; dicts preserve their own order.
+
+    Raises:
+        ValueError: If ``record`` is neither a ``dict`` nor exposes a
+            callable ``model_dump`` attribute.
+    """
+    if isinstance(record, Mapping):
+        return dict(record)
+    model_dump = getattr(record, "model_dump", None)
+    if callable(model_dump):
+        dumped = model_dump()
+        ordered = {
+            key: dumped[key] for key in _TRANSACTION_COLUMNS if key in dumped
+        }
+        for key, value in dumped.items():
+            if key not in ordered:
+                ordered[key] = value
+        return ordered
+    raise ValueError(
+        "Sequence items must be dict records or Transaction objects "
+        f"(with a model_dump() method); got {type(record).__name__}"
+    )
+
+
+def _coerce(value: Any) -> Any:
+    """Coerce a Python value to a spreadsheet-friendly cell value.
+
+    Args:
+        value: A value drawn from a record.
+
+    Returns:
+        ``float`` for :class:`decimal.Decimal`; the value unchanged for
+        ``date``/``datetime`` and for the scalar types openpyxl accepts
+        natively (``str``, ``int``, ``float``, ``bool``, ``None``);
+        ``str(value)`` for anything else.
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, Decimal):
+        return float(value)
+    if isinstance(value, datetime | date):
+        return value
+    if value is None or isinstance(value, str | int | float):
+        return value
+    return str(value)
+
+
+def _write_table(
+    sheet: Any,
+    columns: list[str],
+    rows: list[list[Any]],
+) -> None:
+    """Write the header and data rows, then auto-size the columns.
+
+    Args:
+        sheet: The target openpyxl worksheet.
+        columns: The ordered header labels. May be empty, in which case
+            nothing is written.
+        rows: The cell-value rows aligned to ``columns``.
+    """
+    if not columns:
+        return
+    sheet.append(columns)
+    for cell in sheet[1]:
+        cell.font = Font(bold=True)
+    for row in rows:
+        sheet.append(row)
+    _autosize(sheet, columns, rows)
+
+
+def _write_summary(sheet: Any, summary: Mapping[str, Any]) -> None:
+    """Write a ``summary`` mapping as key/value rows on ``sheet``.
+
+    Args:
+        sheet: The target openpyxl worksheet (the ``Summary`` sheet).
+        summary: The mapping to serialise, one row per item under a
+            bold ``Key``/``Value`` header.
+    """
+    sheet.append(["Key", "Value"])
+    for cell in sheet[1]:
+        cell.font = Font(bold=True)
+    keys = list(summary)
+    for key in keys:
+        sheet.append([str(key), _coerce(summary[key])])
+    _autosize(
+        sheet,
+        ["Key", "Value"],
+        [[str(key), _coerce(summary[key])] for key in keys],
+    )
+
+
+def _autosize(
+    sheet: Any,
+    columns: list[str],
+    rows: list[list[Any]],
+) -> None:
+    """Set each column width to fit its widest cell, within a cap.
+
+    Args:
+        sheet: The worksheet whose column dimensions are adjusted.
+        columns: The header labels, used as the initial width seed.
+        rows: The data rows scanned for their widest cell per column.
+    """
+    for index, header in enumerate(columns):
+        width = len(str(header))
+        for row in rows:
+            cell = row[index]
+            if cell is not None:
+                width = max(width, len(str(cell)))
+        letter = get_column_letter(index + 1)
+        sheet.column_dimensions[letter].width = min(
+            width + 2, _MAX_COLUMN_WIDTH
+        )

bankstatementparser_writer_xlsx-0.0.10/pyproject.toml

@@ -0,0 +1,153 @@
+[tool.poetry]
+name = "bankstatementparser-writer-xlsx"
+version = "0.0.10"
+description = "Excel (.xlsx) writer for bankstatementparser-parsed bank statements."
+authors = ["Sebastien Rousseau <sebastian.rousseau@gmail.com>"]
+license = "Apache-2.0"
+readme = "README.md"
+repository = "https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx"
+homepage = "https://bankstatementparser.com"
+keywords = [
+    "bank-statements",
+    "bankstatementparser",
+    "xlsx",
+    "excel",
+    "openpyxl",
+    "accounting",
+    "reconciliation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+packages = [
+    { include = "bankstatementparser_writer_xlsx" },
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+bankstatementparser = ">=0.0.9"
+openpyxl = ">=3.1,<4"
+pandas = ">=2.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=9.0.3,<10.0.0"
+pytest-cov = ">=6.0.0,<8.0.0"
+black = "^26.3.1"
+ruff = "^0.1.0"
+mypy = "^1.11.0"
+bandit = "^1.7.0"
+interrogate = "^1.7.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 79
+target-version = ['py310']
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"
+addopts = ["-ra", "--strict-markers", "--tb=short"]
+
+[tool.coverage.run]
+branch = true
+source = ["bankstatementparser_writer_xlsx"]
+
+[tool.coverage.report]
+exclude_also = [
+    "if __name__ == .__main__.:",
+    "pragma: no cover",
+    "@overload",
+]
+fail_under = 100
+show_missing = true
+skip_covered = false
+
+[tool.interrogate]
+fail-under = 100
+ignore-init-method = true
+ignore-semiprivate = false
+ignore-private = false
+ignore-magic = true
+exclude = ["tests", "examples"]
+
+[tool.ruff]
+line-length = 79
+target-version = "py310"
+extend-exclude = ["*.md", "tmp_env", ".venv", ".eggs"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_any_unimported = false
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+check_untyped_defs = true
+strict_equality = true
+exclude = [
+    "tmp_env/",
+    ".venv/",
+    ".eggs/",
+]
+
+[[tool.mypy.overrides]]
+module = "bankstatementparser.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "openpyxl"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "openpyxl.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "pandas.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+# The writer accepts heterogeneous record shapes (DataFrame, Transaction,
+# dict) normalised through ``Any``-typed cells, so relax the two strict
+# checks that signature would trip while keeping the rest of strict mode.
+module = "bankstatementparser_writer_xlsx.*"
+disallow_any_generics = false
+warn_return_any = false
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+disallow_untyped_calls = false
+warn_unused_ignores = false
+disable_error_code = ["arg-type", "return-value", "attr-defined", "assignment"]