bankstatementparser 0.0.24__tar.gz → 0.0.26__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.24 → bankstatementparser-0.0.26}/PKG-INFO +6 -5
  2. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/README.md +5 -4
  3. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/__init__.py +21 -1
  4. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/additional_parsers.py +13 -1
  5. bankstatementparser-0.0.26/bankstatementparser/analytics/__init__.py +50 -0
  6. bankstatementparser-0.0.26/bankstatementparser/analytics/cash_flow.py +247 -0
  7. bankstatementparser-0.0.26/bankstatementparser/analytics/common.py +104 -0
  8. bankstatementparser-0.0.26/bankstatementparser/analytics/models.py +155 -0
  9. bankstatementparser-0.0.26/bankstatementparser/analytics/patterns.py +291 -0
  10. bankstatementparser-0.0.26/bankstatementparser/api.py +275 -0
  11. bankstatementparser-0.0.26/bankstatementparser/api_limits.py +226 -0
  12. bankstatementparser-0.0.26/bankstatementparser/api_worker.py +227 -0
  13. bankstatementparser-0.0.26/bankstatementparser/camt_reports.py +429 -0
  14. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/input_validator.py +2 -0
  15. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/parsers/__init__.py +2 -0
  16. bankstatementparser-0.0.26/bankstatementparser/parsers/bai2.py +293 -0
  17. bankstatementparser-0.0.26/bankstatementparser/telemetry.py +177 -0
  18. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/pyproject.toml +2 -2
  19. bankstatementparser-0.0.24/bankstatementparser/analytics.py +0 -691
  20. bankstatementparser-0.0.24/bankstatementparser/api.py +0 -583
  21. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/LICENSE +0 -0
  22. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/LICENSE-APACHE +0 -0
  23. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/LICENSE-MIT +0 -0
  24. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/_amounts.py +0 -0
  25. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/_llm_common.py +0 -0
  26. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/bank_statement_parsers.py +0 -0
  27. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/base_parser.py +0 -0
  28. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/camt_parser.py +0 -0
  29. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/cli.py +0 -0
  30. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/enrichment/__init__.py +0 -0
  31. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/enrichment/account_mapper.py +0 -0
  32. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/enrichment/categorizer.py +0 -0
  33. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/exceptions.py +0 -0
  34. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/export/__init__.py +0 -0
  35. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/export/ledger.py +0 -0
  36. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/export/parquet.py +0 -0
  37. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/field86_parser.py +0 -0
  38. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/forensics.py +0 -0
  39. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/__init__.py +0 -0
  40. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/evaluation.py +0 -0
  41. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/llm_extractor.py +0 -0
  42. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/ollama_direct.py +0 -0
  43. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/orchestrator.py +0 -0
  44. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/pdf_text.py +0 -0
  45. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/prompts.py +0 -0
  46. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/scanner.py +0 -0
  47. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/verification.py +0 -0
  48. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/vision.py +0 -0
  49. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/pain001_parser.py +0 -0
  50. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/parallel.py +0 -0
  51. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/parsers/common.py +0 -0
  52. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/parsers/csv_parser.py +0 -0
  53. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/parsers/mt940.py +0 -0
  54. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/parsers/ofx.py +0 -0
  55. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/plugins.py +0 -0
  56. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/privacy.py +0 -0
  57. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/py.typed +0 -0
  58. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/reconciliation.py +0 -0
  59. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/record_types.py +0 -0
  60. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/transaction_deduplicator.py +0 -0
  61. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/transaction_models.py +0 -0
  62. {bankstatementparser-0.0.24 → bankstatementparser-0.0.26}/bankstatementparser/zip_security.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: bankstatementparser
3
- Version: 0.0.24
3
+ Version: 0.0.26
4
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
@@ -64,7 +64,7 @@ Description-Content-Type: text/markdown
64
64
 
65
65
  <p align="center">
66
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>
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.24" 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.26" alt="PyPI" /></a>
68
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>
69
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>
70
70
  <a href="LICENSE"><img src="https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="License" /></a>
@@ -390,7 +390,7 @@ for the full surface.
390
390
  |---|---|
391
391
  | **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
392
392
  | **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
393
- | **Tested** | 1014 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
393
+ | **Tested** | 1045 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
394
394
 
395
395
  ---
396
396
 
@@ -750,7 +750,8 @@ cleanly — see each companion's README for runnable examples.
750
750
  ## Project Layout
751
751
 
752
752
  ```text
753
- bankstatementparser/ Source code (44 modules)
753
+ bankstatementparser/ Source code (53 modules)
754
+ bankstatementparser/analytics/ Financial metrics, cash flow, cadence & anomaly detection
754
755
  bankstatementparser/parsers/ Modular statement parsers (CSV, MT940, OFX/QFX)
755
756
  bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
756
757
  bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
@@ -759,7 +760,7 @@ bankstatementparser/api.py REST API microservice (FastAPI)
759
760
  docs/compliance/ ISO 13485 validation, risk register, traceability matrix
760
761
  examples/ 14 deterministic + 9 hybrid runnable example scripts
761
762
  scripts/ SBOM generation, checksums, signature verification
762
- tests/ 1014 tests (unit, integration, property-based, security, hybrid mocks)
763
+ tests/ 1045 tests (unit, integration, property-based, security, hybrid mocks)
763
764
  ```
764
765
 
765
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.24" 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.26" 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** | 1045 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
349
349
 
350
350
  ---
351
351
 
@@ -705,7 +705,8 @@ cleanly — see each companion's README for runnable examples.
705
705
  ## Project Layout
706
706
 
707
707
  ```text
708
- bankstatementparser/ Source code (44 modules)
708
+ bankstatementparser/ Source code (53 modules)
709
+ bankstatementparser/analytics/ Financial metrics, cash flow, cadence & anomaly detection
709
710
  bankstatementparser/parsers/ Modular statement parsers (CSV, MT940, OFX/QFX)
710
711
  bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
711
712
  bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
@@ -714,7 +715,7 @@ bankstatementparser/api.py REST API microservice (FastAPI)
714
715
  docs/compliance/ ISO 13485 validation, risk register, traceability matrix
715
716
  examples/ 14 deterministic + 9 hybrid runnable example scripts
716
717
  scripts/ SBOM generation, checksums, signature verification
717
- tests/ 1014 tests (unit, integration, property-based, security, hybrid mocks)
718
+ tests/ 1045 tests (unit, integration, property-based, security, hybrid mocks)
718
719
  ```
719
720
 
720
721
  ---
@@ -20,6 +20,9 @@ operations.
20
20
  """
21
21
 
22
22
  from .additional_parsers import (
23
+ Bai2Parser,
24
+ Camt052Parser,
25
+ Camt054Parser,
23
26
  CsvStatementParser,
24
27
  Mt940Parser,
25
28
  OfxParser,
@@ -71,6 +74,14 @@ from .reconciliation import (
71
74
  ReconciliationStatus,
72
75
  reconcile_payments_and_statements,
73
76
  )
77
+ from .telemetry import (
78
+ NullSpan,
79
+ is_telemetry_available,
80
+ trace_async_stream,
81
+ trace_span,
82
+ trace_stream,
83
+ traced,
84
+ )
74
85
  from .transaction_deduplicator import (
75
86
  DeduplicationResult,
76
87
  Deduplicator,
@@ -91,14 +102,17 @@ from .zip_security import (
91
102
  #: so the conformance gate can compare it statically against
92
103
  #: pyproject.toml -- that comparison is the thing that catches drift, and
93
104
  #: a runtime lookup would make the two trivially equal and check nothing.
94
- __version__ = "0.0.24"
105
+ __version__ = "0.0.26"
95
106
 
96
107
  __all__ = [
97
108
  "AnalyticsReport",
98
109
  "AnomalyFinding",
110
+ "Bai2Parser",
99
111
  "BankStatementParser",
100
112
  "BankStatementParserError",
101
113
  "BoundingBox",
114
+ "Camt052Parser",
115
+ "Camt054Parser",
102
116
  "CamtParser",
103
117
  "CashFlowMetrics",
104
118
  "CsvStatementParser",
@@ -115,6 +129,7 @@ __all__ = [
115
129
  "InputValidator",
116
130
  "MatchGroup",
117
131
  "Mt940Parser",
132
+ "NullSpan",
118
133
  "OfxParser",
119
134
  "Pain001ParseError",
120
135
  "Pain001Parser",
@@ -143,6 +158,7 @@ __all__ = [
143
158
  "export_parquet",
144
159
  "export_parquet_stream",
145
160
  "inspect_pdf_forensics",
161
+ "is_telemetry_available",
146
162
  "iter_files_parallel",
147
163
  "iter_secure_statement_entries",
148
164
  "iter_secure_xml_entries",
@@ -151,4 +167,8 @@ __all__ = [
151
167
  "reconcile_payments_and_statements",
152
168
  "register_loader",
153
169
  "register_writer",
170
+ "trace_async_stream",
171
+ "trace_span",
172
+ "trace_stream",
173
+ "traced",
154
174
  ]
@@ -21,10 +21,12 @@ from pathlib import Path
21
21
 
22
22
  from .base_parser import BankStatementParser
23
23
  from .camt_parser import CamtParser
24
+ from .camt_reports import Camt052Parser, Camt054Parser
24
25
  from .input_validator import ValidationError
25
26
  from .pain001_parser import Pain001Parser
26
27
  from .parsers import (
27
28
  CSV_COLUMN_GROUPS,
29
+ Bai2Parser,
28
30
  CsvStatementParser,
29
31
  Mt940Parser,
30
32
  OfxParser,
@@ -42,6 +44,9 @@ from .plugins import get_registered_loaders
42
44
 
43
45
  __all__ = [
44
46
  "CSV_COLUMN_GROUPS",
47
+ "Bai2Parser",
48
+ "Camt052Parser",
49
+ "Camt054Parser",
45
50
  "CsvStatementParser",
46
51
  "Mt940Parser",
47
52
  "OfxParser",
@@ -67,7 +72,7 @@ def _detect_by_suffix(suffix: str) -> str | None:
67
72
  return "ofx"
68
73
  if suffix in {".mt940", ".sta"}:
69
74
  return "mt940"
70
- if suffix == ".bai2":
75
+ if suffix in {".bai2", ".bai"}:
71
76
  return "bai2"
72
77
  if suffix == ".mt942":
73
78
  return "mt942"
@@ -78,6 +83,10 @@ def _detect_xml_format(lowered: str) -> str | None:
78
83
  """Detect statement format from XML content tags."""
79
84
  if "cstmrcdttrfinitn" in lowered or "pain.001" in lowered:
80
85
  return "pain001"
86
+ if "bktocstmrdbtcdtntfctn" in lowered or "camt.054" in lowered:
87
+ return "camt054"
88
+ if "bktocstmracctrpt" in lowered or "camt.052" in lowered:
89
+ return "camt052"
81
90
  if "bktocstmrstmt" in lowered or "camt." in lowered:
82
91
  return "camt"
83
92
  return None
@@ -135,11 +144,14 @@ def create_parser(
135
144
  selected = (format_name or detect_statement_format(file_name)).lower()
136
145
  parser_map: dict[str, type[BankStatementParser]] = {
137
146
  "camt": CamtParser,
147
+ "camt052": Camt052Parser,
148
+ "camt054": Camt054Parser,
138
149
  "pain001": Pain001Parser,
139
150
  "csv": CsvStatementParser,
140
151
  "ofx": OfxParser,
141
152
  "qfx": QfxParser,
142
153
  "mt940": Mt940Parser,
154
+ "bai2": Bai2Parser,
143
155
  }
144
156
  # Augment with dynamic plugins
145
157
  parser_map.update(get_registered_loaders())
@@ -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
@@ -0,0 +1,104 @@
1
+ # SPDX-License-Identifier: Apache-2.0 OR MIT
2
+ # Copyright (C) 2023-2026 Bank Statement Parser. All rights reserved.
3
+
4
+ """Common extraction and attribute resolution utilities for analytics."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from calendar import monthrange
9
+ from datetime import date, datetime
10
+ from decimal import Decimal
11
+ from typing import Any
12
+
13
+ from .._amounts import iso_decimal
14
+
15
+ _ALIASES: dict[str, tuple[str, ...]] = {
16
+ "amount": ("Amount", "InstdAmt"),
17
+ "currency": ("Currency",),
18
+ "booking_date": ("BookgDt",),
19
+ "value_date": ("ValDt",),
20
+ "description": ("Description", "Reference", "RmtInf"),
21
+ "credit_debit": ("DrCr",),
22
+ "account_id": ("AccountId", "DbtrIBAN"),
23
+ }
24
+
25
+ _CREDIT_DIRECTIONS = frozenset(("CRDT", "CREDIT", "C", "CR"))
26
+ _DEBIT_DIRECTIONS = frozenset(("DBIT", "DEBIT", "D", "DR"))
27
+
28
+
29
+ def _extract_date(val: Any) -> date | None:
30
+ """Parse arbitrary date object or string into a datetime.date."""
31
+ if isinstance(val, date) and not isinstance(val, datetime):
32
+ return val
33
+ if isinstance(val, datetime):
34
+ return val.date()
35
+ if isinstance(val, str):
36
+ val_clean = val.strip()[:10]
37
+ for fmt in ("%Y-%m-%d", "%d/%m/%Y", "%Y%m%d", "%d-%m-%Y"):
38
+ try:
39
+ return datetime.strptime(val_clean, fmt).date()
40
+ except ValueError:
41
+ continue
42
+ return None
43
+
44
+
45
+ def _extract_amount(val: Any) -> Decimal:
46
+ """Convert amount attribute to Decimal."""
47
+ return iso_decimal(
48
+ str(val).strip().replace(",", ".").replace(" ", ""),
49
+ context="analytics amount",
50
+ )
51
+
52
+
53
+ def _get_dict_value(obj: dict[str, Any], key: str) -> Any:
54
+ """Retrieve non-empty value from a dictionary by key."""
55
+ if key in obj and obj[key] not in (None, ""):
56
+ return obj[key]
57
+ return None
58
+
59
+
60
+ def _get_attr(obj: Any, *keys: str, default: Any = None) -> Any:
61
+ """Retrieve attribute or dict key across Transaction or dict instances."""
62
+ expanded = [
63
+ alias for key in keys for alias in (key, *_ALIASES.get(key, ()))
64
+ ]
65
+ for key in expanded:
66
+ if isinstance(obj, dict):
67
+ val = _get_dict_value(obj, key)
68
+ if val is not None:
69
+ return val
70
+ elif hasattr(obj, key):
71
+ val = getattr(obj, key)
72
+ if val is not None:
73
+ return val
74
+ return default
75
+
76
+
77
+ def _amount_and_direction(tx: Any) -> tuple[Decimal, bool]:
78
+ """Resolve explicit bank direction before falling back to amount sign."""
79
+ amount = _extract_amount(_get_attr(tx, "amount", "amt", default=None))
80
+ direction = str(
81
+ _get_attr(tx, "credit_debit", "drcr", "type", default="")
82
+ ).upper()
83
+ if direction in _CREDIT_DIRECTIONS:
84
+ return amount, True
85
+ if direction in _DEBIT_DIRECTIONS:
86
+ return amount, False
87
+ return amount, amount >= 0
88
+
89
+
90
+ def _calendar_months(start: date, end: date) -> Decimal:
91
+ """Measure an inclusive period in calendar months, prorating edge months."""
92
+ cursor = start
93
+ months = Decimal(0)
94
+ while True:
95
+ last = date(
96
+ cursor.year, cursor.month, monthrange(cursor.year, cursor.month)[1]
97
+ )
98
+ stop = min(last, end)
99
+ months += Decimal((stop - cursor).days + 1) / last.day
100
+ if stop == end:
101
+ return months
102
+ cursor = date(
103
+ cursor.year + (cursor.month == 12), cursor.month % 12 + 1, 1
104
+ )