bankstatementparser 0.0.9__tar.gz → 0.0.10__tar.gz

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bankstatementparser
-Version: 0.0.9
+Version: 0.0.10
 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.
 License: Apache Software License
 License-File: LICENSE
@@ -49,7 +49,7 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <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>
-  <a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.9" alt="PyPI" /></a>
+  <a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.10" alt="PyPI" /></a>
   <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>
   <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>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="License" /></a>
@@ -93,8 +93,9 @@ services unless they explicitly opt in.
 - [Command Line](#command-line) — console script and REST API
 - [Deduplication](#deduplication) — exact hashes + suspected matches
 - [Export](#export) — CSV, JSON, Excel, Polars, hledger, beancount
-- [Examples](#examples) — 22 runnable scripts (14 deterministic + 8 hybrid)
+- [Examples](#examples) — 23 runnable scripts (14 deterministic + 9 hybrid)
 - [XML Tag Mapping](#xml-tag-mapping) — ISO 20022 tags to DataFrame columns
+- [Ecosystem](#ecosystem) — companion packages (MCP, LSP, writers, loaders)
 
 **Operational**
 
@@ -230,7 +231,7 @@ print(result.source_method)         # "deterministic"
 # Path B — text-LLM for digital PDFs (set BSP_HYBRID_MODEL=ollama/llama3)
 result = smart_ingest("statement.pdf")
 print(result.source_method)         # "llm"
-print(result.verification.status)   # VERIFIED | DISCREPANCY | FAILED
+print(result.verification.status)   # VERIFIED | DISCREPANCY | UNVERIFIABLE | FAILED
 
 # Path C — multimodal vision for scanned PDFs (set BSP_HYBRID_VISION_MODEL)
 # auto-routed when pypdf cannot extract enough text
@@ -311,7 +312,7 @@ flowchart TD
     Z --> V[verify_balance<br/>Golden Rule]
     Y --> V
     X --> V
-    V --> R[VERIFIED / DISCREPANCY / FAILED]
+    V --> R[VERIFIED / DISCREPANCY / UNVERIFIABLE / FAILED]
 ```
 
 Every extracted row carries an immutable `transaction_hash`, an
@@ -349,7 +350,7 @@ for the full surface.
 
 | Feature | Description |
 |---|---|
-| **Golden Rule verification** *(v0.0.5)* | Every result carries `opening + credits − debits == closing` status: `VERIFIED`, `DISCREPANCY`, or `FAILED`. |
+| **Golden Rule verification** *(v0.0.5)* | Every result carries `opening + credits − debits == closing` status: `VERIFIED`, `DISCREPANCY`, `UNVERIFIABLE`, or `FAILED`. |
 | **Multi-currency verification** *(v0.0.8)* | `verify_balance_multi_currency()` groups transactions by currency and runs the Golden Rule independently per group — no more false `DISCREPANCY` on multi-currency statements. |
 | **Idempotent dedup** *(v0.0.5)* | Every `Transaction` carries a stable `transaction_hash` (MD5 of date + normalized description + amount). `Deduplicator.dedupe_by_hash()` makes incremental ingestion safe to re-run. |
 | **Interactive review** *(v0.0.6)* | `--type review` CLI walks through discrepancies with accept/edit/skip/delete/quit. `IngestResult.to_json()` / `.from_json()` for stable round-trip with embedded audit trail. |
@@ -370,7 +371,7 @@ for the full surface.
 |---|---|
 | **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
 | **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
-| **Tested** | 818 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
+| **Tested** | 844 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
 
 ---
 
@@ -631,8 +632,8 @@ for currency, v in results.items():
 
 ## Examples
 
-See [`examples/`](examples/README.md) for 22 runnable scripts
-(14 deterministic + 8 hybrid):
+See [`examples/`](examples/README.md) for 23 runnable scripts
+(14 deterministic + 9 hybrid):
 
 ### Deterministic parsers
 
@@ -661,9 +662,11 @@ See [`examples/`](examples/README.md) for 22 runnable scripts
 | `hybrid/01_smart_ingest_deterministic.py` | Path A — `smart_ingest()` against a CAMT.053 fixture, $0 cost |
 | `hybrid/02_smart_ingest_text_llm.py` | Path B — text-LLM extraction from a digital PDF (mock or live Ollama) |
 | `hybrid/03_smart_ingest_vision.py` | Path C — multimodal vision extraction with `LOW_TEXT_DENSITY` auto-routing |
-| `hybrid/04_golden_rule.py` | All three `verify_balance()` outcomes |
+| `hybrid/04_golden_rule.py` | `verify_balance()`, `verify_transactions()`, and `verify_continuity()` across `VERIFIED` / `DISCREPANCY` / `UNVERIFIABLE` outcomes |
 | `hybrid/05_dedupe_recurring.py` | `normalize_description()` + `dedupe_by_hash()` for idempotent batching |
 | `hybrid/06_cli_walkthrough.sh` | Four flavours of the new `--type ingest` CLI subcommand |
+| `hybrid/06_cli_walkthrough.ps1` | PowerShell sibling of the bash walkthrough (native Windows) |
+| `hybrid/07_scan_and_ingest.py` | Bulk directory ingest with `scan_and_ingest()` — cross-file dedup + continuity check |
 
 See [`examples/hybrid/README.md`](examples/hybrid/README.md) for
 the full walkthrough including a Mermaid flow diagram, the
@@ -681,6 +684,37 @@ reconciliation pipelines.
 
 ---
 
+## Ecosystem
+
+`bankstatementparser` is the core engine. Optional, independently
+versioned companion packages build on it — each is its own repository
+and Python package, so you install only what you need and the core
+stays dependency-light.
+
+| Package | PyPI | Role | What it adds |
+|---|---|---|---|
+| [`bankstatementparser-mcp`](https://github.com/sebastienrousseau/bankstatementparser-mcp) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-mcp.svg)](https://pypi.org/project/bankstatementparser-mcp/) | AI agents | [Model Context Protocol](https://modelcontextprotocol.io) server — exposes detect / parse / validate / summarize as tools for Claude Desktop and other LLM clients |
+| [`bankstatementparser-lsp`](https://github.com/sebastienrousseau/bankstatementparser-lsp) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-lsp.svg)](https://pypi.org/project/bankstatementparser-lsp/) | Editors | Language Server with live MT940 diagnostics (missing tags, malformed balance / `:61:` lines) over [pygls](https://github.com/openlawlibrary/pygls) |
+| [`bankstatementparser-writer-xlsx`](https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-writer-xlsx.svg)](https://pypi.org/project/bankstatementparser-writer-xlsx/) | Output | Write parsed transactions (DataFrame, `Transaction` list, or dicts) to a polished Excel `.xlsx` workbook |
+| [`bankstatementparser-loader-mt942`](https://github.com/sebastienrousseau/bankstatementparser-loader-mt942) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-mt942.svg)](https://pypi.org/project/bankstatementparser-loader-mt942/) | Input | Parse SWIFT **MT942** interim transaction reports into `Transaction` objects (a format the core does not read) |
+| [`bankstatementparser-loader-bai2`](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-bai2.svg)](https://pypi.org/project/bankstatementparser-loader-bai2/) | Input | Parse **BAI2** cash-management files into `Transaction` objects (a format the core does not read) |
+
+Loaders turn an additional source format into the same unified
+`Transaction` model; writers take parsed data back out to another
+target. Each companion pins `bankstatementparser` as a dependency and
+ships its own 100%-coverage test suite.
+
+```bash
+# Mix and match: e.g. read an MT942 file, then export to Excel
+pip install bankstatementparser-loader-mt942 bankstatementparser-writer-xlsx
+```
+
+Loaders hand back the same `Transaction` model the core parsers
+produce, so `load_mt942_file(...)` then `write_xlsx(...)` composes
+cleanly — see each companion's README for runnable examples.
+
+---
+
 ## Project Layout
 
 ```text
@@ -690,9 +724,9 @@ bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
 bankstatementparser/export/     hledger + beancount journal export
 bankstatementparser/api.py      REST API microservice (FastAPI)
 docs/compliance/                ISO 13485 validation, risk register, traceability matrix
-examples/                       14 deterministic + 8 hybrid runnable example scripts
+examples/                       14 deterministic + 9 hybrid runnable example scripts
 scripts/                        SBOM generation, checksums, signature verification
-tests/                          818 tests (unit, integration, property-based, security, hybrid mocks)
+tests/                          844 tests (unit, integration, property-based, security, hybrid mocks)
 ```
 
 ---

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <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>
-  <a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.9" alt="PyPI" /></a>
+  <a href="https://pypi.org/project/bankstatementparser/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser.svg?style=for-the-badge&v=0.0.10" alt="PyPI" /></a>
   <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>
   <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>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/sebastienrousseau/bankstatementparser?style=for-the-badge" alt="License" /></a>
@@ -54,8 +54,9 @@ services unless they explicitly opt in.
 - [Command Line](#command-line) — console script and REST API
 - [Deduplication](#deduplication) — exact hashes + suspected matches
 - [Export](#export) — CSV, JSON, Excel, Polars, hledger, beancount
-- [Examples](#examples) — 22 runnable scripts (14 deterministic + 8 hybrid)
+- [Examples](#examples) — 23 runnable scripts (14 deterministic + 9 hybrid)
 - [XML Tag Mapping](#xml-tag-mapping) — ISO 20022 tags to DataFrame columns
+- [Ecosystem](#ecosystem) — companion packages (MCP, LSP, writers, loaders)
 
 **Operational**
 
@@ -191,7 +192,7 @@ print(result.source_method)         # "deterministic"
 # Path B — text-LLM for digital PDFs (set BSP_HYBRID_MODEL=ollama/llama3)
 result = smart_ingest("statement.pdf")
 print(result.source_method)         # "llm"
-print(result.verification.status)   # VERIFIED | DISCREPANCY | FAILED
+print(result.verification.status)   # VERIFIED | DISCREPANCY | UNVERIFIABLE | FAILED
 
 # Path C — multimodal vision for scanned PDFs (set BSP_HYBRID_VISION_MODEL)
 # auto-routed when pypdf cannot extract enough text
@@ -272,7 +273,7 @@ flowchart TD
     Z --> V[verify_balance<br/>Golden Rule]
     Y --> V
     X --> V
-    V --> R[VERIFIED / DISCREPANCY / FAILED]
+    V --> R[VERIFIED / DISCREPANCY / UNVERIFIABLE / FAILED]
 ```
 
 Every extracted row carries an immutable `transaction_hash`, an
@@ -310,7 +311,7 @@ for the full surface.
 
 | Feature | Description |
 |---|---|
-| **Golden Rule verification** *(v0.0.5)* | Every result carries `opening + credits − debits == closing` status: `VERIFIED`, `DISCREPANCY`, or `FAILED`. |
+| **Golden Rule verification** *(v0.0.5)* | Every result carries `opening + credits − debits == closing` status: `VERIFIED`, `DISCREPANCY`, `UNVERIFIABLE`, or `FAILED`. |
 | **Multi-currency verification** *(v0.0.8)* | `verify_balance_multi_currency()` groups transactions by currency and runs the Golden Rule independently per group — no more false `DISCREPANCY` on multi-currency statements. |
 | **Idempotent dedup** *(v0.0.5)* | Every `Transaction` carries a stable `transaction_hash` (MD5 of date + normalized description + amount). `Deduplicator.dedupe_by_hash()` makes incremental ingestion safe to re-run. |
 | **Interactive review** *(v0.0.6)* | `--type review` CLI walks through discrepancies with accept/edit/skip/delete/quit. `IngestResult.to_json()` / `.from_json()` for stable round-trip with embedded audit trail. |
@@ -331,7 +332,7 @@ for the full surface.
 |---|---|
 | **PII redaction** | Names, IBANs, and addresses masked by default — opt in with `--show-pii` |
 | **Secure ZIP** | `iter_secure_xml_entries()` rejects zip bombs, encrypted entries, and suspicious compression ratios |
-| **Tested** | 818 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
+| **Tested** | 844 tests, coverage gated at 100% in CI, property-based fuzzing with Hypothesis |
 
 ---
 
@@ -592,8 +593,8 @@ for currency, v in results.items():
 
 ## Examples
 
-See [`examples/`](examples/README.md) for 22 runnable scripts
-(14 deterministic + 8 hybrid):
+See [`examples/`](examples/README.md) for 23 runnable scripts
+(14 deterministic + 9 hybrid):
 
 ### Deterministic parsers
 
@@ -622,9 +623,11 @@ See [`examples/`](examples/README.md) for 22 runnable scripts
 | `hybrid/01_smart_ingest_deterministic.py` | Path A — `smart_ingest()` against a CAMT.053 fixture, $0 cost |
 | `hybrid/02_smart_ingest_text_llm.py` | Path B — text-LLM extraction from a digital PDF (mock or live Ollama) |
 | `hybrid/03_smart_ingest_vision.py` | Path C — multimodal vision extraction with `LOW_TEXT_DENSITY` auto-routing |
-| `hybrid/04_golden_rule.py` | All three `verify_balance()` outcomes |
+| `hybrid/04_golden_rule.py` | `verify_balance()`, `verify_transactions()`, and `verify_continuity()` across `VERIFIED` / `DISCREPANCY` / `UNVERIFIABLE` outcomes |
 | `hybrid/05_dedupe_recurring.py` | `normalize_description()` + `dedupe_by_hash()` for idempotent batching |
 | `hybrid/06_cli_walkthrough.sh` | Four flavours of the new `--type ingest` CLI subcommand |
+| `hybrid/06_cli_walkthrough.ps1` | PowerShell sibling of the bash walkthrough (native Windows) |
+| `hybrid/07_scan_and_ingest.py` | Bulk directory ingest with `scan_and_ingest()` — cross-file dedup + continuity check |
 
 See [`examples/hybrid/README.md`](examples/hybrid/README.md) for
 the full walkthrough including a Mermaid flow diagram, the
@@ -642,6 +645,37 @@ reconciliation pipelines.
 
 ---
 
+## Ecosystem
+
+`bankstatementparser` is the core engine. Optional, independently
+versioned companion packages build on it — each is its own repository
+and Python package, so you install only what you need and the core
+stays dependency-light.
+
+| Package | PyPI | Role | What it adds |
+|---|---|---|---|
+| [`bankstatementparser-mcp`](https://github.com/sebastienrousseau/bankstatementparser-mcp) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-mcp.svg)](https://pypi.org/project/bankstatementparser-mcp/) | AI agents | [Model Context Protocol](https://modelcontextprotocol.io) server — exposes detect / parse / validate / summarize as tools for Claude Desktop and other LLM clients |
+| [`bankstatementparser-lsp`](https://github.com/sebastienrousseau/bankstatementparser-lsp) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-lsp.svg)](https://pypi.org/project/bankstatementparser-lsp/) | Editors | Language Server with live MT940 diagnostics (missing tags, malformed balance / `:61:` lines) over [pygls](https://github.com/openlawlibrary/pygls) |
+| [`bankstatementparser-writer-xlsx`](https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-writer-xlsx.svg)](https://pypi.org/project/bankstatementparser-writer-xlsx/) | Output | Write parsed transactions (DataFrame, `Transaction` list, or dicts) to a polished Excel `.xlsx` workbook |
+| [`bankstatementparser-loader-mt942`](https://github.com/sebastienrousseau/bankstatementparser-loader-mt942) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-mt942.svg)](https://pypi.org/project/bankstatementparser-loader-mt942/) | Input | Parse SWIFT **MT942** interim transaction reports into `Transaction` objects (a format the core does not read) |
+| [`bankstatementparser-loader-bai2`](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-bai2.svg)](https://pypi.org/project/bankstatementparser-loader-bai2/) | Input | Parse **BAI2** cash-management files into `Transaction` objects (a format the core does not read) |
+
+Loaders turn an additional source format into the same unified
+`Transaction` model; writers take parsed data back out to another
+target. Each companion pins `bankstatementparser` as a dependency and
+ships its own 100%-coverage test suite.
+
+```bash
+# Mix and match: e.g. read an MT942 file, then export to Excel
+pip install bankstatementparser-loader-mt942 bankstatementparser-writer-xlsx
+```
+
+Loaders hand back the same `Transaction` model the core parsers
+produce, so `load_mt942_file(...)` then `write_xlsx(...)` composes
+cleanly — see each companion's README for runnable examples.
+
+---
+
 ## Project Layout
 
 ```text
@@ -651,9 +685,9 @@ bankstatementparser/enrichment/ Categorizer, AccountMapper, EnrichedTransaction
 bankstatementparser/export/     hledger + beancount journal export
 bankstatementparser/api.py      REST API microservice (FastAPI)
 docs/compliance/                ISO 13485 validation, risk register, traceability matrix
-examples/                       14 deterministic + 8 hybrid runnable example scripts
+examples/                       14 deterministic + 9 hybrid runnable example scripts
 scripts/                        SBOM generation, checksums, signature verification
-tests/                          818 tests (unit, integration, property-based, security, hybrid mocks)
+tests/                          844 tests (unit, integration, property-based, security, hybrid mocks)
 ```
 
 ---

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/_llm_common.py

@@ -56,6 +56,7 @@ _warned_destinations: set[tuple[str, str]] = set()
 
 
 def _is_local_api_base(api_base: Optional[str]) -> bool:
+    """Return whether an API base URL points at the local machine."""
     if not api_base:
         return True
     host = urlparse(api_base).hostname or ""

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/additional_parsers.py

@@ -118,6 +118,7 @@ CSV_COLUMN_GROUPS = {
 
 
 def _normalized_name(name: str) -> str:
+    """Fold a header name to lowercase ASCII alphanumerics for matching."""
     # NFKD + ASCII-encode folds accented characters to their base
     # letter (é -> e) so French/Spanish headers match their
     # unaccented synonym entries.
@@ -130,6 +131,7 @@ def _normalized_name(name: str) -> str:
 
 
 def _read_validated_text(file_name: str | Path) -> tuple[Path, str]:
+    """Validate the path and read its contents as UTF-8 text."""
     validator = InputValidator()
     path = validator.validate_input_file_path(str(file_name))
     try:
@@ -210,6 +212,7 @@ class CsvStatementParser(BankStatementParser):
         self._parsed_df: pd.DataFrame | None = None
 
     def _find_column(self, df: pd.DataFrame, logical_name: str) -> str | None:
+        """Return the DataFrame column matching a logical name, if any."""
         candidates = CSV_COLUMN_GROUPS[logical_name]
         for column in df.columns:
             column_name = str(column)
@@ -351,6 +354,7 @@ class OfxParser(BankStatementParser):
         self._parsed_df: pd.DataFrame | None = None
 
     def _tag_value(self, source: str, tag: str) -> str | None:
+        """Return the stripped value of an OFX/SGML tag, or None."""
         match = re.search(rf"<{tag}>([^<\r\n]+)", source, flags=re.IGNORECASE)
         if match is None:
             return None

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/api.py

@@ -89,6 +89,7 @@ class APIError(RuntimeError):
 
 
 def _resolve_max_upload_bytes() -> int:
+    """Resolve the max upload size from the environment or default."""
     raw = os.environ.get(ENV_MAX_UPLOAD_BYTES)
     if not raw:
         return DEFAULT_MAX_UPLOAD_BYTES
@@ -121,6 +122,7 @@ def _safe_basename(filename: Optional[str]) -> str:
 
 
 def _allowed_suffix(name: str) -> bool:
+    """Return whether a filename has an allowed input extension."""
     suffix = Path(name).suffix
     if not suffix:
         return False
@@ -170,7 +172,7 @@ def create_app(
     _file_field = File(...)
 
     @app.post("/ingest")  # type: ignore[untyped-decorator]
-    async def ingest(  # pragma: no cover - async endpoint needs ASGI server
+    async def ingest(
         file: UploadFile = _file_field,
     ) -> JSONResponse:
         """Upload a bank statement and get structured JSON back.
@@ -277,6 +279,7 @@ def _result_to_dict(result: Any) -> dict[str, Any]:
 
 
 def _verification_dict(v: Any) -> Optional[dict[str, Any]]:
+    """Serialize a verification result to a JSON-safe dict, or None."""
     if v is None:
         return None
     return {
@@ -319,5 +322,5 @@ def main() -> None:
             "Install with: pip install 'bankstatementparser[api]'"
         ) from exc
 
-    app = create_app()  # pragma: no cover - server entrypoint
-    uvicorn.run(app, host=args.host, port=args.port)  # pragma: no cover
+    app = create_app()
+    uvicorn.run(app, host=args.host, port=args.port)

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/cli.py

@@ -173,6 +173,7 @@ class BankStatementCLI:
         """
 
         def get_camt_stats(parser: Any) -> list[dict[str, Any]]:
+            """Return parser statistics as a list of dict rows."""
             data = parser.get_statement_stats()
             if isinstance(data, pd.DataFrame):
                 # list(DataFrame) would yield column names, not rows
@@ -375,7 +376,6 @@ class BankStatementCLI:
             )
             logger.error(f"Hybrid import failed: {exc}")
             sys.exit(1)
-            return  # pragma: no cover
 
         try:
             result = smart_ingest(str(file_path))
@@ -388,12 +388,10 @@ class BankStatementCLI:
             )
             logger.error(f"Hybrid runtime import failed: {exc}")
             sys.exit(1)
-            return  # pragma: no cover
         except Exception as exc:
             logger.error(f"Hybrid ingest failed: {exc}")
             print(f"Error: hybrid ingest failed - {exc}")
             sys.exit(1)
-            return  # pragma: no cover
 
         rows = [
             {
@@ -450,9 +448,11 @@ class BankStatementCLI:
         (when that file is JSON) or any other source that emits an
         :class:`~bankstatementparser.hybrid.IngestResult` via its
         ``to_json()`` method. When the statement-level status is
-        :class:`VerificationStatus.DISCREPANCY` or
-        :class:`VerificationStatus.FAILED`, every transaction is
-        reviewed. Independently, ``review_below`` routes individual
+        :class:`VerificationStatus.DISCREPANCY`,
+        :class:`VerificationStatus.UNVERIFIABLE`, or
+        :class:`VerificationStatus.FAILED` (i.e. anything other than
+        ``VERIFIED``), every transaction is reviewed. Independently,
+        ``review_below`` routes individual
         low-confidence rows into the same flow even when the
         statement verified cleanly. The operator is prompted with a
         single-character action menu:
@@ -493,7 +493,6 @@ class BankStatementCLI:
             )
             logger.error(f"Hybrid import failed: {exc}")
             sys.exit(1)
-            return  # pragma: no cover
 
         try:
             payload = file_path.read_text(encoding="utf-8")
@@ -502,7 +501,6 @@ class BankStatementCLI:
             logger.error(f"Failed to load IngestResult: {exc}")
             print(f"Error: cannot load IngestResult JSON - {exc}")
             sys.exit(1)
-            return  # pragma: no cover
 
         v = result.verification
         review_all = v is not None and v.status is not (
@@ -756,10 +754,13 @@ class BankStatementCLI:
         try:
             args = self.parser.parse_args()
         except SystemExit:
-            # argparse failed, which means required arguments are missing
+            # argparse failed, which means required arguments are missing.
+            # The explicit return keeps the function from falling through
+            # to the (now unbound) ``args`` reference when ``sys.exit`` is
+            # patched in tests; in production ``sys.exit`` raises first.
             print("Error: Missing required arguments")
             sys.exit(1)
-            return  # pragma: no cover
+            return
 
         # Check if required arguments are present (safety check)
         if (

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/enrichment/categorizer.py

@@ -178,6 +178,7 @@ def _build_messages(
     transactions: list[Transaction],
     schema: tuple[str, ...],
 ) -> list[dict[str, Any]]:
+    """Build the system/user message pair for a categorization call."""
     schema_block = "\n".join(f"  - {c}" for c in schema)
     rows = "\n".join(
         _format_row(idx, tx) for idx, tx in enumerate(transactions)
@@ -218,6 +219,7 @@ def _sanitize_for_prompt(value: str) -> str:
 
 
 def _format_row(index: int, tx: Transaction) -> str:
+    """Render one transaction as a single prompt line."""
     date = tx.booking_date.isoformat() if tx.booking_date else "????-??-??"
     desc = _sanitize_for_prompt(tx.description or "(no description)")
     return f"  [{index}] {date}  {tx.amount:>10}  {desc[:80]}"
@@ -331,6 +333,7 @@ class Categorizer:
         self,
         chunk: list[Transaction],
     ) -> list[EnrichedTransaction]:
+        """Categorize a single chunk of transactions via one LLM call."""
         completion = self._resolve_completion()
         messages = _build_messages(chunk, self.schema)
 
@@ -354,16 +357,17 @@ class Categorizer:
         return _build_enriched(chunk, payload, self._schema_lookup)
 
     def _resolve_completion(self) -> CompletionFn:
+        """Return the injected completion callable or import LiteLLM's."""
         if self.completion_fn is not None:
             return self.completion_fn
-        try:  # pragma: no cover - optional dep
+        try:
             from litellm import completion
-        except ImportError as exc:  # pragma: no cover - optional dep
+        except ImportError as exc:
             raise CategorizerError(
                 "litellm is required for the enrichment module. "
                 "Install with: pip install bankstatementparser[enrichment]"
             ) from exc
-        return completion  # type: ignore[no-any-return]  # pragma: no cover
+        return completion  # type: ignore[no-any-return]
 
 
 # ---------------------------------------------------------------------------
@@ -377,6 +381,7 @@ def _extract_message_content(response: Any) -> str:
 
 
 def _parse_json_payload(raw: str) -> dict[str, Any]:
+    """Tolerantly parse a JSON object from a model response."""
     return parse_json_payload(raw, error_cls=CategorizerError)
 
 
@@ -385,6 +390,7 @@ def _build_enriched(
     payload: dict[str, Any],
     schema_lookup: dict[str, str],
 ) -> list[EnrichedTransaction]:
+    """Map an LLM results payload back onto the input chunk by index."""
     raw_results = payload.get("results")
     if not isinstance(raw_results, list):
         raise CategorizerError("Enrichment payload missing 'results' list")

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/hybrid/evaluation.py

@@ -102,6 +102,7 @@ class EvalSummary:
 
 
 def _to_decimal(value: object, *, context: str) -> Decimal:
+    """Coerce a value to ``Decimal``, raising on malformed input."""
     try:
         return Decimal(str(value))
     except InvalidOperation as exc:
@@ -109,12 +110,14 @@ def _to_decimal(value: object, *, context: str) -> Decimal:
 
 
 def _optional_decimal(value: object, *, context: str) -> Optional[Decimal]:
+    """Coerce a value to ``Decimal``, returning ``None`` when empty."""
     if value is None or value == "":
         return None
     return _to_decimal(value, context=context)
 
 
 def _optional_date(value: object, *, context: str) -> Optional[date]:
+    """Parse an ISO date, returning ``None`` when empty and raising on bad input."""
     if value is None or value == "":
         return None
     try:
@@ -243,6 +246,7 @@ def _match_rows(
 def _description_matches(
     expected: Optional[str], actual: Optional[str]
 ) -> bool:
+    """Return whether two descriptions match after normalization."""
     if not expected:
         return not actual
     if not actual:
@@ -253,6 +257,7 @@ def _description_matches(
 
 
 def _ratio(numerator: int, denominator: int) -> float:
+    """Return ``numerator / denominator``, or 1.0 when the denominator is zero."""
     return numerator / denominator if denominator else 1.0
 
 
@@ -315,6 +320,7 @@ def score_extraction(
         )
 
     def _check(expected_value: object, actual_value: object) -> Optional[bool]:
+        """Compare values, returning ``None`` when nothing is pinned."""
         if expected_value is None:
             return None
         return expected_value == actual_value

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/hybrid/llm_extractor.py

@@ -127,6 +127,7 @@ class LLMExtractor:
         return _build_result(payload, raw, source_text=statement_text)
 
     def _resolve_completion(self) -> CompletionFn:
+        """Return the injected completion callable or import a backend."""
         if self._completion_fn is not None:
             return self._completion_fn
         # Auto-select the direct Ollama bridge for any ollama/* model
@@ -141,14 +142,14 @@ class LLMExtractor:
 
         if is_ollama_model(self.model):
             return ollama_direct_completion
-        try:  # pragma: no cover - optional dep
+        try:
             from litellm import completion
-        except ImportError as exc:  # pragma: no cover - optional dep
+        except ImportError as exc:
             raise LLMExtractorError(
                 "litellm is required for LLM extraction. "
                 "Install with: pip install bankstatementparser[hybrid]"
             ) from exc
-        return completion  # type: ignore[no-any-return]  # pragma: no cover
+        return completion  # type: ignore[no-any-return]
 
 
 def _extract_message_content(response: Any) -> str:
@@ -162,6 +163,7 @@ def _parse_json_payload(raw: str) -> dict[str, Any]:
 
 
 def _to_decimal(value: Any) -> Optional[Decimal]:
+    """Coerce a value to ``Decimal``, returning ``None`` when empty."""
     if value in (None, ""):
         return None
     try:
@@ -203,6 +205,7 @@ def _build_result(
     source_text: str = "",
     source_method: SourceMethod = "llm",
 ) -> LLMExtractionResult:
+    """Convert a parsed LLM payload into an :class:`LLMExtractionResult`."""
     raw_txs = payload.get("transactions") or []
     if not isinstance(raw_txs, list):
         raise LLMExtractorError("LLM 'transactions' field must be a list")

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/hybrid/ollama_direct.py

@@ -91,7 +91,7 @@ def ollama_direct_completion(**kwargs: Any) -> dict[str, Any]:
     """
     try:
         import httpx
-    except ImportError as exc:  # pragma: no cover - optional dep
+    except ImportError as exc:
         raise OllamaDirectError(
             "httpx is required for the direct Ollama bridge. "
             "Install with: pip install bankstatementparser[hybrid]"

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/hybrid/orchestrator.py

@@ -109,6 +109,7 @@ class IngestResult:
         return json.dumps(self._to_dict(), indent=indent, sort_keys=False)
 
     def _to_dict(self) -> dict[str, Any]:
+        """Build the JSON-serializable dict representation."""
         return {
             "schema_version": 1,
             "source_method": self.source_method,
@@ -146,6 +147,7 @@ class IngestResult:
 
     @classmethod
     def _from_dict(cls, data: dict[str, Any]) -> IngestResult:
+        """Reconstruct an instance from a decoded JSON dict, validating fields."""
         version = data.get("schema_version")
         if version not in (None, 1):
             raise ValueError(
@@ -185,6 +187,7 @@ class IngestResult:
 def _verification_to_dict(
     verification: Optional[BalanceVerification],
 ) -> Optional[dict[str, Any]]:
+    """Serialize a :class:`BalanceVerification` to a JSON-safe dict."""
     if verification is None:
         return None
     return {
@@ -203,6 +206,7 @@ def _verification_to_dict(
 def _verification_from_dict(
     data: Any,
 ) -> Optional[BalanceVerification]:
+    """Reconstruct a :class:`BalanceVerification` from a decoded dict."""
     if data is None:
         return None
     if not isinstance(data, dict):
@@ -229,12 +233,14 @@ def _verification_from_dict(
 
 
 def _decimal_to_str(value: Optional[Decimal]) -> Optional[str]:
+    """Encode a ``Decimal`` as a plain string, preserving ``None``."""
     if value is None:
         return None
     return format(value, "f")
 
 
 def _decimal_from_str(value: Any) -> Optional[Decimal]:
+    """Decode a string back into a ``Decimal``, preserving ``None``/empty."""
     if value is None or value == "":
         return None
     return Decimal(str(value))
@@ -313,10 +319,20 @@ def smart_ingest(
 
 
 def _safe_detect(file_path: Path, warnings: list[str]) -> Optional[str]:
+    """Detect the statement format, recording a warning on no match."""
     try:
         return detect_statement_format(str(file_path))
     except Exception as exc:
-        warnings.append(f"Format detection failed: {exc}")
+        logger.debug(
+            "Deterministic format detection did not match for %s: %s",
+            file_path,
+            exc,
+        )
+        warnings.append(
+            "No deterministic statement format matched "
+            "(not XML/CSV/OFX/QFX/MT940); routing to the hybrid "
+            "LLM/vision extraction pipeline"
+        )
         return None
 
 
@@ -328,6 +344,7 @@ def _run_deterministic(
     closing_balance: Optional[Decimal],
     warnings: list[str],
 ) -> IngestResult:
+    """Run the deterministic parser and wrap its output in an IngestResult."""
     parser = create_parser(str(file_path), fmt)
     raw = parser.parse()
     transactions = _coerce_transactions(raw, source=fmt)
@@ -443,6 +460,7 @@ def _run_vision(
     closing_balance: Optional[Decimal],
     warnings: list[str],
 ) -> IngestResult:
+    """Run the vision extractor and wrap its output in an IngestResult."""
     vision_extractor = vision_extractor or VisionExtractor()
     result = vision_extractor.extract(file_path)
     return _build_ingest_result(
@@ -462,6 +480,7 @@ def _build_ingest_result(
     closing_balance: Optional[Decimal],
     warnings: list[str],
 ) -> IngestResult:
+    """Assemble an IngestResult from an LLM result, running verification."""
     effective_opening = (
         opening_balance
         if opening_balance is not None
@@ -498,13 +517,13 @@ def _coerce_transactions(raw: object, *, source: str) -> list[Transaction]:
     if callable(to_dict):
         try:
             records = list(to_dict("records"))
-        except TypeError:  # pragma: no cover - non-DataFrame fallback
+        except TypeError:
             records = []
     elif isinstance(raw, list):
         records = [dict(item) for item in raw if isinstance(item, dict)]
     elif isinstance(raw, dict):
         records = [dict(raw)]
-    else:  # pragma: no cover - defensive
+    else:
         records = []
 
     transactions: list[Transaction] = []

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/hybrid/pdf_text.py

@@ -90,17 +90,18 @@ def extract_text_pages(
 
     if engine == "pypdf":
         pages = _extract_with_pypdf(pdf_path)
-    elif engine == "pdfplumber":  # pragma: no cover - opt-in extra
+    elif engine == "pdfplumber":
         pages = _extract_with_pdfplumber(pdf_path)
-    else:  # pragma: no cover - guarded by Literal
+    else:
         raise PDFExtractionError(f"Unknown PDF engine: {engine}")
     return [_strip_noise(page) for page in pages]
 
 
 def _extract_with_pypdf(pdf_path: Path) -> list[str]:
+    """Extract per-page text using the ``pypdf`` engine."""
     try:
         from pypdf import PdfReader
-    except ImportError as exc:  # pragma: no cover - optional dep
+    except ImportError as exc:
         raise PDFExtractionError(
             "pypdf is required for PDF extraction. "
             "Install with: pip install bankstatementparser[hybrid]"
@@ -109,7 +110,7 @@ def _extract_with_pypdf(pdf_path: Path) -> list[str]:
     try:
         reader = PdfReader(str(pdf_path))
         return [page.extract_text() or "" for page in reader.pages]
-    except Exception as exc:  # pragma: no cover - defensive
+    except Exception as exc:
         raise PDFExtractionError(
             f"Failed to read PDF {pdf_path}: {exc}"
         ) from exc
@@ -117,7 +118,8 @@ def _extract_with_pypdf(pdf_path: Path) -> list[str]:
 
 def _extract_with_pdfplumber(
     pdf_path: Path,
-) -> list[str]:  # pragma: no cover - opt-in extra
+) -> list[str]:
+    """Extract per-page text using the ``pdfplumber`` engine."""
     try:
         import pdfplumber
     except ImportError as exc:

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/hybrid/verification.py

@@ -16,7 +16,7 @@
 """Golden Rule balance verification.
 
 If ``opening + credits - debits != closing`` the statement is flagged
-as ``Discrepancy`` (or ``Failed`` when balances are missing). This is
+as ``Discrepancy`` (or ``Unverifiable`` when balances are missing). This is
 the single most important integrity check in the hybrid pipeline.
 """
 
@@ -34,10 +34,25 @@ from ..transaction_models import Transaction
 
 
 class VerificationStatus(str, Enum):
-    """Verification outcome for a parsed statement."""
+    """Verification outcome for a parsed statement.
+
+    Members:
+        VERIFIED: The rule was applied and the books balance.
+        DISCREPANCY: The rule was applied and the books do **not**
+            balance.
+        UNVERIFIABLE: The rule could **not** be applied — e.g. a
+            missing opening/closing balance or fewer than two
+            statements for a continuity check. The statement is not
+            wrong; it simply cannot be checked, so it is routed to
+            human review.
+        FAILED: Reserved for a genuine verification error — the check
+            itself could not run. No current code path emits this; it
+            remains for forward compatibility and (de)serialization.
+    """
 
     VERIFIED = "verified"
     DISCREPANCY = "discrepancy"
+    UNVERIFIABLE = "unverifiable"
     FAILED = "failed"
 
 
@@ -76,7 +91,7 @@ def verify_balance(
 
     Returns:
         A :class:`BalanceVerification` describing the outcome. The
-        ``status`` is ``FAILED`` only when the rule cannot be applied
+        ``status`` is ``UNVERIFIABLE`` when the rule cannot be applied
         (missing balances), not when it disagrees.
     """
     credits = Decimal("0")
@@ -91,7 +106,7 @@ def verify_balance(
 
     if opening_balance is None or closing_balance is None:
         return BalanceVerification(
-            status=VerificationStatus.FAILED,
+            status=VerificationStatus.UNVERIFIABLE,
             opening_balance=opening_balance,
             closing_balance=closing_balance,
             total_credits=credits,
@@ -152,10 +167,10 @@ def verify_balance_multi_currency(
     Args:
         transactions: Iterable of normalized transactions.
         balances: Optional ``{currency: (opening, closing)}`` dict.
-            When ``None``, verification runs with ``FAILED`` status
-            for every currency (no balances provided). When a
+            When ``None``, verification runs with ``UNVERIFIABLE``
+            status for every currency (no balances provided). When a
             currency appears in the transactions but not in this
-            dict, its verification is also ``FAILED``.
+            dict, its verification is also ``UNVERIFIABLE``.
         tolerance: Per-currency tolerance. Defaults to one cent.
 
     Returns:
@@ -188,9 +203,11 @@ def aggregate_verifications(
 ) -> BalanceVerification:
     """Collapse per-currency results into one statement-level verdict.
 
-    The aggregate ``status`` is the worst per-currency outcome:
-    ``DISCREPANCY`` if any currency disagrees, else ``FAILED`` if any
-    currency could not be checked, else ``VERIFIED``.
+    The aggregate ``status`` is the worst per-currency outcome
+    (worst-first): ``DISCREPANCY`` if any currency disagrees, else
+    ``FAILED`` if any currency hit a genuine verification error, else
+    ``UNVERIFIABLE`` if any currency could not be checked, else
+    ``VERIFIED``.
 
     ``total_credits``/``total_debits``/``actual_delta`` are raw sums
     across all currencies — useful as row-count-style magnitudes, not
@@ -218,6 +235,8 @@ def aggregate_verifications(
         status = VerificationStatus.DISCREPANCY
     elif VerificationStatus.FAILED in statuses:
         status = VerificationStatus.FAILED
+    elif VerificationStatus.UNVERIFIABLE in statuses:
+        status = VerificationStatus.UNVERIFIABLE
     else:
         status = VerificationStatus.VERIFIED
 
@@ -286,13 +305,13 @@ def verify_continuity(
 
     Returns:
         A :class:`ContinuityResult`. ``status`` is ``DISCREPANCY``
-        if any link has a gap beyond tolerance, else ``FAILED`` if
-        any link could not be checked (missing balance on either
+        if any link has a gap beyond tolerance, else ``UNVERIFIABLE``
+        if any link could not be checked (missing balance on either
         side, or fewer than two statements), else ``VERIFIED``.
     """
     if len(statements) < 2:
         return ContinuityResult(
-            status=VerificationStatus.FAILED,
+            status=VerificationStatus.UNVERIFIABLE,
             breaks=(),
             checked_links=0,
             unchecked_links=0,
@@ -337,7 +356,7 @@ def verify_continuity(
         )
     if unchecked:
         return ContinuityResult(
-            status=VerificationStatus.FAILED,
+            status=VerificationStatus.UNVERIFIABLE,
             breaks=(),
             checked_links=checked,
             unchecked_links=unchecked,
@@ -374,8 +393,8 @@ def verify_transactions(
 
     The single ``opening_balance``/``closing_balance`` pair cannot
     be attributed to one currency of a multi-currency statement, so
-    in that case every currency reports ``FAILED`` (cannot verify)
-    rather than a spurious mismatch.
+    in that case every currency reports ``UNVERIFIABLE`` (cannot
+    verify) rather than a spurious mismatch.
 
     Args:
         transactions: Iterable of normalized transactions.

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/hybrid/vision.py

@@ -314,9 +314,10 @@ class VisionExtractor:
         )
 
     def _render_pages(self, pdf_path: Path) -> list[bytes]:
+        """Render each PDF page (up to :attr:`max_pages`) as a PNG."""
         try:
             import pypdfium2 as pdfium
-        except ImportError as exc:  # pragma: no cover - optional dep
+        except ImportError as exc:
             raise VisionExtractorError(
                 "pypdfium2 is required for vision extraction. "
                 "Install with: "
@@ -358,7 +359,7 @@ class VisionExtractor:
         """
         try:
             import pypdfium2 as pdfium
-        except ImportError as exc:  # pragma: no cover - optional dep
+        except ImportError as exc:
             raise VisionExtractorError(
                 "pypdfium2 is required for vision extraction. "
                 "Install with: "
@@ -407,6 +408,7 @@ class VisionExtractor:
         return all_strips
 
     def _resolve_completion(self) -> CompletionFn:
+        """Return the injected completion callable or import a backend."""
         if self._completion_fn is not None:
             return self._completion_fn
         # Auto-select the direct Ollama bridge for any ollama/* model
@@ -421,15 +423,15 @@ class VisionExtractor:
 
         if is_ollama_model(self.model):
             return ollama_direct_completion
-        try:  # pragma: no cover - optional dep
+        try:
             from litellm import completion
-        except ImportError as exc:  # pragma: no cover - optional dep
+        except ImportError as exc:
             raise VisionExtractorError(
                 "litellm is required for vision extraction. "
                 "Install with: "
                 "pip install bankstatementparser[hybrid-vision]"
             ) from exc
-        return completion  # type: ignore[no-any-return]  # pragma: no cover
+        return completion  # type: ignore[no-any-return]
 
 
 STRIP_HEADER_SYSTEM_PROMPT = """You are a meticulous Financial Data

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/parallel.py

@@ -110,7 +110,7 @@ def parse_files_parallel(
             path = future_to_path[future]
             try:
                 results[path] = future.result()
-            except Exception as exc:  # pragma: no cover
+            except Exception as exc:
                 results[path] = FileResult(
                     path=path,
                     status="FAILED",

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/transaction_deduplicator.py

@@ -31,12 +31,14 @@ from .transaction_models import Transaction
 
 
 def _days_between(left: date | None, right: date | None) -> int | None:
+    """Return the absolute day gap between two dates, or None."""
     if left is None or right is None:
         return None
     return abs((left - right).days)
 
 
 def _description_similarity(left: Transaction, right: Transaction) -> float:
+    """Return the 0.0-1.0 similarity of two normalized descriptions."""
     if not left.normalized_description or not right.normalized_description:
         return 0.0
     return SequenceMatcher(
@@ -76,6 +78,8 @@ class DeduplicationResult(BaseModel):
 
 @dataclass(frozen=True)
 class _Candidate:
+    """A transaction paired with its source index and primary hash."""
+
     index: int
     transaction: Transaction
     primary_hash: str
@@ -247,6 +251,7 @@ class Deduplicator:
     def _candidate_groups_by_primary(
         self, candidates: list[_Candidate]
     ) -> dict[str, list[_Candidate]]:
+        """Group candidates by their primary hash."""
         groups: dict[str, list[_Candidate]] = defaultdict(list)
         for candidate in candidates:
             groups[candidate.primary_hash].append(candidate)
@@ -255,6 +260,7 @@ class Deduplicator:
     def _find_exact_duplicates(
         self, candidates: list[_Candidate]
     ) -> list[ExactDuplicateGroup]:
+        """Return groups of candidates sharing a primary hash."""
         groups = self._candidate_groups_by_primary(candidates)
         exact_groups = []
         for primary_hash, bucket in sorted(groups.items()):
@@ -281,6 +287,7 @@ class Deduplicator:
         *,
         excluded_indices: set[int],
     ) -> tuple[list[MatchGroup], set[int]]:
+        """Find probable and temporal match groups for operator review."""
         probable_groups, probable_indices = self._find_probable_matches(
             candidates
         )
@@ -299,6 +306,7 @@ class Deduplicator:
     def _find_probable_matches(
         self, candidates: list[_Candidate]
     ) -> tuple[list[MatchGroup], set[int]]:
+        """Match candidates by hash collision and description similarity."""
         groups = []
         matched_indices: set[int] = set()
         for bucket in self._candidate_groups_by_primary(candidates).values():
@@ -343,6 +351,7 @@ class Deduplicator:
     def _find_temporal_matches(
         self, candidates: list[_Candidate]
     ) -> tuple[list[MatchGroup], set[int]]:
+        """Match candidates with equal amounts but shifted value dates."""
         buckets: dict[tuple[str, str, str], list[_Candidate]] = defaultdict(
             list
         )
@@ -363,6 +372,7 @@ class Deduplicator:
             component: list[_Candidate],
             similarities: list[float],
         ) -> None:
+            """Record a matched component as a temporal match group."""
             matched_indices.update(candidate.index for candidate in component)
             groups.append(self._temporal_group(component, similarities))
 
@@ -413,6 +423,7 @@ class Deduplicator:
         component: list[_Candidate],
         similarities: list[float],
     ) -> MatchGroup:
+        """Build a temporal MatchGroup with a confidence and reason."""
         max_delta = (
             _days_between(
                 component[0].transaction.value_date,

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/bankstatementparser/transaction_models.py

@@ -34,6 +34,7 @@ from pydantic import (
 
 
 def _coerce_decimal(value: object) -> Decimal:
+    """Coerce a value into a Decimal amount, raising if empty."""
     text = str(value).strip()
     if not text:
         raise ValueError("amount is required")
@@ -41,6 +42,7 @@ def _coerce_decimal(value: object) -> Decimal:
 
 
 def _parse_date(value: object) -> date | None:
+    """Parse a value into a date across common formats, or None."""
     if value in (None, ""):
         return None
     if isinstance(value, date) and not isinstance(value, datetime):
@@ -98,6 +100,7 @@ def normalize_description(value: str | None) -> str:
 
 
 def _first_value(record: Mapping[str, object], *keys: str) -> object | None:
+    """Return the first non-empty value among the given keys, or None."""
     for key in keys:
         if key in record and record[key] not in (None, ""):
             return record[key]
@@ -136,6 +139,7 @@ class BoundingBox(BaseModel):
 
     @model_validator(mode="after")
     def _check_non_inverted(self) -> BoundingBox:
+        """Validate that the box corners are not inverted."""
         if self.x0 > self.x1:
             raise ValueError(
                 f"BoundingBox x0 ({self.x0}) must be <= x1 ({self.x1})"

{bankstatementparser-0.0.9 → bankstatementparser-0.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "bankstatementparser"
-version = "0.0.9"
+version = "0.0.10"
 description = "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."
 authors = ["Sebastien Rousseau <sebastian.rousseau@gmail.com>"]
 license = "Apache Software License"
@@ -31,9 +31,10 @@ pytest = ">=8.0.0,<10.0.0"
 pytest-cov = "^7.1.0"
 pytest-benchmark = "^5.1.0"
 ruff = "^0.15.7"
-mypy = "^1.5.0"
+mypy = ">=1.5,<3"
 bandit = "^1.7.0"
 hypothesis = ">=6.82,<7"
+interrogate = "^1.7.0"
 
 [tool.poetry.group.docs]
 optional = true
@@ -162,6 +163,28 @@ markers = [
     "slow: marks tests as slow-running performance or regression checks",
 ]
 
+[tool.interrogate]
+# Documentation coverage is enforced at 100% across the package, the
+# developer/CI helper scripts, and the runnable examples. Test modules
+# and the local virtualenv are excluded; everything else — including
+# private and nested helpers — must carry a docstring.
+fail-under = 100
+ignore-init-method = true
+ignore-magic = true
+ignore-module = false
+ignore-private = false
+ignore-nested-functions = false
+ignore-semiprivate = false
+exclude = [
+    ".venv",
+    "build",
+    "dist",
+    "tests",
+    "setup.py",
+    "docs",
+]
+verbose = 1
+
 [tool.coverage.run]
 source = ["bankstatementparser"]
 branch = true
@@ -170,5 +193,4 @@ branch = true
 exclude_lines = [
     "pragma: no cover",
     "if TYPE_CHECKING:",
-    "raise NotImplementedError",
 ]