bankstatementparser 0.0.25__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 (60) hide show
  1. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/PKG-INFO +5 -5
  2. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/README.md +4 -4
  3. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/__init__.py +7 -1
  4. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/additional_parsers.py +13 -1
  5. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/api.py +14 -2
  6. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/api_worker.py +77 -0
  7. bankstatementparser-0.0.26/bankstatementparser/camt_reports.py +429 -0
  8. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/input_validator.py +2 -0
  9. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/parsers/__init__.py +2 -0
  10. bankstatementparser-0.0.26/bankstatementparser/parsers/bai2.py +293 -0
  11. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/pyproject.toml +1 -1
  12. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/LICENSE +0 -0
  13. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/LICENSE-APACHE +0 -0
  14. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/LICENSE-MIT +0 -0
  15. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/_amounts.py +0 -0
  16. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/_llm_common.py +0 -0
  17. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/analytics/__init__.py +0 -0
  18. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/analytics/cash_flow.py +0 -0
  19. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/analytics/common.py +0 -0
  20. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/analytics/models.py +0 -0
  21. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/analytics/patterns.py +0 -0
  22. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/api_limits.py +0 -0
  23. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/bank_statement_parsers.py +0 -0
  24. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/base_parser.py +0 -0
  25. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/camt_parser.py +0 -0
  26. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/cli.py +0 -0
  27. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/enrichment/__init__.py +0 -0
  28. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/enrichment/account_mapper.py +0 -0
  29. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/enrichment/categorizer.py +0 -0
  30. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/exceptions.py +0 -0
  31. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/export/__init__.py +0 -0
  32. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/export/ledger.py +0 -0
  33. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/export/parquet.py +0 -0
  34. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/field86_parser.py +0 -0
  35. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/forensics.py +0 -0
  36. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/__init__.py +0 -0
  37. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/evaluation.py +0 -0
  38. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/llm_extractor.py +0 -0
  39. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/ollama_direct.py +0 -0
  40. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/orchestrator.py +0 -0
  41. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/pdf_text.py +0 -0
  42. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/prompts.py +0 -0
  43. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/scanner.py +0 -0
  44. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/verification.py +0 -0
  45. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/hybrid/vision.py +0 -0
  46. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/pain001_parser.py +0 -0
  47. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/parallel.py +0 -0
  48. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/parsers/common.py +0 -0
  49. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/parsers/csv_parser.py +0 -0
  50. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/parsers/mt940.py +0 -0
  51. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/parsers/ofx.py +0 -0
  52. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/plugins.py +0 -0
  53. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/privacy.py +0 -0
  54. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/py.typed +0 -0
  55. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/reconciliation.py +0 -0
  56. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/record_types.py +0 -0
  57. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/telemetry.py +0 -0
  58. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/transaction_deduplicator.py +0 -0
  59. {bankstatementparser-0.0.25 → bankstatementparser-0.0.26}/bankstatementparser/transaction_models.py +0 -0
  60. {bankstatementparser-0.0.25 → 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.25
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.25" 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** | 1023 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,7 @@ cleanly — see each companion's README for runnable examples.
750
750
  ## Project Layout
751
751
 
752
752
  ```text
753
- bankstatementparser/ Source code (51 modules)
753
+ bankstatementparser/ Source code (53 modules)
754
754
  bankstatementparser/analytics/ Financial metrics, cash flow, cadence & anomaly detection
755
755
  bankstatementparser/parsers/ Modular statement parsers (CSV, MT940, OFX/QFX)
756
756
  bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
@@ -760,7 +760,7 @@ bankstatementparser/api.py REST API microservice (FastAPI)
760
760
  docs/compliance/ ISO 13485 validation, risk register, traceability matrix
761
761
  examples/ 14 deterministic + 9 hybrid runnable example scripts
762
762
  scripts/ SBOM generation, checksums, signature verification
763
- tests/ 1023 tests (unit, integration, property-based, security, hybrid mocks)
763
+ tests/ 1045 tests (unit, integration, property-based, security, hybrid mocks)
764
764
  ```
765
765
 
766
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.25" 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** | 1023 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,7 @@ cleanly — see each companion's README for runnable examples.
705
705
  ## Project Layout
706
706
 
707
707
  ```text
708
- bankstatementparser/ Source code (51 modules)
708
+ bankstatementparser/ Source code (53 modules)
709
709
  bankstatementparser/analytics/ Financial metrics, cash flow, cadence & anomaly detection
710
710
  bankstatementparser/parsers/ Modular statement parsers (CSV, MT940, OFX/QFX)
711
711
  bankstatementparser/hybrid/ PDF pipeline: orchestrator, llm_extractor, vision, scanner, ollama_direct, verification
@@ -715,7 +715,7 @@ bankstatementparser/api.py REST API microservice (FastAPI)
715
715
  docs/compliance/ ISO 13485 validation, risk register, traceability matrix
716
716
  examples/ 14 deterministic + 9 hybrid runnable example scripts
717
717
  scripts/ SBOM generation, checksums, signature verification
718
- tests/ 1023 tests (unit, integration, property-based, security, hybrid mocks)
718
+ tests/ 1045 tests (unit, integration, property-based, security, hybrid mocks)
719
719
  ```
720
720
 
721
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,
@@ -99,14 +102,17 @@ from .zip_security import (
99
102
  #: so the conformance gate can compare it statically against
100
103
  #: pyproject.toml -- that comparison is the thing that catches drift, and
101
104
  #: a runtime lookup would make the two trivially equal and check nothing.
102
- __version__ = "0.0.25"
105
+ __version__ = "0.0.26"
103
106
 
104
107
  __all__ = [
105
108
  "AnalyticsReport",
106
109
  "AnomalyFinding",
110
+ "Bai2Parser",
107
111
  "BankStatementParser",
108
112
  "BankStatementParserError",
109
113
  "BoundingBox",
114
+ "Camt052Parser",
115
+ "Camt054Parser",
110
116
  "CamtParser",
111
117
  "CashFlowMetrics",
112
118
  "CsvStatementParser",
@@ -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())
@@ -53,11 +53,13 @@ from .api_limits import (
53
53
  _safe_basename,
54
54
  )
55
55
  from .api_worker import (
56
+ PersistentWorkerPool,
56
57
  _ingest_in_process,
57
58
  _ingest_in_thread,
58
59
  _reap_worker,
59
60
  _result_to_dict,
60
61
  _run_ingest_worker,
62
+ _run_worker_job,
61
63
  _verification_dict,
62
64
  )
63
65
  from .input_validator import InputValidator
@@ -70,6 +72,7 @@ __all__ = [
70
72
  "ENV_MAX_UPLOAD_BYTES",
71
73
  "_UPLOAD_CHUNK_BYTES",
72
74
  "APIError",
75
+ "PersistentWorkerPool",
73
76
  "_IngestLimits",
74
77
  "_allowed_suffix",
75
78
  "_ingest_in_process",
@@ -78,6 +81,7 @@ __all__ = [
78
81
  "_resolve_max_upload_bytes",
79
82
  "_result_to_dict",
80
83
  "_run_ingest_worker",
84
+ "_run_worker_job",
81
85
  "_safe_basename",
82
86
  "_verification_dict",
83
87
  "create_app",
@@ -101,6 +105,7 @@ def _build_ingest_handler(
101
105
  app: Any,
102
106
  max_upload: int,
103
107
  ingest_timeout: float | None,
108
+ worker_pool: Optional[PersistentWorkerPool] = None,
104
109
  ) -> Any:
105
110
  """Register the POST /ingest endpoint on the FastAPI application."""
106
111
  from fastapi import File, UploadFile
@@ -151,7 +156,11 @@ def _build_ingest_handler(
151
156
  },
152
157
  status_code=413,
153
158
  )
154
- if ingest_timeout is None:
159
+ if worker_pool is not None and ingest_timeout is not None:
160
+ payload = await worker_pool.run_ingest(
161
+ tmp_path, ingest_timeout
162
+ )
163
+ elif ingest_timeout is None:
155
164
  result = await _ingest_in_thread(smart_ingest, tmp_path)
156
165
  payload = _result_to_dict(result)
157
166
  else:
@@ -187,6 +196,7 @@ def create_app(
187
196
  max_concurrent_ingests: int = 4,
188
197
  upload_timeout: float = 60.0,
189
198
  ingest_timeout: float | None = 120.0,
199
+ worker_pool: Optional[PersistentWorkerPool] = None,
190
200
  ) -> Any:
191
201
  """Create a FastAPI application wrapping :func:`smart_ingest`."""
192
202
  try:
@@ -226,7 +236,9 @@ def create_app(
226
236
  upload_timeout=upload_timeout,
227
237
  )
228
238
 
229
- _build_ingest_handler(app, upload_cap, ingest_timeout)
239
+ _build_ingest_handler(
240
+ app, upload_cap, ingest_timeout, worker_pool=worker_pool
241
+ )
230
242
 
231
243
  @app.get("/health") # type: ignore[untyped-decorator]
232
244
  async def health() -> dict[str, str]:
@@ -21,12 +21,24 @@ import asyncio
21
21
  import json
22
22
  import sys
23
23
  import tempfile
24
+ from concurrent.futures import ProcessPoolExecutor
24
25
  from contextlib import suppress
25
26
  from pathlib import Path
26
27
  from typing import Any, Optional, cast
27
28
 
28
29
  from .api_limits import APIError
29
30
 
31
+ __all__ = [
32
+ "PersistentWorkerPool",
33
+ "_ingest_in_process",
34
+ "_ingest_in_thread",
35
+ "_reap_worker",
36
+ "_result_to_dict",
37
+ "_run_ingest_worker",
38
+ "_run_worker_job",
39
+ "_verification_dict",
40
+ ]
41
+
30
42
 
31
43
  def _verification_dict(v: Any) -> Optional[dict[str, Any]]:
32
44
  """Serialize a verification result to a JSON-safe dict, or None."""
@@ -76,6 +88,17 @@ def _run_ingest_worker(input_path: str, output_path: str) -> None:
76
88
  json.dump(payload, output)
77
89
 
78
90
 
91
+ def _run_worker_job(input_path: str) -> dict[str, Any]:
92
+ """Execute ingestion in a warm process worker and serialize to dict."""
93
+ from .hybrid import smart_ingest
94
+ from .telemetry import trace_span
95
+
96
+ with trace_span(
97
+ "bankstatementparser.api.worker_pool", {"input_path": input_path}
98
+ ):
99
+ return _result_to_dict(smart_ingest(input_path))
100
+
101
+
79
102
  async def _reap_worker(process: asyncio.subprocess.Process) -> None:
80
103
  """Wait for process exit even if cleanup receives repeated cancellation."""
81
104
  waiter = asyncio.create_task(process.wait())
@@ -148,3 +171,57 @@ async def _ingest_in_process(path: str, timeout: float) -> dict[str, Any]:
148
171
  with suppress(ProcessLookupError):
149
172
  process.kill()
150
173
  await _reap_worker(process)
174
+
175
+
176
+ class PersistentWorkerPool:
177
+ """Persistent warm process pool with memory recycling and execution deadlines."""
178
+
179
+ def __init__(
180
+ self,
181
+ max_workers: int = 4,
182
+ max_tasks_per_child: int = 50,
183
+ ) -> None:
184
+ """Initialize worker pool with concurrency and memory recycling bounds."""
185
+ self._max_workers = max_workers
186
+ self._max_tasks_per_child = max_tasks_per_child
187
+ self._executor: ProcessPoolExecutor | None = None
188
+
189
+ @property
190
+ def is_running(self) -> bool:
191
+ """Check whether the process pool is currently initialized and active."""
192
+ return self._executor is not None
193
+
194
+ def start(self) -> None:
195
+ """Initialize the persistent worker pool if not already running."""
196
+ if self._executor is None:
197
+ kwargs: dict[str, Any] = {}
198
+ if (
199
+ sys.version_info >= (3, 11) and self._max_tasks_per_child
200
+ ): # pragma: no cover - version dependent
201
+ kwargs["max_tasks_per_child"] = self._max_tasks_per_child
202
+ self._executor = ProcessPoolExecutor(
203
+ max_workers=self._max_workers,
204
+ **kwargs,
205
+ )
206
+
207
+ def shutdown(self, wait: bool = True) -> None:
208
+ """Shut down the pool and release worker processes."""
209
+ if self._executor is not None:
210
+ self._executor.shutdown(wait=wait, cancel_futures=True)
211
+ self._executor = None
212
+
213
+ async def run_ingest(self, path: str, timeout: float) -> dict[str, Any]:
214
+ """Execute statement ingestion in a warm worker under an execution deadline."""
215
+ if self._executor is None:
216
+ self.start()
217
+ executor = self._executor
218
+ if executor is None:
219
+ raise APIError("Worker pool failed to initialize")
220
+ loop = asyncio.get_running_loop()
221
+ future = loop.run_in_executor(executor, _run_worker_job, path)
222
+ try:
223
+ return await asyncio.wait_for(future, timeout=timeout)
224
+ except asyncio.TimeoutError:
225
+ raise
226
+ except Exception as exc:
227
+ raise APIError(f"Worker ingestion failed: {exc}") from exc
@@ -0,0 +1,429 @@
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
+ """CAMT.052 and CAMT.054 ISO 20022 streaming report and notification parsers."""
17
+
18
+ from __future__ import annotations
19
+
20
+ import logging
21
+ from collections.abc import Iterator
22
+ from datetime import date
23
+ from decimal import Decimal
24
+ from io import BytesIO
25
+ from pathlib import Path
26
+ from typing import ClassVar, cast
27
+
28
+ import pandas as pd
29
+ from lxml import etree
30
+
31
+ from ._amounts import iso_decimal
32
+ from .base_parser import BankStatementParser, _single_summary
33
+ from .exceptions import ParserError
34
+ from .input_validator import InputValidator
35
+ from .privacy import redact_record
36
+ from .record_types import SummaryRecord, TransactionRecord
37
+ from .transaction_models import Transaction
38
+
39
+ logger = logging.getLogger(__name__)
40
+
41
+
42
+ def _strip_ns(tag: str) -> str:
43
+ """Return local XML tag without namespace URI prefix."""
44
+ if tag.startswith("{"):
45
+ return str(etree.QName(tag).localname)
46
+ return tag
47
+
48
+
49
+ def _parse_iso_date(date_text: str | None) -> date | None:
50
+ """Parse ISO date or date-time text into datetime.date."""
51
+ if not date_text or not date_text.strip():
52
+ return None
53
+ cleaned = date_text.strip()
54
+ if len(cleaned) >= 10:
55
+ cleaned_date = cleaned[:10]
56
+ try:
57
+ return date.fromisoformat(cleaned_date)
58
+ except ValueError:
59
+ pass
60
+ return None
61
+
62
+
63
+ def _extract_entry_refs(elem: etree._Element) -> tuple[str | None, str | None]:
64
+ """Extract reference and end-to-end identifier from entry or detail."""
65
+ ref_elems = (
66
+ elem.findall(".//Ustrd")
67
+ + elem.findall(".//{*}Ustrd")
68
+ + elem.findall(".//Strd//Ref")
69
+ + elem.findall(".//{*}Strd//{*}Ref")
70
+ + elem.findall(".//CdtrRefInf/Ref")
71
+ + elem.findall(".//{*}CdtrRefInf/{*}Ref")
72
+ )
73
+ texts = [r.text.strip() for r in ref_elems if r.text and r.text.strip()]
74
+ reference = " ".join(dict.fromkeys(texts)) or None
75
+ e2e = elem.findtext(".//Refs/EndToEndId") or elem.findtext(
76
+ ".//{*}Refs/{*}EndToEndId"
77
+ )
78
+ end_to_end = e2e.strip() if e2e and e2e.strip() else None
79
+ return reference, end_to_end
80
+
81
+
82
+ def _extract_parties(elem: etree._Element) -> tuple[str, str]:
83
+ """Extract debtor and creditor party names from entry or detail."""
84
+ dbtr = (
85
+ elem.findtext(".//Dbtr/Nm")
86
+ or elem.findtext(".//{*}Dbtr/{*}Nm")
87
+ or elem.findtext(".//RltdPties/Dbtr/Nm")
88
+ or elem.findtext(".//{*}RltdPties/{*}Dbtr/{*}Nm")
89
+ or ""
90
+ )
91
+ cdtr = (
92
+ elem.findtext(".//Cdtr/Nm")
93
+ or elem.findtext(".//{*}Cdtr/{*}Nm")
94
+ or elem.findtext(".//RltdPties/Cdtr/Nm")
95
+ or elem.findtext(".//{*}RltdPties/{*}Cdtr/{*}Nm")
96
+ or ""
97
+ )
98
+ return dbtr.strip(), cdtr.strip()
99
+
100
+
101
+ def _parse_entry_records(
102
+ entry: etree._Element,
103
+ account_id: str,
104
+ default_currency: str,
105
+ redact_pii: bool,
106
+ ) -> list[TransactionRecord]:
107
+ """Extract standardized transaction records from an Ntry XML element."""
108
+ amt_elem = entry.find("Amt")
109
+ if amt_elem is None:
110
+ amt_elem = entry.find("{*}Amt")
111
+ cdt_dbt_elem = entry.find("CdtDbtInd")
112
+ if cdt_dbt_elem is None:
113
+ cdt_dbt_elem = entry.find("{*}CdtDbtInd")
114
+ if amt_elem is None:
115
+ raise ValueError("Transaction entry missing <Amt> element")
116
+ if cdt_dbt_elem is None:
117
+ raise ParserError("Transaction entry missing <CdtDbtInd>")
118
+
119
+ currency = amt_elem.get("Ccy") or default_currency
120
+ if not currency:
121
+ raise ParserError("Transaction entry missing currency (Ccy)")
122
+
123
+ direction = (cdt_dbt_elem.text or "").strip()
124
+ if direction not in {"CRDT", "DBIT"}:
125
+ raise ParserError(f"Invalid CdtDbtInd: {direction}")
126
+
127
+ raw_amt = iso_decimal(amt_elem.text, context="CAMT entry")
128
+ signed_amt = -raw_amt if direction == "DBIT" else raw_amt
129
+
130
+ val_dt = (
131
+ entry.findtext("./ValDt/Dt")
132
+ or entry.findtext("./{*}ValDt/{*}Dt")
133
+ or entry.findtext("./ValDt/DtTm")
134
+ or entry.findtext("./{*}ValDt/{*}DtTm")
135
+ or ""
136
+ )
137
+ bkg_dt = (
138
+ entry.findtext("./BookgDt/Dt")
139
+ or entry.findtext("./{*}BookgDt/{*}Dt")
140
+ or entry.findtext("./BookgDt/DtTm")
141
+ or entry.findtext("./{*}BookgDt/{*}DtTm")
142
+ or ""
143
+ )
144
+ ref, e2e = _extract_entry_refs(entry)
145
+ dbtr, cdtr = _extract_parties(entry)
146
+
147
+ rec: TransactionRecord = {
148
+ "Amount": signed_amt,
149
+ "Currency": currency,
150
+ "DrCr": direction,
151
+ "Debtor": dbtr,
152
+ "Creditor": cdtr,
153
+ "Reference": ref,
154
+ "EndToEndId": e2e,
155
+ "ValDt": val_dt,
156
+ "BookgDt": bkg_dt,
157
+ "AccountId": account_id,
158
+ "description": ref or f"{direction} {currency} {raw_amt}",
159
+ "amount": signed_amt,
160
+ "date": bkg_dt[:10] if len(bkg_dt) >= 10 else val_dt[:10] or None,
161
+ "currency": currency,
162
+ "account_id": account_id,
163
+ }
164
+ if redact_pii:
165
+ return [cast(TransactionRecord, redact_record(rec))]
166
+ return [rec]
167
+
168
+
169
+ def _build_model(record: TransactionRecord, source: str) -> Transaction:
170
+ """Convert a TransactionRecord dictionary into a unified Transaction."""
171
+ bkg = _parse_iso_date(record.get("BookgDt"))
172
+ val = _parse_iso_date(record.get("ValDt"))
173
+ desc = (
174
+ record.get("description") or record.get("Reference") or "Transaction"
175
+ )
176
+ return Transaction(
177
+ account_id=record.get("AccountId"),
178
+ currency=record.get("Currency") or "USD",
179
+ amount=record["Amount"],
180
+ booking_date=bkg,
181
+ value_date=val or bkg,
182
+ description=desc,
183
+ normalized_description=desc.lower(),
184
+ reference=record.get("Reference"),
185
+ transaction_id=record.get("EndToEndId"),
186
+ source=source,
187
+ source_method="deterministic",
188
+ )
189
+
190
+
191
+ def _clear_element(elem: etree._Element) -> None:
192
+ """Clear processed element and prune preceding siblings from DOM."""
193
+ elem.clear()
194
+ while elem.getprevious() is not None:
195
+ del elem.getparent()[0]
196
+
197
+
198
+ def _init_scope_summary() -> SummaryRecord:
199
+ """Initialize a blank scope summary record."""
200
+ return {
201
+ "account_id": None,
202
+ "currency": None,
203
+ "statement_date": None,
204
+ "transaction_count": 0,
205
+ "total_amount": Decimal("0.00"),
206
+ "opening_balance": None,
207
+ "closing_balance": None,
208
+ }
209
+
210
+
211
+ class _BaseCamtStreamParser(BankStatementParser):
212
+ """Base streaming parser for ISO 20022 CAMT report and notification files."""
213
+
214
+ SCOPE_TAG: ClassVar[str] = ""
215
+ DOCUMENT_TAG: ClassVar[str] = ""
216
+
217
+ def __init__(
218
+ self,
219
+ file_name: str | Path,
220
+ *,
221
+ xml_bytes: bytes | None = None,
222
+ source_name: str | None = None,
223
+ ) -> None:
224
+ """Initialize parser from path or in-memory XML bytes."""
225
+ super().__init__(file_name)
226
+ self._source_name = source_name or str(file_name)
227
+ if xml_bytes is not None:
228
+ self._xml_bytes = xml_bytes
229
+ self._is_memory = True
230
+ else:
231
+ path = InputValidator().validate_input_file_path(str(file_name))
232
+ self._xml_bytes = path.read_bytes()
233
+ self._is_memory = False
234
+ self._parsed_df: pd.DataFrame | None = None
235
+ self._summaries: list[SummaryRecord] = []
236
+
237
+ @classmethod
238
+ def from_string(cls, xml_string: str) -> _BaseCamtStreamParser:
239
+ """Create a parser instance directly from an XML string."""
240
+ raw = xml_string.encode("utf-8")
241
+ InputValidator()._validate_bytes_size(raw)
242
+ return cls("memory.xml", xml_bytes=raw, source_name="memory.xml")
243
+
244
+ @classmethod
245
+ def from_bytes(
246
+ cls, xml_bytes: bytes, source_name: str = "memory.xml"
247
+ ) -> _BaseCamtStreamParser:
248
+ """Create a parser instance directly from raw XML bytes."""
249
+ InputValidator()._validate_bytes_size(xml_bytes)
250
+ return cls(source_name, xml_bytes=xml_bytes, source_name=source_name)
251
+
252
+ def _handle_metadata_event(
253
+ self,
254
+ tag: str,
255
+ elem: etree._Element,
256
+ summary: SummaryRecord | None,
257
+ meta_state: dict[str, str],
258
+ ) -> None:
259
+ """Extract account, creation date, and balances for report scope."""
260
+ if tag == "Acct":
261
+ iban = elem.findtext(".//IBAN")
262
+ othr = elem.findtext(".//Othr/Id")
263
+ acct = (iban if iban is not None else (othr or "")).strip()
264
+ ccy = (elem.findtext("Ccy") or "").strip()
265
+ meta_state["acct"] = acct
266
+ meta_state["ccy"] = ccy
267
+ if summary is not None:
268
+ summary["account_id"] = acct or None
269
+ summary["currency"] = ccy or None
270
+ elif tag == "CreDtTm":
271
+ if summary is not None and elem.text:
272
+ summary["statement_date"] = elem.text.strip()[:10]
273
+ else:
274
+ self._handle_balance_tag(elem, summary)
275
+
276
+ def _yield_entry_records(
277
+ self,
278
+ elem: etree._Element,
279
+ meta_state: dict[str, str],
280
+ active_summary: SummaryRecord | None,
281
+ redact_pii: bool,
282
+ ) -> Iterator[TransactionRecord]:
283
+ """Yield records from an entry element and update scope summary."""
284
+ for rec in _parse_entry_records(
285
+ elem, meta_state["acct"], meta_state["ccy"], redact_pii
286
+ ):
287
+ if active_summary is not None:
288
+ active_summary["transaction_count"] += 1
289
+ active_summary["total_amount"] += rec["Amount"]
290
+ yield rec
291
+ _clear_element(elem)
292
+
293
+ def _stream_records(
294
+ self, redact_pii: bool = False
295
+ ) -> Iterator[TransactionRecord]:
296
+ """Stream transaction records via lxml iterparse with O(1) memory cleanup."""
297
+ stream = BytesIO(self._xml_bytes)
298
+ meta_state = {"acct": "", "ccy": ""}
299
+ scope_summaries: list[SummaryRecord] = []
300
+ active_summary: SummaryRecord | None = None
301
+
302
+ context = etree.iterparse(
303
+ stream,
304
+ events=("start", "end"),
305
+ resolve_entities=False,
306
+ load_dtd=False,
307
+ no_network=True,
308
+ huge_tree=False,
309
+ )
310
+
311
+ for event, elem in context:
312
+ if event == "start":
313
+ elem.tag = str(etree.QName(elem).localname)
314
+ if elem.tag == self.SCOPE_TAG:
315
+ meta_state["acct"] = ""
316
+ meta_state["ccy"] = ""
317
+ active_summary = _init_scope_summary()
318
+ continue
319
+
320
+ tag = elem.tag
321
+ if tag in ("Acct", "CreDtTm", "Bal"):
322
+ self._handle_metadata_event(
323
+ tag, elem, active_summary, meta_state
324
+ )
325
+ elif tag == "Ntry":
326
+ yield from self._yield_entry_records(
327
+ elem, meta_state, active_summary, redact_pii
328
+ )
329
+ elif tag == self.SCOPE_TAG:
330
+ if active_summary is not None: # pragma: no branch
331
+ scope_summaries.append(active_summary)
332
+ _clear_element(elem)
333
+
334
+ self._summaries = scope_summaries
335
+
336
+ def _handle_balance_tag(
337
+ self, elem: etree._Element, summary: SummaryRecord | None
338
+ ) -> None:
339
+ """Parse opening and closing balances into scope summary record."""
340
+ if summary is None:
341
+ return
342
+ code = (
343
+ elem.findtext(".//Tp/CdOrPrtry/Cd")
344
+ or elem.findtext(".//{*}Tp/{*}CdOrPrtry/{*}Cd")
345
+ or ""
346
+ )
347
+ amt_str = elem.findtext("Amt") or elem.findtext("{*}Amt")
348
+ if not amt_str:
349
+ return
350
+ amt = iso_decimal(amt_str, context="CAMT balance")
351
+ drcr = elem.findtext("CdtDbtInd") or elem.findtext("{*}CdtDbtInd")
352
+ signed = -amt if drcr == "DBIT" else amt
353
+ if code in ("OPBD", "PRCD"):
354
+ summary["opening_balance"] = signed
355
+ elif code in ("CLBD", "CLAV"):
356
+ summary["closing_balance"] = signed
357
+
358
+ def parse_streaming(
359
+ self, redact_pii: bool = False
360
+ ) -> Iterator[TransactionRecord]:
361
+ """Yield transaction records incrementally with O(1) memory guarantees."""
362
+ yield from self._stream_records(redact_pii=redact_pii)
363
+
364
+ def parse_streaming_transactions(
365
+ self, redact_pii: bool = False
366
+ ) -> Iterator[Transaction]:
367
+ """Yield validated Transaction pydantic models incrementally."""
368
+ source = self._source_name
369
+ for rec in self.parse_streaming(redact_pii=redact_pii):
370
+ yield _build_model(rec, source)
371
+
372
+ def parse(self, redact_pii: bool = False) -> pd.DataFrame:
373
+ """Parse statements into a pandas DataFrame."""
374
+ if self._parsed_df is not None:
375
+ return self._parsed_df
376
+ records = list(self.parse_streaming(redact_pii=redact_pii))
377
+ if not records:
378
+ df = pd.DataFrame(
379
+ columns=[
380
+ "Amount",
381
+ "Currency",
382
+ "DrCr",
383
+ "Debtor",
384
+ "Creditor",
385
+ "Reference",
386
+ "EndToEndId",
387
+ "ValDt",
388
+ "BookgDt",
389
+ "AccountId",
390
+ ]
391
+ )
392
+ else:
393
+ df = pd.DataFrame(records)
394
+ self._parsed_df = df
395
+ return self._parsed_df
396
+
397
+ def get_summaries(self) -> list[SummaryRecord]:
398
+ """Return account summaries for all scopes within the document."""
399
+ if self._parsed_df is None:
400
+ self.parse()
401
+ return self._summaries or [
402
+ {
403
+ "account_id": None,
404
+ "currency": None,
405
+ "statement_date": None,
406
+ "transaction_count": 0,
407
+ "total_amount": Decimal("0.00"),
408
+ "opening_balance": None,
409
+ "closing_balance": None,
410
+ }
411
+ ]
412
+
413
+ def get_summary(self) -> SummaryRecord:
414
+ """Return single document summary or raise if multiple scopes exist."""
415
+ return _single_summary(self.get_summaries())
416
+
417
+
418
+ class Camt052Parser(_BaseCamtStreamParser):
419
+ """Parse ISO 20022 CAMT.052 Bank-to-Customer Account Reports."""
420
+
421
+ SCOPE_TAG: ClassVar[str] = "Rpt"
422
+ DOCUMENT_TAG: ClassVar[str] = "BkToCstmrAcctRpt"
423
+
424
+
425
+ class Camt054Parser(_BaseCamtStreamParser):
426
+ """Parse ISO 20022 CAMT.054 Bank-to-Customer Debit/Credit Notifications."""
427
+
428
+ SCOPE_TAG: ClassVar[str] = "Ntfctn"
429
+ DOCUMENT_TAG: ClassVar[str] = "BkToCstmrDbtCdtNtfctn"
@@ -56,6 +56,8 @@ class InputValidator:
56
56
  ".STA",
57
57
  ".bai2",
58
58
  ".BAI2",
59
+ ".bai",
60
+ ".BAI",
59
61
  ".mt942",
60
62
  ".MT942",
61
63
  ".pdf",
@@ -17,6 +17,7 @@
17
17
 
18
18
  from __future__ import annotations
19
19
 
20
+ from .bai2 import Bai2Parser
20
21
  from .common import (
21
22
  CSV_COLUMN_GROUPS,
22
23
  _amount_or_zero,
@@ -34,6 +35,7 @@ from .ofx import OfxParser, QfxParser
34
35
 
35
36
  __all__ = [
36
37
  "CSV_COLUMN_GROUPS",
38
+ "Bai2Parser",
37
39
  "CsvStatementParser",
38
40
  "Mt940Parser",
39
41
  "OfxParser",
@@ -0,0 +1,293 @@
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
+ """BAI2 (Bank Administration Institute Standard 2) statement parser."""
17
+
18
+ from __future__ import annotations
19
+
20
+ from collections.abc import Iterator
21
+ from datetime import date, datetime
22
+ from decimal import Decimal
23
+ from pathlib import Path
24
+ from typing import Any
25
+
26
+ import pandas as pd
27
+
28
+ from ..base_parser import BankStatementParser, _single_summary
29
+ from ..record_types import SummaryRecord, TransactionRecord
30
+ from ..transaction_models import Transaction
31
+ from .common import _read_validated_text, _require_amount
32
+
33
+
34
+ def _parse_bai2_date(date_str: str) -> date | None:
35
+ """Parse YYMMDD or YYYYMMDD into a datetime.date."""
36
+ cleaned = date_str.strip()
37
+ if not cleaned:
38
+ return None
39
+ for fmt in ("%y%m%d", "%Y%m%d"):
40
+ try:
41
+ return datetime.strptime(cleaned, fmt).date()
42
+ except ValueError:
43
+ continue
44
+ return None
45
+
46
+
47
+ def _parse_bai2_amount(raw: str, currency: str | None) -> Decimal:
48
+ """Parse integer cents or decimal string into Decimal amount."""
49
+ val = raw.strip()
50
+ if not val:
51
+ return Decimal("0.00")
52
+ if "." in val:
53
+ return Decimal(val)
54
+ # Default 2 decimal places for standard currencies
55
+ return Decimal(val) / Decimal("100")
56
+
57
+
58
+ class _Bai2State:
59
+ """Internal mutable state during BAI2 streaming line traversal."""
60
+
61
+ def __init__(self) -> None:
62
+ """Initialize parser state with empty records and tracking."""
63
+ self.file_sender: str | None = None
64
+ self.file_receiver: str | None = None
65
+ self.group_currency: str | None = None
66
+ self.as_of_date: date | None = None
67
+ self.account_id: str | None = None
68
+ self.account_currency: str | None = None
69
+ self.opening_balance: Decimal | None = None
70
+ self.closing_balance: Decimal | None = None
71
+ self.last_record_type: str | None = None
72
+ self.last_tx: dict[str, Any] | None = None
73
+ self.summaries: list[SummaryRecord] = []
74
+ self.current_summary: SummaryRecord | None = None
75
+
76
+
77
+ class Bai2Parser(BankStatementParser):
78
+ """Parse BAI2 cash management statement files into standardized records."""
79
+
80
+ def __init__(self, file_name: str | Path) -> None:
81
+ """Validate and read BAI2 file content."""
82
+ super().__init__(file_name)
83
+ self._path, self._text = _read_validated_text(file_name)
84
+ self._parsed_df: pd.DataFrame | None = None
85
+ self._summaries: list[SummaryRecord] = []
86
+ self._transactions: list[Transaction] = []
87
+
88
+ def _reset_account_state(self, state: _Bai2State) -> None:
89
+ """Finalize prior account summary if any before starting new scope."""
90
+ if state.current_summary is not None:
91
+ state.summaries.append(state.current_summary)
92
+ state.opening_balance = None
93
+ state.closing_balance = None
94
+ state.last_tx = None
95
+
96
+ def _handle_header_01(self, parts: list[str], state: _Bai2State) -> None:
97
+ """Parse Record 01: File Header."""
98
+ if len(parts) >= 3:
99
+ state.file_sender = parts[1]
100
+ state.file_receiver = parts[2]
101
+ state.last_record_type = "01"
102
+
103
+ def _handle_header_02(self, parts: list[str], state: _Bai2State) -> None:
104
+ """Parse Record 02: Group Header."""
105
+ if len(parts) >= 5:
106
+ state.as_of_date = _parse_bai2_date(parts[4])
107
+ if len(parts) >= 7 and parts[6].strip():
108
+ state.group_currency = parts[6].strip()
109
+ state.last_record_type = "02"
110
+
111
+ def _handle_account_03(self, parts: list[str], state: _Bai2State) -> None:
112
+ """Parse Record 03: Account Identifier and summary balances."""
113
+ self._reset_account_state(state)
114
+ state.account_id = parts[1].strip() if len(parts) > 1 else None
115
+ curr = parts[2].strip() if len(parts) > 2 else ""
116
+ state.account_currency = curr or state.group_currency or "USD"
117
+
118
+ # Check for status/summary codes in fields 3+
119
+ idx = 3
120
+ while idx + 1 < len(parts):
121
+ code = parts[idx].strip()
122
+ amt_str = parts[idx + 1].strip()
123
+ if code in ("010", "040") and amt_str:
124
+ state.opening_balance = _parse_bai2_amount(
125
+ amt_str, state.account_currency
126
+ )
127
+ elif code in ("015", "045") and amt_str:
128
+ state.closing_balance = _parse_bai2_amount(
129
+ amt_str, state.account_currency
130
+ )
131
+ idx += 4 # type code, amount, item count, funds type
132
+
133
+ state.current_summary = {
134
+ "account_id": state.account_id,
135
+ "currency": state.account_currency,
136
+ "statement_date": (
137
+ state.as_of_date.isoformat() if state.as_of_date else None
138
+ ),
139
+ "transaction_count": 0,
140
+ "total_amount": Decimal("0.00"),
141
+ "opening_balance": state.opening_balance,
142
+ "closing_balance": state.closing_balance,
143
+ }
144
+ state.last_record_type = "03"
145
+
146
+ def _handle_detail_16(
147
+ self, parts: list[str], state: _Bai2State
148
+ ) -> Transaction | None:
149
+ """Parse Record 16: Transaction Detail."""
150
+ if len(parts) < 3:
151
+ return None
152
+ type_code = parts[1].strip()
153
+ raw_amt = _parse_bai2_amount(parts[2], state.account_currency)
154
+
155
+ # In BAI2: 100-399 are credits (+), 400-699 are debits (-)
156
+ is_debit = False
157
+ try:
158
+ code_num = int(type_code)
159
+ if 400 <= code_num <= 699:
160
+ is_debit = True
161
+ except ValueError:
162
+ pass
163
+
164
+ signed_amt = -abs(raw_amt) if is_debit else abs(raw_amt)
165
+ bank_ref = (parts[4].strip() or None) if len(parts) > 4 else None
166
+ cust_ref = (parts[5].strip() or None) if len(parts) > 5 else None
167
+ text_desc = parts[6].strip() if len(parts) > 6 else ""
168
+
169
+ tx = Transaction(
170
+ account_id=state.account_id,
171
+ currency=state.account_currency or "USD",
172
+ amount=signed_amt,
173
+ booking_date=state.as_of_date,
174
+ value_date=state.as_of_date,
175
+ description=text_desc or f"Type {type_code}",
176
+ normalized_description=(text_desc or f"Type {type_code}").lower(),
177
+ reference=cust_ref or bank_ref,
178
+ transaction_id=bank_ref,
179
+ source=str(self.file_name),
180
+ source_method="deterministic",
181
+ )
182
+ if state.current_summary is not None:
183
+ state.current_summary["transaction_count"] += 1
184
+ state.current_summary["total_amount"] += signed_amt
185
+ state.last_record_type = "16"
186
+ return tx
187
+
188
+ def _dispatch_line(
189
+ self, parts: list[str], state: _Bai2State
190
+ ) -> Transaction | None:
191
+ """Route parsed line tokens to the appropriate record handler."""
192
+ rec_type = parts[0] if parts else ""
193
+ if rec_type == "01":
194
+ self._handle_header_01(parts, state)
195
+ elif rec_type == "02":
196
+ self._handle_header_02(parts, state)
197
+ elif rec_type == "03":
198
+ self._handle_account_03(parts, state)
199
+ elif rec_type == "16":
200
+ return self._handle_detail_16(parts, state)
201
+ elif rec_type in ("49", "98", "99"):
202
+ state.last_record_type = rec_type
203
+ return None
204
+
205
+ def _iter_logical_records(self) -> Iterator[Transaction]:
206
+ """Stream normalized transactions from BAI2 lines."""
207
+ state = _Bai2State()
208
+ for raw_line in self._text.splitlines():
209
+ line = raw_line.strip()
210
+ if not line:
211
+ continue
212
+ if line.endswith("/"):
213
+ line = line[:-1]
214
+ parts = [p.strip() for p in line.split(",")]
215
+ tx = self._dispatch_line(parts, state)
216
+ if tx is not None:
217
+ yield tx
218
+
219
+ if state.current_summary is not None:
220
+ state.summaries.append(state.current_summary)
221
+ self._summaries = state.summaries
222
+
223
+ def parse_streaming(self) -> Iterator[TransactionRecord]:
224
+ """Stream dictionary transactions for lightweight processing."""
225
+ for tx in self._iter_logical_records():
226
+ yield {
227
+ "AccountId": tx.account_id,
228
+ "Currency": tx.currency,
229
+ "Amount": tx.amount,
230
+ "BookgDt": (
231
+ tx.booking_date.isoformat() if tx.booking_date else None
232
+ ),
233
+ "ValDt": tx.value_date.isoformat() if tx.value_date else None,
234
+ "description": tx.description,
235
+ "Reference": tx.reference,
236
+ "transaction_id": tx.transaction_id,
237
+ "amount": tx.amount,
238
+ "currency": tx.currency,
239
+ "account_id": tx.account_id,
240
+ "date": (
241
+ tx.booking_date.isoformat() if tx.booking_date else None
242
+ ),
243
+ }
244
+
245
+ def parse(self) -> pd.DataFrame:
246
+ """Parse all transactions and return as a pandas DataFrame."""
247
+ if self._parsed_df is not None:
248
+ return self._parsed_df
249
+
250
+ rows = list(self.parse_streaming())
251
+ if not rows:
252
+ df = pd.DataFrame(
253
+ columns=[
254
+ "AccountId",
255
+ "Currency",
256
+ "Amount",
257
+ "BookgDt",
258
+ "ValDt",
259
+ "description",
260
+ "Reference",
261
+ "transaction_id",
262
+ ]
263
+ )
264
+ else:
265
+ df = pd.DataFrame(rows)
266
+ df["Amount"] = df["Amount"].apply(
267
+ lambda v: _require_amount(v, context="Amount")
268
+ )
269
+
270
+ self._parsed_df = df
271
+ return self._parsed_df
272
+
273
+ def get_summary(self) -> SummaryRecord:
274
+ """Return primary summary for single-account statements."""
275
+ if self._parsed_df is None:
276
+ self.parse()
277
+ return _single_summary(self.get_summaries())
278
+
279
+ def get_summaries(self) -> list[SummaryRecord]:
280
+ """Return scoped summaries for all accounts in the BAI2 statement."""
281
+ if self._parsed_df is None:
282
+ self.parse()
283
+ return self._summaries or [
284
+ {
285
+ "account_id": None,
286
+ "currency": None,
287
+ "statement_date": None,
288
+ "transaction_count": 0,
289
+ "total_amount": Decimal("0.00"),
290
+ "opening_balance": None,
291
+ "closing_balance": None,
292
+ }
293
+ ]
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "bankstatementparser"
3
- version = "0.0.25"
3
+ version = "0.0.26"
4
4
  description = "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
  authors = ["Sebastien Rousseau <sebastian.rousseau@gmail.com>"]
6
6
  license = "Apache-2.0 OR MIT"