bankstatementparser 0.0.23__tar.gz → 0.0.25__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.23 → bankstatementparser-0.0.25}/PKG-INFO +9 -6
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/README.md +6 -4
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/__init__.py +15 -1
- bankstatementparser-0.0.25/bankstatementparser/additional_parsers.py +150 -0
- bankstatementparser-0.0.25/bankstatementparser/analytics/__init__.py +50 -0
- bankstatementparser-0.0.25/bankstatementparser/analytics/cash_flow.py +247 -0
- bankstatementparser-0.0.25/bankstatementparser/analytics/common.py +104 -0
- bankstatementparser-0.0.25/bankstatementparser/analytics/models.py +155 -0
- bankstatementparser-0.0.25/bankstatementparser/analytics/patterns.py +291 -0
- bankstatementparser-0.0.25/bankstatementparser/api.py +263 -0
- bankstatementparser-0.0.25/bankstatementparser/api_limits.py +226 -0
- bankstatementparser-0.0.25/bankstatementparser/api_worker.py +150 -0
- bankstatementparser-0.0.25/bankstatementparser/field86_parser.py +204 -0
- bankstatementparser-0.0.25/bankstatementparser/parsers/__init__.py +49 -0
- bankstatementparser-0.0.25/bankstatementparser/parsers/common.py +233 -0
- bankstatementparser-0.0.25/bankstatementparser/parsers/csv_parser.py +141 -0
- bankstatementparser-0.0.25/bankstatementparser/parsers/mt940.py +268 -0
- bankstatementparser-0.0.25/bankstatementparser/parsers/ofx.py +115 -0
- bankstatementparser-0.0.25/bankstatementparser/telemetry.py +177 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/pyproject.toml +25 -3
- bankstatementparser-0.0.23/bankstatementparser/additional_parsers.py +0 -632
- bankstatementparser-0.0.23/bankstatementparser/analytics.py +0 -691
- bankstatementparser-0.0.23/bankstatementparser/api.py +0 -583
- bankstatementparser-0.0.23/bankstatementparser/field86_parser.py +0 -186
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/LICENSE +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/LICENSE-APACHE +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/LICENSE-MIT +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/_amounts.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/_llm_common.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/bank_statement_parsers.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/base_parser.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/camt_parser.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/cli.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/__init__.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/account_mapper.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/categorizer.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/exceptions.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/export/__init__.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/export/ledger.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/export/parquet.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/forensics.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/__init__.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/evaluation.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/llm_extractor.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/ollama_direct.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/orchestrator.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/pdf_text.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/prompts.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/scanner.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/verification.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/vision.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/input_validator.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/pain001_parser.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/parallel.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/plugins.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/privacy.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/py.typed +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/reconciliation.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/record_types.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/transaction_deduplicator.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/transaction_models.py +0 -0
- {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/zip_security.py +0 -0
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: bankstatementparser
|
|
3
|
-
Version: 0.0.
|
|
4
|
-
Summary:
|
|
3
|
+
Version: 0.0.25
|
|
4
|
+
Summary: Parse bank statements (CAMT.053, PAIN.001, MT940, OFX, BAI2, CSV, and PDF) into unified Transactions with treasury analytics, 2-way reconciliation, PDF forensics, and ledger export.
|
|
5
5
|
License: Apache-2.0 OR MIT
|
|
6
6
|
License-File: LICENSE
|
|
7
7
|
License-File: LICENSE-APACHE
|
|
8
8
|
License-File: LICENSE-MIT
|
|
9
|
+
Keywords: banking,finance,iso20022,camt053,pain001,mt940,ofx,bai2,sepa,fintech,treasury,python,reconciliation,hledger,beancount,parquet,pdf-parsing,fastapi,cli,bank-statements
|
|
9
10
|
Author: Sebastien Rousseau
|
|
10
11
|
Author-email: sebastian.rousseau@gmail.com
|
|
11
12
|
Requires-Python: >=3.10,<4.0
|
|
@@ -63,7 +64,7 @@ Description-Content-Type: text/markdown
|
|
|
63
64
|
|
|
64
65
|
<p align="center">
|
|
65
66
|
<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>
|
|
66
|
-
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.
|
|
67
|
+
<a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.25" alt="PyPI" /></a>
|
|
67
68
|
<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>
|
|
68
69
|
<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>
|
|
69
70
|
<a href="LICENSE"><img src="https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="License" /></a>
|
|
@@ -389,7 +390,7 @@ for the full surface.
|
|
|
389
390
|
|---|---|
|
|
390
391
|
| **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
|
|
391
392
|
| **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
|
|
392
|
-
| **Tested** |
|
|
393
|
+
| **Tested** | 1023 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
|
|
393
394
|
|
|
394
395
|
---
|
|
395
396
|
|
|
@@ -749,7 +750,9 @@ cleanly — see each companion's README for runnable examples.
|
|
|
749
750
|
## Project Layout
|
|
750
751
|
|
|
751
752
|
```text
|
|
752
|
-
bankstatementparser/ Source code (
|
|
753
|
+
bankstatementparser/ Source code (51 modules)
|
|
754
|
+
bankstatementparser/analytics/ Financial metrics, cash flow, cadence & anomaly detection
|
|
755
|
+
bankstatementparser/parsers/ Modular statement parsers (CSV, MT940, OFX/QFX)
|
|
753
756
|
bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
|
|
754
757
|
bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
|
|
755
758
|
bankstatementparser/export/ hledger + beancount journal export, Apache Parquet columnar export
|
|
@@ -757,7 +760,7 @@ bankstatementparser/api.py REST API microservice (FastAPI)
|
|
|
757
760
|
docs/compliance/ ISO 13485 validation, risk register, traceability matrix
|
|
758
761
|
examples/ 14 deterministic + 9 hybrid runnable example scripts
|
|
759
762
|
scripts/ SBOM generation, checksums, signature verification
|
|
760
|
-
tests/
|
|
763
|
+
tests/ 1023 tests (unit, integration, property-based, security, hybrid mocks)
|
|
761
764
|
```
|
|
762
765
|
|
|
763
766
|
---
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
|
|
20
20
|
<p align="center">
|
|
21
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>
|
|
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.
|
|
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.25" alt="PyPI" /></a>
|
|
23
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>
|
|
24
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>
|
|
25
25
|
<a href="LICENSE"><img src="https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="License" /></a>
|
|
@@ -345,7 +345,7 @@ for the full surface.
|
|
|
345
345
|
|---|---|
|
|
346
346
|
| **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
|
|
347
347
|
| **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
|
|
348
|
-
| **Tested** |
|
|
348
|
+
| **Tested** | 1023 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
|
|
349
349
|
|
|
350
350
|
---
|
|
351
351
|
|
|
@@ -705,7 +705,9 @@ cleanly — see each companion's README for runnable examples.
|
|
|
705
705
|
## Project Layout
|
|
706
706
|
|
|
707
707
|
```text
|
|
708
|
-
bankstatementparser/ Source code (
|
|
708
|
+
bankstatementparser/ Source code (51 modules)
|
|
709
|
+
bankstatementparser/analytics/ Financial metrics, cash flow, cadence & anomaly detection
|
|
710
|
+
bankstatementparser/parsers/ Modular statement parsers (CSV, MT940, OFX/QFX)
|
|
709
711
|
bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
|
|
710
712
|
bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
|
|
711
713
|
bankstatementparser/export/ hledger + beancount journal export, Apache Parquet columnar export
|
|
@@ -713,7 +715,7 @@ bankstatementparser/api.py REST API microservice (FastAPI)
|
|
|
713
715
|
docs/compliance/ ISO 13485 validation, risk register, traceability matrix
|
|
714
716
|
examples/ 14 deterministic + 9 hybrid runnable example scripts
|
|
715
717
|
scripts/ SBOM generation, checksums, signature verification
|
|
716
|
-
tests/
|
|
718
|
+
tests/ 1023 tests (unit, integration, property-based, security, hybrid mocks)
|
|
717
719
|
```
|
|
718
720
|
|
|
719
721
|
---
|
|
@@ -71,6 +71,14 @@ from .reconciliation import (
|
|
|
71
71
|
ReconciliationStatus,
|
|
72
72
|
reconcile_payments_and_statements,
|
|
73
73
|
)
|
|
74
|
+
from .telemetry import (
|
|
75
|
+
NullSpan,
|
|
76
|
+
is_telemetry_available,
|
|
77
|
+
trace_async_stream,
|
|
78
|
+
trace_span,
|
|
79
|
+
trace_stream,
|
|
80
|
+
traced,
|
|
81
|
+
)
|
|
74
82
|
from .transaction_deduplicator import (
|
|
75
83
|
DeduplicationResult,
|
|
76
84
|
Deduplicator,
|
|
@@ -91,7 +99,7 @@ from .zip_security import (
|
|
|
91
99
|
#: so the conformance gate can compare it statically against
|
|
92
100
|
#: pyproject.toml -- that comparison is the thing that catches drift, and
|
|
93
101
|
#: a runtime lookup would make the two trivially equal and check nothing.
|
|
94
|
-
__version__ = "0.0.
|
|
102
|
+
__version__ = "0.0.25"
|
|
95
103
|
|
|
96
104
|
__all__ = [
|
|
97
105
|
"AnalyticsReport",
|
|
@@ -115,6 +123,7 @@ __all__ = [
|
|
|
115
123
|
"InputValidator",
|
|
116
124
|
"MatchGroup",
|
|
117
125
|
"Mt940Parser",
|
|
126
|
+
"NullSpan",
|
|
118
127
|
"OfxParser",
|
|
119
128
|
"Pain001ParseError",
|
|
120
129
|
"Pain001Parser",
|
|
@@ -143,6 +152,7 @@ __all__ = [
|
|
|
143
152
|
"export_parquet",
|
|
144
153
|
"export_parquet_stream",
|
|
145
154
|
"inspect_pdf_forensics",
|
|
155
|
+
"is_telemetry_available",
|
|
146
156
|
"iter_files_parallel",
|
|
147
157
|
"iter_secure_statement_entries",
|
|
148
158
|
"iter_secure_xml_entries",
|
|
@@ -151,4 +161,8 @@ __all__ = [
|
|
|
151
161
|
"reconcile_payments_and_statements",
|
|
152
162
|
"register_loader",
|
|
153
163
|
"register_writer",
|
|
164
|
+
"trace_async_stream",
|
|
165
|
+
"trace_span",
|
|
166
|
+
"trace_stream",
|
|
167
|
+
"traced",
|
|
154
168
|
]
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
|
|
2
|
+
#
|
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
# you may not use this file except in compliance with the License.
|
|
5
|
+
# You may obtain a copy of the License at
|
|
6
|
+
#
|
|
7
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
#
|
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
12
|
+
# implied.
|
|
13
|
+
# See the License for the specific language governing permissions and
|
|
14
|
+
# limitations under the License.
|
|
15
|
+
|
|
16
|
+
"""Additional bank statement parsers and format detection helpers."""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
|
|
22
|
+
from .base_parser import BankStatementParser
|
|
23
|
+
from .camt_parser import CamtParser
|
|
24
|
+
from .input_validator import ValidationError
|
|
25
|
+
from .pain001_parser import Pain001Parser
|
|
26
|
+
from .parsers import (
|
|
27
|
+
CSV_COLUMN_GROUPS,
|
|
28
|
+
CsvStatementParser,
|
|
29
|
+
Mt940Parser,
|
|
30
|
+
OfxParser,
|
|
31
|
+
QfxParser,
|
|
32
|
+
_amount_or_zero,
|
|
33
|
+
_grouped_summaries,
|
|
34
|
+
_normalize_delimiters,
|
|
35
|
+
_normalized_name,
|
|
36
|
+
_parse_amount,
|
|
37
|
+
_read_validated_text,
|
|
38
|
+
_require_amount,
|
|
39
|
+
_summary_text,
|
|
40
|
+
)
|
|
41
|
+
from .plugins import get_registered_loaders
|
|
42
|
+
|
|
43
|
+
__all__ = [
|
|
44
|
+
"CSV_COLUMN_GROUPS",
|
|
45
|
+
"CsvStatementParser",
|
|
46
|
+
"Mt940Parser",
|
|
47
|
+
"OfxParser",
|
|
48
|
+
"QfxParser",
|
|
49
|
+
"_amount_or_zero",
|
|
50
|
+
"_grouped_summaries",
|
|
51
|
+
"_normalize_delimiters",
|
|
52
|
+
"_normalized_name",
|
|
53
|
+
"_parse_amount",
|
|
54
|
+
"_read_validated_text",
|
|
55
|
+
"_require_amount",
|
|
56
|
+
"_summary_text",
|
|
57
|
+
"create_parser",
|
|
58
|
+
"detect_statement_format",
|
|
59
|
+
]
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _detect_by_suffix(suffix: str) -> str | None:
|
|
63
|
+
"""Detect statement format from file extension."""
|
|
64
|
+
if suffix == ".csv":
|
|
65
|
+
return "csv"
|
|
66
|
+
if suffix in {".ofx", ".qfx"}:
|
|
67
|
+
return "ofx"
|
|
68
|
+
if suffix in {".mt940", ".sta"}:
|
|
69
|
+
return "mt940"
|
|
70
|
+
if suffix == ".bai2":
|
|
71
|
+
return "bai2"
|
|
72
|
+
if suffix == ".mt942":
|
|
73
|
+
return "mt942"
|
|
74
|
+
return None
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _detect_xml_format(lowered: str) -> str | None:
|
|
78
|
+
"""Detect statement format from XML content tags."""
|
|
79
|
+
if "cstmrcdttrfinitn" in lowered or "pain.001" in lowered:
|
|
80
|
+
return "pain001"
|
|
81
|
+
if "bktocstmrstmt" in lowered or "camt." in lowered:
|
|
82
|
+
return "camt"
|
|
83
|
+
return None
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _detect_by_content(text: str, lowered: str) -> str | None:
|
|
87
|
+
"""Detect statement format from file text contents."""
|
|
88
|
+
if text.startswith("01,") or "\n01," in text:
|
|
89
|
+
return "bai2"
|
|
90
|
+
if ":34F:" in text and ":61:" in text:
|
|
91
|
+
return "mt942"
|
|
92
|
+
if "<ofx>" in lowered or "<banktranlist>" in lowered:
|
|
93
|
+
return "ofx"
|
|
94
|
+
if ":20:" in text and ":61:" in text:
|
|
95
|
+
return "mt940"
|
|
96
|
+
return None
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _detect_by_plugin(suffix: str) -> str | None:
|
|
100
|
+
"""Detect statement format using registered loader plugins."""
|
|
101
|
+
loaders = get_registered_loaders()
|
|
102
|
+
for name in loaders:
|
|
103
|
+
if suffix == f".{name}" or name in suffix:
|
|
104
|
+
return name
|
|
105
|
+
return None
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def detect_statement_format(file_name: str | Path) -> str:
|
|
109
|
+
"""Detect the parser format for a bank statement file."""
|
|
110
|
+
path, text = _read_validated_text(file_name)
|
|
111
|
+
suffix = path.suffix.lower()
|
|
112
|
+
lowered = text.lower()
|
|
113
|
+
|
|
114
|
+
if suffix == ".xml":
|
|
115
|
+
xml_fmt = _detect_xml_format(lowered)
|
|
116
|
+
if xml_fmt is not None:
|
|
117
|
+
return xml_fmt
|
|
118
|
+
|
|
119
|
+
detected = (
|
|
120
|
+
_detect_by_suffix(suffix)
|
|
121
|
+
or _detect_by_content(text, lowered)
|
|
122
|
+
or _detect_by_plugin(suffix)
|
|
123
|
+
)
|
|
124
|
+
if detected is not None:
|
|
125
|
+
return detected
|
|
126
|
+
|
|
127
|
+
raise ValidationError(f"Unable to detect statement format: {path}")
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def create_parser(
|
|
131
|
+
file_name: str | Path,
|
|
132
|
+
format_name: str | None = None,
|
|
133
|
+
) -> BankStatementParser:
|
|
134
|
+
"""Create a parser instance from an explicit or detected format."""
|
|
135
|
+
selected = (format_name or detect_statement_format(file_name)).lower()
|
|
136
|
+
parser_map: dict[str, type[BankStatementParser]] = {
|
|
137
|
+
"camt": CamtParser,
|
|
138
|
+
"pain001": Pain001Parser,
|
|
139
|
+
"csv": CsvStatementParser,
|
|
140
|
+
"ofx": OfxParser,
|
|
141
|
+
"qfx": QfxParser,
|
|
142
|
+
"mt940": Mt940Parser,
|
|
143
|
+
}
|
|
144
|
+
# Augment with dynamic plugins
|
|
145
|
+
parser_map.update(get_registered_loaders())
|
|
146
|
+
|
|
147
|
+
if selected not in parser_map:
|
|
148
|
+
raise ValidationError(f"Unsupported statement format: {selected}")
|
|
149
|
+
parser_cls = parser_map[selected]
|
|
150
|
+
return parser_cls(str(file_name))
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0 OR MIT
|
|
2
|
+
# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
|
|
3
|
+
|
|
4
|
+
"""Treasury Cash-Flow Spreading, Cadence Detection, and Anomaly Engine."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from .cash_flow import (
|
|
9
|
+
compute_average_daily_balance,
|
|
10
|
+
compute_cash_flow_summary,
|
|
11
|
+
)
|
|
12
|
+
from .common import (
|
|
13
|
+
_amount_and_direction,
|
|
14
|
+
_calendar_months,
|
|
15
|
+
_extract_amount,
|
|
16
|
+
_extract_date,
|
|
17
|
+
_get_attr,
|
|
18
|
+
)
|
|
19
|
+
from .models import (
|
|
20
|
+
AnalyticsReport,
|
|
21
|
+
AnomalyFinding,
|
|
22
|
+
CashFlowMetrics,
|
|
23
|
+
DailyBalanceMetrics,
|
|
24
|
+
RecurringCadence,
|
|
25
|
+
RecurringPattern,
|
|
26
|
+
)
|
|
27
|
+
from .patterns import (
|
|
28
|
+
analyze_statement_transactions,
|
|
29
|
+
detect_anomalies_and_nsf,
|
|
30
|
+
detect_recurring_transactions,
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
__all__ = [
|
|
34
|
+
"AnalyticsReport",
|
|
35
|
+
"AnomalyFinding",
|
|
36
|
+
"CashFlowMetrics",
|
|
37
|
+
"DailyBalanceMetrics",
|
|
38
|
+
"RecurringCadence",
|
|
39
|
+
"RecurringPattern",
|
|
40
|
+
"_amount_and_direction",
|
|
41
|
+
"_calendar_months",
|
|
42
|
+
"_extract_amount",
|
|
43
|
+
"_extract_date",
|
|
44
|
+
"_get_attr",
|
|
45
|
+
"analyze_statement_transactions",
|
|
46
|
+
"compute_average_daily_balance",
|
|
47
|
+
"compute_cash_flow_summary",
|
|
48
|
+
"detect_anomalies_and_nsf",
|
|
49
|
+
"detect_recurring_transactions",
|
|
50
|
+
]
|
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0 OR MIT
|
|
2
|
+
# Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
|
|
3
|
+
|
|
4
|
+
"""Cash-flow spreading and average daily balance computation."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from calendar import monthrange
|
|
9
|
+
from collections import defaultdict
|
|
10
|
+
from collections.abc import Iterable
|
|
11
|
+
from datetime import date
|
|
12
|
+
from decimal import Decimal
|
|
13
|
+
from typing import Any
|
|
14
|
+
|
|
15
|
+
from .._amounts import iso_decimal
|
|
16
|
+
from .common import (
|
|
17
|
+
_amount_and_direction,
|
|
18
|
+
_calendar_months,
|
|
19
|
+
_extract_date,
|
|
20
|
+
_get_attr,
|
|
21
|
+
)
|
|
22
|
+
from .models import CashFlowMetrics, DailyBalanceMetrics
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _process_daily_balance_tx(
|
|
26
|
+
tx: Any,
|
|
27
|
+
currency: str,
|
|
28
|
+
account_id: str | None,
|
|
29
|
+
period_start: date,
|
|
30
|
+
period_end: date,
|
|
31
|
+
) -> tuple[Decimal, int]:
|
|
32
|
+
"""Validate transaction account/currency/date and return signed amount with days remaining."""
|
|
33
|
+
tx_currency = str(_get_attr(tx, "currency", default="UNKNOWN")).upper()
|
|
34
|
+
raw_account = _get_attr(tx, "account_id", default=None)
|
|
35
|
+
tx_account = str(raw_account) if raw_account is not None else None
|
|
36
|
+
if tx_currency != currency or tx_account != account_id:
|
|
37
|
+
raise ValueError("Daily balance requires one account and currency")
|
|
38
|
+
booked = _extract_date(_get_attr(tx, "booking_date", "date"))
|
|
39
|
+
if booked is None or not period_start <= booked <= period_end:
|
|
40
|
+
raise ValueError("Every booking date must fall within the period")
|
|
41
|
+
amount, credit = _amount_and_direction(tx)
|
|
42
|
+
signed = abs(amount) if credit else -abs(amount)
|
|
43
|
+
days_remaining = (period_end - booked).days + 1
|
|
44
|
+
return signed, days_remaining
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def compute_average_daily_balance(
|
|
48
|
+
transactions: Iterable[Any],
|
|
49
|
+
*,
|
|
50
|
+
opening_balance: Decimal,
|
|
51
|
+
period_start: date,
|
|
52
|
+
period_end: date,
|
|
53
|
+
currency: str,
|
|
54
|
+
account_id: str | None = None,
|
|
55
|
+
) -> DailyBalanceMetrics:
|
|
56
|
+
"""Average end-of-day balances, including days without transactions.
|
|
57
|
+
|
|
58
|
+
Opening balance is the balance immediately before the first day. Each
|
|
59
|
+
booking affects that day's closing balance through the inclusive end date.
|
|
60
|
+
The caller must supply the complete period and all its posted transactions.
|
|
61
|
+
Reject mixed accounts/currencies, missing dates and out-of-period rows;
|
|
62
|
+
never infer an opening balance from incomplete transaction history.
|
|
63
|
+
Runtime is linear in rows, without allocating one balance per day.
|
|
64
|
+
"""
|
|
65
|
+
if period_end < period_start:
|
|
66
|
+
raise ValueError("period_end must not precede period_start")
|
|
67
|
+
clean_currency = currency.strip().upper()
|
|
68
|
+
if not clean_currency or clean_currency == "UNKNOWN":
|
|
69
|
+
raise ValueError("An explicit currency is required")
|
|
70
|
+
opening = iso_decimal(str(opening_balance), context="opening balance")
|
|
71
|
+
days = (period_end - period_start).days + 1
|
|
72
|
+
weighted_balance = opening * days
|
|
73
|
+
closing = opening
|
|
74
|
+
for tx in transactions:
|
|
75
|
+
signed, days_remaining = _process_daily_balance_tx(
|
|
76
|
+
tx, clean_currency, account_id, period_start, period_end
|
|
77
|
+
)
|
|
78
|
+
closing += signed
|
|
79
|
+
weighted_balance += signed * days_remaining
|
|
80
|
+
return DailyBalanceMetrics(
|
|
81
|
+
account_id,
|
|
82
|
+
clean_currency,
|
|
83
|
+
period_start,
|
|
84
|
+
period_end,
|
|
85
|
+
opening,
|
|
86
|
+
closing,
|
|
87
|
+
weighted_balance / days,
|
|
88
|
+
days,
|
|
89
|
+
)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _validate_period(
|
|
93
|
+
period_start: date | None, period_end: date | None
|
|
94
|
+
) -> None:
|
|
95
|
+
"""Validate consistency of start and end period parameters."""
|
|
96
|
+
if (period_start is None) != (period_end is None):
|
|
97
|
+
raise ValueError("Supply both period_start and period_end")
|
|
98
|
+
if (
|
|
99
|
+
period_start is not None
|
|
100
|
+
and period_end is not None
|
|
101
|
+
and period_end < period_start
|
|
102
|
+
):
|
|
103
|
+
raise ValueError("period_end must not precede period_start")
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _calculate_run_rates(
|
|
107
|
+
dates: list[date],
|
|
108
|
+
tx_count: int,
|
|
109
|
+
total_outflow: Decimal,
|
|
110
|
+
net_cash: Decimal,
|
|
111
|
+
period_start: date | None,
|
|
112
|
+
period_end: date | None,
|
|
113
|
+
) -> tuple[Decimal | None, Decimal | None]:
|
|
114
|
+
"""Calculate monthly burn rate and annual run rate if all dates are present."""
|
|
115
|
+
if len(dates) != tx_count:
|
|
116
|
+
return None, None
|
|
117
|
+
first, last = min(dates), max(dates)
|
|
118
|
+
start = period_start or first.replace(day=1)
|
|
119
|
+
end = period_end or last.replace(day=monthrange(last.year, last.month)[1])
|
|
120
|
+
months = _calendar_months(start, end)
|
|
121
|
+
burn_rate = total_outflow / months
|
|
122
|
+
projected_run_rate = net_cash / months * 12
|
|
123
|
+
return burn_rate, projected_run_rate
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
class _CurrencyAccumulator:
|
|
127
|
+
"""Accumulates cash flow figures and metrics for a single currency."""
|
|
128
|
+
|
|
129
|
+
def __init__(
|
|
130
|
+
self,
|
|
131
|
+
curr: str,
|
|
132
|
+
period_start: date | None,
|
|
133
|
+
period_end: date | None,
|
|
134
|
+
) -> None:
|
|
135
|
+
"""Initialize currency accumulator state."""
|
|
136
|
+
self.curr = curr
|
|
137
|
+
self.period_start = period_start
|
|
138
|
+
self.period_end = period_end
|
|
139
|
+
self.total_inflow = Decimal("0.00")
|
|
140
|
+
self.total_outflow = Decimal("0.00")
|
|
141
|
+
self.credit_count = 0
|
|
142
|
+
self.debit_count = 0
|
|
143
|
+
self.dates: list[date] = []
|
|
144
|
+
self.monthly_inflows: dict[str, Decimal] = defaultdict(
|
|
145
|
+
lambda: Decimal("0.00")
|
|
146
|
+
)
|
|
147
|
+
self.monthly_outflows: dict[str, Decimal] = defaultdict(
|
|
148
|
+
lambda: Decimal("0.00")
|
|
149
|
+
)
|
|
150
|
+
|
|
151
|
+
def process_tx(self, tx: Any) -> None:
|
|
152
|
+
"""Process a single transaction into currency aggregates."""
|
|
153
|
+
amt, is_credit = _amount_and_direction(tx)
|
|
154
|
+
abs_amt = abs(amt)
|
|
155
|
+
d = _extract_date(
|
|
156
|
+
_get_attr(tx, "booking_date", "value_date", "date", default=None)
|
|
157
|
+
)
|
|
158
|
+
m_key = d.strftime("%Y-%m") if d else "UNKNOWN"
|
|
159
|
+
if (
|
|
160
|
+
self.period_start is not None
|
|
161
|
+
and self.period_end is not None
|
|
162
|
+
and (d is None or not self.period_start <= d <= self.period_end)
|
|
163
|
+
):
|
|
164
|
+
raise ValueError("Every booking date must fall within the period")
|
|
165
|
+
if d is not None:
|
|
166
|
+
self.dates.append(d)
|
|
167
|
+
|
|
168
|
+
if is_credit:
|
|
169
|
+
self.total_inflow += abs_amt
|
|
170
|
+
self.credit_count += 1
|
|
171
|
+
self.monthly_inflows[m_key] += abs_amt
|
|
172
|
+
else:
|
|
173
|
+
self.total_outflow += abs_amt
|
|
174
|
+
self.debit_count += 1
|
|
175
|
+
self.monthly_outflows[m_key] += abs_amt
|
|
176
|
+
|
|
177
|
+
def build_metrics(self, tx_count: int) -> CashFlowMetrics:
|
|
178
|
+
"""Build finalized CashFlowMetrics from accumulated totals."""
|
|
179
|
+
net_cash = self.total_inflow - self.total_outflow
|
|
180
|
+
avg_in = (
|
|
181
|
+
self.total_inflow / Decimal(self.credit_count)
|
|
182
|
+
if self.credit_count > 0
|
|
183
|
+
else Decimal("0.00")
|
|
184
|
+
)
|
|
185
|
+
avg_out = (
|
|
186
|
+
self.total_outflow / Decimal(self.debit_count)
|
|
187
|
+
if self.debit_count > 0
|
|
188
|
+
else Decimal("0.00")
|
|
189
|
+
)
|
|
190
|
+
avg_amt = (
|
|
191
|
+
(self.total_inflow + self.total_outflow) / Decimal(tx_count)
|
|
192
|
+
if tx_count > 0
|
|
193
|
+
else Decimal("0.00")
|
|
194
|
+
)
|
|
195
|
+
|
|
196
|
+
burn_rate, projected_run_rate = _calculate_run_rates(
|
|
197
|
+
self.dates,
|
|
198
|
+
tx_count,
|
|
199
|
+
self.total_outflow,
|
|
200
|
+
net_cash,
|
|
201
|
+
self.period_start,
|
|
202
|
+
self.period_end,
|
|
203
|
+
)
|
|
204
|
+
|
|
205
|
+
return CashFlowMetrics(
|
|
206
|
+
currency=self.curr,
|
|
207
|
+
total_inflow=self.total_inflow,
|
|
208
|
+
total_outflow=self.total_outflow,
|
|
209
|
+
net_cash_flow=net_cash,
|
|
210
|
+
transaction_count=tx_count,
|
|
211
|
+
credit_count=self.credit_count,
|
|
212
|
+
debit_count=self.debit_count,
|
|
213
|
+
average_inflow=avg_in,
|
|
214
|
+
average_outflow=avg_out,
|
|
215
|
+
average_transaction_amount=avg_amt,
|
|
216
|
+
monthly_inflows={
|
|
217
|
+
k: str(v) for k, v in self.monthly_inflows.items()
|
|
218
|
+
},
|
|
219
|
+
monthly_outflows={
|
|
220
|
+
k: str(v) for k, v in self.monthly_outflows.items()
|
|
221
|
+
},
|
|
222
|
+
burn_rate_monthly=burn_rate,
|
|
223
|
+
projected_annual_run_rate=projected_run_rate,
|
|
224
|
+
)
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def compute_cash_flow_summary(
|
|
228
|
+
transactions: Iterable[Any],
|
|
229
|
+
*,
|
|
230
|
+
period_start: date | None = None,
|
|
231
|
+
period_end: date | None = None,
|
|
232
|
+
) -> dict[str, CashFlowMetrics]:
|
|
233
|
+
"""Calculate cash flow spreads, volume, and run rates grouped by currency."""
|
|
234
|
+
_validate_period(period_start, period_end)
|
|
235
|
+
groups: dict[str, list[Any]] = defaultdict(list)
|
|
236
|
+
for tx in transactions:
|
|
237
|
+
curr = _get_attr(tx, "currency", "curr", default="UNKNOWN")
|
|
238
|
+
groups[str(curr).upper()].append(tx)
|
|
239
|
+
|
|
240
|
+
results: dict[str, CashFlowMetrics] = {}
|
|
241
|
+
for curr, txs in groups.items():
|
|
242
|
+
accumulator = _CurrencyAccumulator(curr, period_start, period_end)
|
|
243
|
+
for tx in txs:
|
|
244
|
+
accumulator.process_tx(tx)
|
|
245
|
+
results[curr] = accumulator.build_metrics(len(txs))
|
|
246
|
+
|
|
247
|
+
return results
|