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.
Files changed (62) hide show
  1. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/PKG-INFO +9 -6
  2. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/README.md +6 -4
  3. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/__init__.py +15 -1
  4. bankstatementparser-0.0.25/bankstatementparser/additional_parsers.py +150 -0
  5. bankstatementparser-0.0.25/bankstatementparser/analytics/__init__.py +50 -0
  6. bankstatementparser-0.0.25/bankstatementparser/analytics/cash_flow.py +247 -0
  7. bankstatementparser-0.0.25/bankstatementparser/analytics/common.py +104 -0
  8. bankstatementparser-0.0.25/bankstatementparser/analytics/models.py +155 -0
  9. bankstatementparser-0.0.25/bankstatementparser/analytics/patterns.py +291 -0
  10. bankstatementparser-0.0.25/bankstatementparser/api.py +263 -0
  11. bankstatementparser-0.0.25/bankstatementparser/api_limits.py +226 -0
  12. bankstatementparser-0.0.25/bankstatementparser/api_worker.py +150 -0
  13. bankstatementparser-0.0.25/bankstatementparser/field86_parser.py +204 -0
  14. bankstatementparser-0.0.25/bankstatementparser/parsers/__init__.py +49 -0
  15. bankstatementparser-0.0.25/bankstatementparser/parsers/common.py +233 -0
  16. bankstatementparser-0.0.25/bankstatementparser/parsers/csv_parser.py +141 -0
  17. bankstatementparser-0.0.25/bankstatementparser/parsers/mt940.py +268 -0
  18. bankstatementparser-0.0.25/bankstatementparser/parsers/ofx.py +115 -0
  19. bankstatementparser-0.0.25/bankstatementparser/telemetry.py +177 -0
  20. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/pyproject.toml +25 -3
  21. bankstatementparser-0.0.23/bankstatementparser/additional_parsers.py +0 -632
  22. bankstatementparser-0.0.23/bankstatementparser/analytics.py +0 -691
  23. bankstatementparser-0.0.23/bankstatementparser/api.py +0 -583
  24. bankstatementparser-0.0.23/bankstatementparser/field86_parser.py +0 -186
  25. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/LICENSE +0 -0
  26. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/LICENSE-APACHE +0 -0
  27. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/LICENSE-MIT +0 -0
  28. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/_amounts.py +0 -0
  29. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/_llm_common.py +0 -0
  30. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/bank_statement_parsers.py +0 -0
  31. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/base_parser.py +0 -0
  32. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/camt_parser.py +0 -0
  33. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/cli.py +0 -0
  34. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/__init__.py +0 -0
  35. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/account_mapper.py +0 -0
  36. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/enrichment/categorizer.py +0 -0
  37. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/exceptions.py +0 -0
  38. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/export/__init__.py +0 -0
  39. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/export/ledger.py +0 -0
  40. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/export/parquet.py +0 -0
  41. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/forensics.py +0 -0
  42. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/__init__.py +0 -0
  43. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/evaluation.py +0 -0
  44. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/llm_extractor.py +0 -0
  45. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/ollama_direct.py +0 -0
  46. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/orchestrator.py +0 -0
  47. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/pdf_text.py +0 -0
  48. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/prompts.py +0 -0
  49. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/scanner.py +0 -0
  50. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/verification.py +0 -0
  51. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/hybrid/vision.py +0 -0
  52. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/input_validator.py +0 -0
  53. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/pain001_parser.py +0 -0
  54. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/parallel.py +0 -0
  55. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/plugins.py +0 -0
  56. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/privacy.py +0 -0
  57. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/py.typed +0 -0
  58. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/reconciliation.py +0 -0
  59. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/record_types.py +0 -0
  60. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/transaction_deduplicator.py +0 -0
  61. {bankstatementparser-0.0.23 → bankstatementparser-0.0.25}/bankstatementparser/transaction_models.py +0 -0
  62. {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.23
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.
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.23" alt="PyPI" /></a>
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** | 1014 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
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 (39 modules)
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/ 1014 tests (unit, integration, property-based, security, hybrid mocks)
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.23" alt="PyPI" /></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.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** | 1014 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
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 (39 modules)
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/ 1014 tests (unit, integration, property-based, security, hybrid mocks)
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.23"
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