bankstatementparser 0.0.18__tar.gz → 0.0.19__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/PKG-INFO +63 -37
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/README.md +60 -36
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/__init__.py +60 -1
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/_llm_common.py +6 -1
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/additional_parsers.py +70 -148
- bankstatementparser-0.0.19/bankstatementparser/analytics.py +529 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/api.py +13 -10
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/base_parser.py +35 -3
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/camt_parser.py +181 -109
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/cli.py +9 -9
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/enrichment/categorizer.py +47 -23
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/export/__init__.py +2 -0
- bankstatementparser-0.0.19/bankstatementparser/export/parquet.py +81 -0
- bankstatementparser-0.0.19/bankstatementparser/field86_parser.py +186 -0
- bankstatementparser-0.0.19/bankstatementparser/forensics.py +312 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/llm_extractor.py +8 -6
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/scanner.py +10 -6
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/input_validator.py +13 -5
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/pain001_parser.py +5 -3
- bankstatementparser-0.0.19/bankstatementparser/plugins.py +165 -0
- bankstatementparser-0.0.19/bankstatementparser/reconciliation.py +322 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/transaction_deduplicator.py +5 -3
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/transaction_models.py +5 -3
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/zip_security.py +110 -2
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/pyproject.toml +3 -1
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/LICENSE +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/LICENSE-APACHE +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/LICENSE-MIT +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/_amounts.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/bank_statement_parsers.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/enrichment/__init__.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/enrichment/account_mapper.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/exceptions.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/export/ledger.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/__init__.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/evaluation.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/ollama_direct.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/orchestrator.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/pdf_text.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/prompts.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/verification.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/hybrid/vision.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/parallel.py +0 -0
- {bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/record_types.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: bankstatementparser
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.19
|
|
4
4
|
Summary: BankStatementParser is your essential tool for easy bank statement management. Designed with finance and treasury experts in mind, it offers a simple way to handle CAMT (ISO 20022) formats and more. Get quick, accurate insights from your financial data and spend less time on processing. It's the smart, hassle-free way to stay on top of your transactions.
|
|
5
5
|
License: Apache-2.0 OR MIT
|
|
6
6
|
License-File: LICENSE
|
|
@@ -22,6 +22,7 @@ Provides-Extra: excel
|
|
|
22
22
|
Provides-Extra: hybrid
|
|
23
23
|
Provides-Extra: hybrid-plus
|
|
24
24
|
Provides-Extra: hybrid-vision
|
|
25
|
+
Provides-Extra: parquet
|
|
25
26
|
Provides-Extra: polars
|
|
26
27
|
Requires-Dist: defusedxml (>=0.7.1,<0.8.0)
|
|
27
28
|
Requires-Dist: fastapi (>=0.115.0) ; extra == "api"
|
|
@@ -31,6 +32,7 @@ Requires-Dist: openpyxl (>=3.1.5,<4.0.0) ; extra == "excel"
|
|
|
31
32
|
Requires-Dist: pandas (>=2.3.3,<3.0.0)
|
|
32
33
|
Requires-Dist: pdfplumber (>=0.11.0) ; extra == "hybrid-plus"
|
|
33
34
|
Requires-Dist: polars (>=1.32.0,<2.0.0) ; extra == "polars"
|
|
35
|
+
Requires-Dist: pyarrow (>=14.0.0) ; extra == "parquet"
|
|
34
36
|
Requires-Dist: pydantic (>=2.11.0,<3.0.0)
|
|
35
37
|
Requires-Dist: pypdf (>=4.0.0) ; extra == "hybrid" or extra == "hybrid-plus" or extra == "hybrid-vision"
|
|
36
38
|
Requires-Dist: pypdfium2 (>=4.30.0) ; extra == "hybrid-vision"
|
|
@@ -39,7 +41,16 @@ Project-URL: Homepage, https://bankstatementparser.com
|
|
|
39
41
|
Project-URL: Repository, https://github.com/sebastienrousseau/bankstatementparser
|
|
40
42
|
Description-Content-Type: text/markdown
|
|
41
43
|
|
|
42
|
-
<!-- SPDX-License-Identifier: Apache-2.0 OR MIT
|
|
44
|
+
<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
|
|
45
|
+
|
|
46
|
+
<p align="center">
|
|
47
|
+
<img
|
|
48
|
+
src="https://cloudcdn.pro/bankstatementparser/v1/logos/bankstatementparser.svg"
|
|
49
|
+
alt="bankstatementparser logo"
|
|
50
|
+
width="120"
|
|
51
|
+
height="120"
|
|
52
|
+
/>
|
|
53
|
+
</p>
|
|
43
54
|
|
|
44
55
|
<h1 align="center">Bank Statement Parser</h1>
|
|
45
56
|
|
|
@@ -51,7 +62,7 @@ Description-Content-Type: text/markdown
|
|
|
51
62
|
|
|
52
63
|
<p align="center">
|
|
53
64
|
<a href="https://github.com/sebastienrousseau/bankstatementparser/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/bankstatementparser/quality-gates.yml?style=for-the-badge&logo=github" alt="Build" /></a>
|
|
54
|
-
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.
|
|
65
|
+
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.19" alt="PyPI" /></a>
|
|
55
66
|
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/dm/bankstatementparser.svg?style=for-the-badge" alt="PyPI Downloads" /></a>
|
|
56
67
|
<a href="https://codecov.io/github/sebastienrousseau/bankstatementparser?branch=main"><img src="https://img.shields.io/codecov/c/github/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="Codecov" /></a>
|
|
57
68
|
<a href="LICENSE"><img src="https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="License" /></a>
|
|
@@ -228,17 +239,19 @@ from bankstatementparser.hybrid import smart_ingest
|
|
|
228
239
|
|
|
229
240
|
# Path A — deterministic parser (free, fastest, $0)
|
|
230
241
|
result = smart_ingest("statement.xml")
|
|
231
|
-
print(result.source_method)
|
|
242
|
+
print(result.source_method) # "deterministic"
|
|
232
243
|
|
|
233
244
|
# Path B — text-LLM for digital PDFs (set BSP_HYBRID_MODEL=ollama/llama3)
|
|
234
245
|
result = smart_ingest("statement.pdf")
|
|
235
|
-
print(result.source_method)
|
|
236
|
-
print(
|
|
246
|
+
print(result.source_method) # "llm"
|
|
247
|
+
print(
|
|
248
|
+
result.verification.status
|
|
249
|
+
) # VERIFIED | DISCREPANCY | UNVERIFIABLE | FAILED
|
|
237
250
|
|
|
238
251
|
# Path C — multimodal vision for scanned PDFs (set BSP_HYBRID_VISION_MODEL)
|
|
239
252
|
# auto-routed when pypdf cannot extract enough text
|
|
240
253
|
result = smart_ingest("scan.pdf")
|
|
241
|
-
print(result.source_method)
|
|
254
|
+
print(result.source_method) # "vision"
|
|
242
255
|
```
|
|
243
256
|
|
|
244
257
|
Every row carries:
|
|
@@ -276,7 +289,9 @@ For ZIP archives, use `iter_secure_xml_entries()`.
|
|
|
276
289
|
from bankstatementparser import CamtParser, iter_secure_xml_entries
|
|
277
290
|
|
|
278
291
|
for entry in iter_secure_xml_entries("statements.zip"):
|
|
279
|
-
parser = CamtParser.from_bytes(
|
|
292
|
+
parser = CamtParser.from_bytes(
|
|
293
|
+
entry.xml_bytes, source_name=entry.source_name
|
|
294
|
+
)
|
|
280
295
|
transactions = parser.parse()
|
|
281
296
|
print(entry.source_name, len(transactions), "transactions")
|
|
282
297
|
```
|
|
@@ -298,23 +313,23 @@ Gemini, …).
|
|
|
298
313
|
|
|
299
314
|
```mermaid
|
|
300
315
|
flowchart TD
|
|
301
|
-
A[smart_ingest
|
|
302
|
-
B
|
|
303
|
-
C --> Z[IngestResult<br/>source_method='deterministic']
|
|
316
|
+
A["smart_ingest(path)"] --> B{"detect_statement_format"}
|
|
317
|
+
B -->|CAMT/PAIN/OFX/MT940/CSV| C["Path A: deterministic parser<br/>$0, fastest"]
|
|
318
|
+
C --> Z["IngestResult<br/>source_method='deterministic'"]
|
|
304
319
|
|
|
305
|
-
B
|
|
306
|
-
D --> E{text
|
|
320
|
+
B -->|pdf or unknown| D["pypdf extract_text"]
|
|
321
|
+
D --> E{"text length >= 50?"}
|
|
307
322
|
|
|
308
|
-
E
|
|
309
|
-
F --> Y[IngestResult<br/>source_method='llm']
|
|
323
|
+
E -->|yes| F["Path B: text-LLM<br/>default ollama/llama3"]
|
|
324
|
+
F --> Y["IngestResult<br/>source_method='llm'"]
|
|
310
325
|
|
|
311
|
-
E
|
|
312
|
-
G --> X[IngestResult<br/>source_method='vision']
|
|
326
|
+
E -->|no| G["Path C: vision-LLM<br/>opt-in via BSP_HYBRID_VISION_MODEL"]
|
|
327
|
+
G --> X["IngestResult<br/>source_method='vision'"]
|
|
313
328
|
|
|
314
|
-
Z --> V[verify_balance<br/>Golden Rule]
|
|
329
|
+
Z --> V["verify_balance<br/>Golden Rule"]
|
|
315
330
|
Y --> V
|
|
316
331
|
X --> V
|
|
317
|
-
V --> R[VERIFIED / DISCREPANCY / UNVERIFIABLE / FAILED]
|
|
332
|
+
V --> R["VERIFIED / DISCREPANCY / UNVERIFIABLE / FAILED"]
|
|
318
333
|
```
|
|
319
334
|
|
|
320
335
|
Every extracted row carries an immutable `transaction_hash`, an
|
|
@@ -373,7 +388,7 @@ for the full surface.
|
|
|
373
388
|
|---|---|
|
|
374
389
|
| **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
|
|
375
390
|
| **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
|
|
376
|
-
| **Tested** |
|
|
391
|
+
| **Tested** | 907 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
|
|
377
392
|
|
|
378
393
|
---
|
|
379
394
|
|
|
@@ -440,11 +455,13 @@ Process multiple files simultaneously across CPU cores:
|
|
|
440
455
|
```python
|
|
441
456
|
from bankstatementparser import parse_files_parallel
|
|
442
457
|
|
|
443
|
-
results = parse_files_parallel(
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
458
|
+
results = parse_files_parallel(
|
|
459
|
+
[
|
|
460
|
+
"statements/jan.xml",
|
|
461
|
+
"statements/feb.xml",
|
|
462
|
+
"statements/mar.xml",
|
|
463
|
+
]
|
|
464
|
+
)
|
|
448
465
|
|
|
449
466
|
for r in results:
|
|
450
467
|
print(r.path, r.status, len(r.transactions), "rows")
|
|
@@ -693,13 +710,22 @@ versioned companion packages build on it — each is its own repository
|
|
|
693
710
|
and Python package, so you install only what you need and the core
|
|
694
711
|
stays dependency-light.
|
|
695
712
|
|
|
696
|
-
| Package | PyPI | Role |
|
|
697
|
-
|
|
698
|
-
| [`bankstatementparser
|
|
699
|
-
| [`bankstatementparser-
|
|
700
|
-
| [`bankstatementparser-
|
|
701
|
-
| [`bankstatementparser-
|
|
702
|
-
| [`bankstatementparser-
|
|
713
|
+
| Package | GitHub Repository | PyPI | Role | Description |
|
|
714
|
+
|---|---|---|---|---|
|
|
715
|
+
| [`bankstatementparser`](https://github.com/sebastienrousseau/bankstatementparser) | [`sebastienrousseau/bankstatementparser`](https://github.com/sebastienrousseau/bankstatementparser) | [](https://pypi.org/project/bankstatementparser/) | Core Engine | Unified parser for CAMT (052/053), PAIN.001, CSV, OFX, QFX, MT940, and PDF statements |
|
|
716
|
+
| [`bankstatementparser-mcp`](https://github.com/sebastienrousseau/bankstatementparser-mcp) | [`sebastienrousseau/bankstatementparser-mcp`](https://github.com/sebastienrousseau/bankstatementparser-mcp) | [](https://pypi.org/project/bankstatementparser-mcp/) | AI Protocol | Model Context Protocol (MCP) server exposing statement tools to LLMs & AI agents |
|
|
717
|
+
| [`bankstatementparser-lsp`](https://github.com/sebastienrousseau/bankstatementparser-lsp) | [`sebastienrousseau/bankstatementparser-lsp`](https://github.com/sebastienrousseau/bankstatementparser-lsp) | [](https://pypi.org/project/bankstatementparser-lsp/) | Developer Tooling | Language Server Protocol (LSP) with live SWIFT MT940 statement validation & diagnostics |
|
|
718
|
+
| [`bankstatementparser-transport-ebics`](https://github.com/sebastienrousseau/bankstatementparser-transport-ebics) | [`sebastienrousseau/bankstatementparser-transport-ebics`](https://github.com/sebastienrousseau/bankstatementparser-transport-ebics) | [](https://pypi.org/project/bankstatementparser-transport-ebics/) | Transport | Automated bank statement retrieval over EBICS 3.0 (`H005`) and 2.5 (`H004`) protocols |
|
|
719
|
+
| [`bankstatementparser-writer-xlsx`](https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx) | [`sebastienrousseau/bankstatementparser-writer-xlsx`](https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx) | [](https://pypi.org/project/bankstatementparser-writer-xlsx/) | Output Writer | Formats and exports parsed banking transactions into styled Microsoft Excel (`.xlsx`) workbooks |
|
|
720
|
+
| [`bankstatementparser-writer-qif`](https://github.com/sebastienrousseau/bankstatementparser-writer-qif) | [`sebastienrousseau/bankstatementparser-writer-qif`](https://github.com/sebastienrousseau/bankstatementparser-writer-qif) | [](https://pypi.org/project/bankstatementparser-writer-qif/) | Output Writer | Serializes transactions into standard Quicken Interchange Format (`.qif`) exchange files |
|
|
721
|
+
| [`bankstatementparser-writer-ofx`](https://github.com/sebastienrousseau/bankstatementparser-writer-ofx) | [`sebastienrousseau/bankstatementparser-writer-ofx`](https://github.com/sebastienrousseau/bankstatementparser-writer-ofx) | [](https://pypi.org/project/bankstatementparser-writer-ofx/) | Output Writer | Serializes transactions into standard Open Financial Exchange (`.ofx`) XML/SGML files |
|
|
722
|
+
| [`bankstatementparser-writer-swift`](https://github.com/sebastienrousseau/bankstatementparser-writer-swift) | [`sebastienrousseau/bankstatementparser-writer-swift`](https://github.com/sebastienrousseau/bankstatementparser-writer-swift) | [](https://pypi.org/project/bankstatementparser-writer-swift/) | Output Writer | Exports transactions to SWIFT MT940 customer statements and MT942 interim reports |
|
|
723
|
+
| [`bankstatementparser-loader-bai2`](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2) | [`sebastienrousseau/bankstatementparser-loader-bai2`](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2) | [](https://pypi.org/project/bankstatementparser-loader-bai2/) | Input Loader | Parses BAI2 cash-management and account balance statements |
|
|
724
|
+
| [`bankstatementparser-loader-mt942`](https://github.com/sebastienrousseau/bankstatementparser-loader-mt942) | [`sebastienrousseau/bankstatementparser-loader-mt942`](https://github.com/sebastienrousseau/bankstatementparser-loader-mt942) | [](https://pypi.org/project/bankstatementparser-loader-mt942/) | Input Loader | Parses SWIFT MT942 interim transaction reports with credit/debit summary reconciliation |
|
|
725
|
+
| [`bankstatementparser-loader-cfonb`](https://github.com/sebastienrousseau/bankstatementparser-loader-cfonb) | [`sebastienrousseau/bankstatementparser-loader-cfonb`](https://github.com/sebastienrousseau/bankstatementparser-loader-cfonb) | [](https://pypi.org/project/bankstatementparser-loader-cfonb/) | Input Loader | Parses French CFONB 120 / AFB120 120-byte fixed-width banking statement files |
|
|
726
|
+
| [`bankstatementparser-loader-camt054`](https://github.com/sebastienrousseau/bankstatementparser-loader-camt054) | [`sebastienrousseau/bankstatementparser-loader-camt054`](https://github.com/sebastienrousseau/bankstatementparser-loader-camt054) | [](https://pypi.org/project/bankstatementparser-loader-camt054/) | Input Loader | Ingests ISO 20022 CAMT.054 real-time debit/credit notification stream XML |
|
|
727
|
+
| [`bankstatementparser-loader-sepa`](https://github.com/sebastienrousseau/bankstatementparser-loader-sepa) | [`sebastienrousseau/bankstatementparser-loader-sepa`](https://github.com/sebastienrousseau/bankstatementparser-loader-sepa) | [](https://pypi.org/project/bankstatementparser-loader-sepa/) | Input Loader | Ingests ISO 20022 SEPA PAIN.002 payment status reports and PAIN.008 direct debit mandates |
|
|
728
|
+
| [`bankstatementparser-loader-bacs`](https://github.com/sebastienrousseau/bankstatementparser-loader-bacs) | [`sebastienrousseau/bankstatementparser-loader-bacs`](https://github.com/sebastienrousseau/bankstatementparser-loader-bacs) | [](https://pypi.org/project/bankstatementparser-loader-bacs/) | Input Loader | Parses UK BACS Standard 18 / Faster Payments 106-byte fixed-width transmission files |
|
|
703
729
|
|
|
704
730
|
Loaders turn an additional source format into the same unified
|
|
705
731
|
`Transaction` model; writers take parsed data back out to another
|
|
@@ -707,8 +733,8 @@ target. Each companion pins `bankstatementparser` as a dependency and
|
|
|
707
733
|
ships its own 100%-coverage test suite.
|
|
708
734
|
|
|
709
735
|
```bash
|
|
710
|
-
# Mix and match: e.g.
|
|
711
|
-
pip install bankstatementparser-
|
|
736
|
+
# Mix and match: e.g. fetch via EBICS 3.0, parse CAMT.053, and export to SWIFT MT940 or Excel
|
|
737
|
+
pip install bankstatementparser-transport-ebics bankstatementparser-writer-swift bankstatementparser-writer-xlsx
|
|
712
738
|
```
|
|
713
739
|
|
|
714
740
|
Loaders hand back the same `Transaction` model the core parsers
|
|
@@ -720,15 +746,15 @@ cleanly — see each companion's README for runnable examples.
|
|
|
720
746
|
## Project Layout
|
|
721
747
|
|
|
722
748
|
```text
|
|
723
|
-
bankstatementparser/ Source code (
|
|
749
|
+
bankstatementparser/ Source code (38 modules)
|
|
724
750
|
bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
|
|
725
751
|
bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
|
|
726
|
-
bankstatementparser/export/ hledger + beancount journal export
|
|
752
|
+
bankstatementparser/export/ hledger + beancount journal export, Apache Parquet columnar export
|
|
727
753
|
bankstatementparser/api.py REST API microservice (FastAPI)
|
|
728
754
|
docs/compliance/ ISO 13485 validation, risk register, traceability matrix
|
|
729
755
|
examples/ 14 deterministic + 9 hybrid runnable example scripts
|
|
730
756
|
scripts/ SBOM generation, checksums, signature verification
|
|
731
|
-
tests/
|
|
757
|
+
tests/ 907 tests (unit, integration, property-based, security, hybrid mocks)
|
|
732
758
|
```
|
|
733
759
|
|
|
734
760
|
---
|
|
@@ -1,4 +1,13 @@
|
|
|
1
|
-
<!-- SPDX-License-Identifier: Apache-2.0 OR MIT
|
|
1
|
+
<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img
|
|
5
|
+
src="https://cloudcdn.pro/bankstatementparser/v1/logos/bankstatementparser.svg"
|
|
6
|
+
alt="bankstatementparser logo"
|
|
7
|
+
width="120"
|
|
8
|
+
height="120"
|
|
9
|
+
/>
|
|
10
|
+
</p>
|
|
2
11
|
|
|
3
12
|
<h1 align="center">Bank Statement Parser</h1>
|
|
4
13
|
|
|
@@ -10,7 +19,7 @@
|
|
|
10
19
|
|
|
11
20
|
<p align="center">
|
|
12
21
|
<a href="https://github.com/sebastienrousseau/bankstatementparser/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/bankstatementparser/quality-gates.yml?style=for-the-badge&logo=github" alt="Build" /></a>
|
|
13
|
-
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.
|
|
22
|
+
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.19" alt="PyPI" /></a>
|
|
14
23
|
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/dm/bankstatementparser.svg?style=for-the-badge" alt="PyPI Downloads" /></a>
|
|
15
24
|
<a href="https://codecov.io/github/sebastienrousseau/bankstatementparser?branch=main"><img src="https://img.shields.io/codecov/c/github/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="Codecov" /></a>
|
|
16
25
|
<a href="LICENSE"><img src="https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="License" /></a>
|
|
@@ -187,17 +196,19 @@ from bankstatementparser.hybrid import smart_ingest
|
|
|
187
196
|
|
|
188
197
|
# Path A — deterministic parser (free, fastest, $0)
|
|
189
198
|
result = smart_ingest("statement.xml")
|
|
190
|
-
print(result.source_method)
|
|
199
|
+
print(result.source_method) # "deterministic"
|
|
191
200
|
|
|
192
201
|
# Path B — text-LLM for digital PDFs (set BSP_HYBRID_MODEL=ollama/llama3)
|
|
193
202
|
result = smart_ingest("statement.pdf")
|
|
194
|
-
print(result.source_method)
|
|
195
|
-
print(
|
|
203
|
+
print(result.source_method) # "llm"
|
|
204
|
+
print(
|
|
205
|
+
result.verification.status
|
|
206
|
+
) # VERIFIED | DISCREPANCY | UNVERIFIABLE | FAILED
|
|
196
207
|
|
|
197
208
|
# Path C — multimodal vision for scanned PDFs (set BSP_HYBRID_VISION_MODEL)
|
|
198
209
|
# auto-routed when pypdf cannot extract enough text
|
|
199
210
|
result = smart_ingest("scan.pdf")
|
|
200
|
-
print(result.source_method)
|
|
211
|
+
print(result.source_method) # "vision"
|
|
201
212
|
```
|
|
202
213
|
|
|
203
214
|
Every row carries:
|
|
@@ -235,7 +246,9 @@ For ZIP archives, use `iter_secure_xml_entries()`.
|
|
|
235
246
|
from bankstatementparser import CamtParser, iter_secure_xml_entries
|
|
236
247
|
|
|
237
248
|
for entry in iter_secure_xml_entries("statements.zip"):
|
|
238
|
-
parser = CamtParser.from_bytes(
|
|
249
|
+
parser = CamtParser.from_bytes(
|
|
250
|
+
entry.xml_bytes, source_name=entry.source_name
|
|
251
|
+
)
|
|
239
252
|
transactions = parser.parse()
|
|
240
253
|
print(entry.source_name, len(transactions), "transactions")
|
|
241
254
|
```
|
|
@@ -257,23 +270,23 @@ Gemini, …).
|
|
|
257
270
|
|
|
258
271
|
```mermaid
|
|
259
272
|
flowchart TD
|
|
260
|
-
A[smart_ingest
|
|
261
|
-
B
|
|
262
|
-
C --> Z[IngestResult<br/>source_method='deterministic']
|
|
273
|
+
A["smart_ingest(path)"] --> B{"detect_statement_format"}
|
|
274
|
+
B -->|CAMT/PAIN/OFX/MT940/CSV| C["Path A: deterministic parser<br/>$0, fastest"]
|
|
275
|
+
C --> Z["IngestResult<br/>source_method='deterministic'"]
|
|
263
276
|
|
|
264
|
-
B
|
|
265
|
-
D --> E{text
|
|
277
|
+
B -->|pdf or unknown| D["pypdf extract_text"]
|
|
278
|
+
D --> E{"text length >= 50?"}
|
|
266
279
|
|
|
267
|
-
E
|
|
268
|
-
F --> Y[IngestResult<br/>source_method='llm']
|
|
280
|
+
E -->|yes| F["Path B: text-LLM<br/>default ollama/llama3"]
|
|
281
|
+
F --> Y["IngestResult<br/>source_method='llm'"]
|
|
269
282
|
|
|
270
|
-
E
|
|
271
|
-
G --> X[IngestResult<br/>source_method='vision']
|
|
283
|
+
E -->|no| G["Path C: vision-LLM<br/>opt-in via BSP_HYBRID_VISION_MODEL"]
|
|
284
|
+
G --> X["IngestResult<br/>source_method='vision'"]
|
|
272
285
|
|
|
273
|
-
Z --> V[verify_balance<br/>Golden Rule]
|
|
286
|
+
Z --> V["verify_balance<br/>Golden Rule"]
|
|
274
287
|
Y --> V
|
|
275
288
|
X --> V
|
|
276
|
-
V --> R[VERIFIED / DISCREPANCY / UNVERIFIABLE / FAILED]
|
|
289
|
+
V --> R["VERIFIED / DISCREPANCY / UNVERIFIABLE / FAILED"]
|
|
277
290
|
```
|
|
278
291
|
|
|
279
292
|
Every extracted row carries an immutable `transaction_hash`, an
|
|
@@ -332,7 +345,7 @@ for the full surface.
|
|
|
332
345
|
|---|---|
|
|
333
346
|
| **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
|
|
334
347
|
| **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
|
|
335
|
-
| **Tested** |
|
|
348
|
+
| **Tested** | 907 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
|
|
336
349
|
|
|
337
350
|
---
|
|
338
351
|
|
|
@@ -399,11 +412,13 @@ Process multiple files simultaneously across CPU cores:
|
|
|
399
412
|
```python
|
|
400
413
|
from bankstatementparser import parse_files_parallel
|
|
401
414
|
|
|
402
|
-
results = parse_files_parallel(
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
415
|
+
results = parse_files_parallel(
|
|
416
|
+
[
|
|
417
|
+
"statements/jan.xml",
|
|
418
|
+
"statements/feb.xml",
|
|
419
|
+
"statements/mar.xml",
|
|
420
|
+
]
|
|
421
|
+
)
|
|
407
422
|
|
|
408
423
|
for r in results:
|
|
409
424
|
print(r.path, r.status, len(r.transactions), "rows")
|
|
@@ -652,13 +667,22 @@ versioned companion packages build on it — each is its own repository
|
|
|
652
667
|
and Python package, so you install only what you need and the core
|
|
653
668
|
stays dependency-light.
|
|
654
669
|
|
|
655
|
-
| Package | PyPI | Role |
|
|
656
|
-
|
|
657
|
-
| [`bankstatementparser
|
|
658
|
-
| [`bankstatementparser-
|
|
659
|
-
| [`bankstatementparser-
|
|
660
|
-
| [`bankstatementparser-
|
|
661
|
-
| [`bankstatementparser-
|
|
670
|
+
| Package | GitHub Repository | PyPI | Role | Description |
|
|
671
|
+
|---|---|---|---|---|
|
|
672
|
+
| [`bankstatementparser`](https://github.com/sebastienrousseau/bankstatementparser) | [`sebastienrousseau/bankstatementparser`](https://github.com/sebastienrousseau/bankstatementparser) | [](https://pypi.org/project/bankstatementparser/) | Core Engine | Unified parser for CAMT (052/053), PAIN.001, CSV, OFX, QFX, MT940, and PDF statements |
|
|
673
|
+
| [`bankstatementparser-mcp`](https://github.com/sebastienrousseau/bankstatementparser-mcp) | [`sebastienrousseau/bankstatementparser-mcp`](https://github.com/sebastienrousseau/bankstatementparser-mcp) | [](https://pypi.org/project/bankstatementparser-mcp/) | AI Protocol | Model Context Protocol (MCP) server exposing statement tools to LLMs & AI agents |
|
|
674
|
+
| [`bankstatementparser-lsp`](https://github.com/sebastienrousseau/bankstatementparser-lsp) | [`sebastienrousseau/bankstatementparser-lsp`](https://github.com/sebastienrousseau/bankstatementparser-lsp) | [](https://pypi.org/project/bankstatementparser-lsp/) | Developer Tooling | Language Server Protocol (LSP) with live SWIFT MT940 statement validation & diagnostics |
|
|
675
|
+
| [`bankstatementparser-transport-ebics`](https://github.com/sebastienrousseau/bankstatementparser-transport-ebics) | [`sebastienrousseau/bankstatementparser-transport-ebics`](https://github.com/sebastienrousseau/bankstatementparser-transport-ebics) | [](https://pypi.org/project/bankstatementparser-transport-ebics/) | Transport | Automated bank statement retrieval over EBICS 3.0 (`H005`) and 2.5 (`H004`) protocols |
|
|
676
|
+
| [`bankstatementparser-writer-xlsx`](https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx) | [`sebastienrousseau/bankstatementparser-writer-xlsx`](https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx) | [](https://pypi.org/project/bankstatementparser-writer-xlsx/) | Output Writer | Formats and exports parsed banking transactions into styled Microsoft Excel (`.xlsx`) workbooks |
|
|
677
|
+
| [`bankstatementparser-writer-qif`](https://github.com/sebastienrousseau/bankstatementparser-writer-qif) | [`sebastienrousseau/bankstatementparser-writer-qif`](https://github.com/sebastienrousseau/bankstatementparser-writer-qif) | [](https://pypi.org/project/bankstatementparser-writer-qif/) | Output Writer | Serializes transactions into standard Quicken Interchange Format (`.qif`) exchange files |
|
|
678
|
+
| [`bankstatementparser-writer-ofx`](https://github.com/sebastienrousseau/bankstatementparser-writer-ofx) | [`sebastienrousseau/bankstatementparser-writer-ofx`](https://github.com/sebastienrousseau/bankstatementparser-writer-ofx) | [](https://pypi.org/project/bankstatementparser-writer-ofx/) | Output Writer | Serializes transactions into standard Open Financial Exchange (`.ofx`) XML/SGML files |
|
|
679
|
+
| [`bankstatementparser-writer-swift`](https://github.com/sebastienrousseau/bankstatementparser-writer-swift) | [`sebastienrousseau/bankstatementparser-writer-swift`](https://github.com/sebastienrousseau/bankstatementparser-writer-swift) | [](https://pypi.org/project/bankstatementparser-writer-swift/) | Output Writer | Exports transactions to SWIFT MT940 customer statements and MT942 interim reports |
|
|
680
|
+
| [`bankstatementparser-loader-bai2`](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2) | [`sebastienrousseau/bankstatementparser-loader-bai2`](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2) | [](https://pypi.org/project/bankstatementparser-loader-bai2/) | Input Loader | Parses BAI2 cash-management and account balance statements |
|
|
681
|
+
| [`bankstatementparser-loader-mt942`](https://github.com/sebastienrousseau/bankstatementparser-loader-mt942) | [`sebastienrousseau/bankstatementparser-loader-mt942`](https://github.com/sebastienrousseau/bankstatementparser-loader-mt942) | [](https://pypi.org/project/bankstatementparser-loader-mt942/) | Input Loader | Parses SWIFT MT942 interim transaction reports with credit/debit summary reconciliation |
|
|
682
|
+
| [`bankstatementparser-loader-cfonb`](https://github.com/sebastienrousseau/bankstatementparser-loader-cfonb) | [`sebastienrousseau/bankstatementparser-loader-cfonb`](https://github.com/sebastienrousseau/bankstatementparser-loader-cfonb) | [](https://pypi.org/project/bankstatementparser-loader-cfonb/) | Input Loader | Parses French CFONB 120 / AFB120 120-byte fixed-width banking statement files |
|
|
683
|
+
| [`bankstatementparser-loader-camt054`](https://github.com/sebastienrousseau/bankstatementparser-loader-camt054) | [`sebastienrousseau/bankstatementparser-loader-camt054`](https://github.com/sebastienrousseau/bankstatementparser-loader-camt054) | [](https://pypi.org/project/bankstatementparser-loader-camt054/) | Input Loader | Ingests ISO 20022 CAMT.054 real-time debit/credit notification stream XML |
|
|
684
|
+
| [`bankstatementparser-loader-sepa`](https://github.com/sebastienrousseau/bankstatementparser-loader-sepa) | [`sebastienrousseau/bankstatementparser-loader-sepa`](https://github.com/sebastienrousseau/bankstatementparser-loader-sepa) | [](https://pypi.org/project/bankstatementparser-loader-sepa/) | Input Loader | Ingests ISO 20022 SEPA PAIN.002 payment status reports and PAIN.008 direct debit mandates |
|
|
685
|
+
| [`bankstatementparser-loader-bacs`](https://github.com/sebastienrousseau/bankstatementparser-loader-bacs) | [`sebastienrousseau/bankstatementparser-loader-bacs`](https://github.com/sebastienrousseau/bankstatementparser-loader-bacs) | [](https://pypi.org/project/bankstatementparser-loader-bacs/) | Input Loader | Parses UK BACS Standard 18 / Faster Payments 106-byte fixed-width transmission files |
|
|
662
686
|
|
|
663
687
|
Loaders turn an additional source format into the same unified
|
|
664
688
|
`Transaction` model; writers take parsed data back out to another
|
|
@@ -666,8 +690,8 @@ target. Each companion pins `bankstatementparser` as a dependency and
|
|
|
666
690
|
ships its own 100%-coverage test suite.
|
|
667
691
|
|
|
668
692
|
```bash
|
|
669
|
-
# Mix and match: e.g.
|
|
670
|
-
pip install bankstatementparser-
|
|
693
|
+
# Mix and match: e.g. fetch via EBICS 3.0, parse CAMT.053, and export to SWIFT MT940 or Excel
|
|
694
|
+
pip install bankstatementparser-transport-ebics bankstatementparser-writer-swift bankstatementparser-writer-xlsx
|
|
671
695
|
```
|
|
672
696
|
|
|
673
697
|
Loaders hand back the same `Transaction` model the core parsers
|
|
@@ -679,15 +703,15 @@ cleanly — see each companion's README for runnable examples.
|
|
|
679
703
|
## Project Layout
|
|
680
704
|
|
|
681
705
|
```text
|
|
682
|
-
bankstatementparser/ Source code (
|
|
706
|
+
bankstatementparser/ Source code (38 modules)
|
|
683
707
|
bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
|
|
684
708
|
bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
|
|
685
|
-
bankstatementparser/export/ hledger + beancount journal export
|
|
709
|
+
bankstatementparser/export/ hledger + beancount journal export, Apache Parquet columnar export
|
|
686
710
|
bankstatementparser/api.py REST API microservice (FastAPI)
|
|
687
711
|
docs/compliance/ ISO 13485 validation, risk register, traceability matrix
|
|
688
712
|
examples/ 14 deterministic + 9 hybrid runnable example scripts
|
|
689
713
|
scripts/ SBOM generation, checksums, signature verification
|
|
690
|
-
tests/
|
|
714
|
+
tests/ 907 tests (unit, integration, property-based, security, hybrid mocks)
|
|
691
715
|
```
|
|
692
716
|
|
|
693
717
|
---
|
|
@@ -27,6 +27,17 @@ from .additional_parsers import (
|
|
|
27
27
|
create_parser,
|
|
28
28
|
detect_statement_format,
|
|
29
29
|
)
|
|
30
|
+
from .analytics import (
|
|
31
|
+
AnalyticsReport,
|
|
32
|
+
AnomalyFinding,
|
|
33
|
+
CashFlowMetrics,
|
|
34
|
+
RecurringCadence,
|
|
35
|
+
RecurringPattern,
|
|
36
|
+
analyze_statement_transactions,
|
|
37
|
+
compute_cash_flow_summary,
|
|
38
|
+
detect_anomalies_and_nsf,
|
|
39
|
+
detect_recurring_transactions,
|
|
40
|
+
)
|
|
30
41
|
from .base_parser import BankStatementParser
|
|
31
42
|
from .camt_parser import CamtParser
|
|
32
43
|
from .exceptions import (
|
|
@@ -35,9 +46,29 @@ from .exceptions import (
|
|
|
35
46
|
Pain001ParseError,
|
|
36
47
|
ParserError,
|
|
37
48
|
)
|
|
49
|
+
from .export.parquet import export_parquet
|
|
50
|
+
from .field86_parser import Field86Structure, parse_field_86
|
|
51
|
+
from .forensics import (
|
|
52
|
+
ForensicFinding,
|
|
53
|
+
ForensicsReport,
|
|
54
|
+
ForensicVerdict,
|
|
55
|
+
inspect_pdf_forensics,
|
|
56
|
+
)
|
|
38
57
|
from .input_validator import InputValidator, ValidationError
|
|
39
58
|
from .pain001_parser import Pain001Parser
|
|
40
59
|
from .parallel import FileResult, parse_files_parallel
|
|
60
|
+
from .plugins import (
|
|
61
|
+
discover_loaders,
|
|
62
|
+
discover_writers,
|
|
63
|
+
register_loader,
|
|
64
|
+
register_writer,
|
|
65
|
+
)
|
|
66
|
+
from .reconciliation import (
|
|
67
|
+
ReconciliationMatch,
|
|
68
|
+
ReconciliationReport,
|
|
69
|
+
ReconciliationStatus,
|
|
70
|
+
reconcile_payments_and_statements,
|
|
71
|
+
)
|
|
41
72
|
from .transaction_deduplicator import (
|
|
42
73
|
DeduplicationResult,
|
|
43
74
|
Deduplicator,
|
|
@@ -47,7 +78,9 @@ from .transaction_deduplicator import (
|
|
|
47
78
|
from .transaction_models import BoundingBox, Transaction
|
|
48
79
|
from .zip_security import (
|
|
49
80
|
ZipSecurityError,
|
|
81
|
+
ZipStatementSource,
|
|
50
82
|
ZipXMLSource,
|
|
83
|
+
iter_secure_statement_entries,
|
|
51
84
|
iter_secure_xml_entries,
|
|
52
85
|
)
|
|
53
86
|
|
|
@@ -56,19 +89,26 @@ from .zip_security import (
|
|
|
56
89
|
#: so the conformance gate can compare it statically against
|
|
57
90
|
#: pyproject.toml -- that comparison is the thing that catches drift, and
|
|
58
91
|
#: a runtime lookup would make the two trivially equal and check nothing.
|
|
59
|
-
__version__ = "0.0.
|
|
92
|
+
__version__ = "0.0.19"
|
|
60
93
|
|
|
61
94
|
__all__ = [
|
|
95
|
+
"AnalyticsReport",
|
|
96
|
+
"AnomalyFinding",
|
|
62
97
|
"BankStatementParser",
|
|
63
98
|
"BankStatementParserError",
|
|
64
99
|
"BoundingBox",
|
|
65
100
|
"CamtParser",
|
|
101
|
+
"CashFlowMetrics",
|
|
66
102
|
"CsvStatementParser",
|
|
67
103
|
"DeduplicationResult",
|
|
68
104
|
"Deduplicator",
|
|
69
105
|
"ExactDuplicateGroup",
|
|
70
106
|
"ExportError",
|
|
107
|
+
"Field86Structure",
|
|
71
108
|
"FileResult",
|
|
109
|
+
"ForensicFinding",
|
|
110
|
+
"ForensicVerdict",
|
|
111
|
+
"ForensicsReport",
|
|
72
112
|
"InputValidator",
|
|
73
113
|
"MatchGroup",
|
|
74
114
|
"Mt940Parser",
|
|
@@ -77,13 +117,32 @@ __all__ = [
|
|
|
77
117
|
"Pain001Parser",
|
|
78
118
|
"ParserError",
|
|
79
119
|
"QfxParser",
|
|
120
|
+
"ReconciliationMatch",
|
|
121
|
+
"ReconciliationReport",
|
|
122
|
+
"ReconciliationStatus",
|
|
123
|
+
"RecurringCadence",
|
|
124
|
+
"RecurringPattern",
|
|
80
125
|
"Transaction",
|
|
81
126
|
"ValidationError",
|
|
82
127
|
"ZipSecurityError",
|
|
128
|
+
"ZipStatementSource",
|
|
83
129
|
"ZipXMLSource",
|
|
84
130
|
"__version__",
|
|
131
|
+
"analyze_statement_transactions",
|
|
132
|
+
"compute_cash_flow_summary",
|
|
85
133
|
"create_parser",
|
|
134
|
+
"detect_anomalies_and_nsf",
|
|
135
|
+
"detect_recurring_transactions",
|
|
86
136
|
"detect_statement_format",
|
|
137
|
+
"discover_loaders",
|
|
138
|
+
"discover_writers",
|
|
139
|
+
"export_parquet",
|
|
140
|
+
"inspect_pdf_forensics",
|
|
141
|
+
"iter_secure_statement_entries",
|
|
87
142
|
"iter_secure_xml_entries",
|
|
143
|
+
"parse_field_86",
|
|
88
144
|
"parse_files_parallel",
|
|
145
|
+
"reconcile_payments_and_statements",
|
|
146
|
+
"register_loader",
|
|
147
|
+
"register_writer",
|
|
89
148
|
]
|
{bankstatementparser-0.0.18 → bankstatementparser-0.0.19}/bankstatementparser/_llm_common.py
RENAMED
|
@@ -47,7 +47,12 @@ OLLAMA_PREFIX_RE = re.compile(r"^ollama(?:_chat)?/", re.IGNORECASE)
|
|
|
47
47
|
|
|
48
48
|
_LOCAL_HOSTNAMES = frozenset(
|
|
49
49
|
# Matched against, never bound to — this is an allowlist of local hosts
|
|
50
|
-
{
|
|
50
|
+
{
|
|
51
|
+
"localhost",
|
|
52
|
+
"127.0.0.1",
|
|
53
|
+
"::1",
|
|
54
|
+
"0.0.0.0", # noqa: S104
|
|
55
|
+
} # nosec B104
|
|
51
56
|
)
|
|
52
57
|
|
|
53
58
|
# (model, api_base) pairs already warned about, so a batch run
|