chkparse 1.0.0__tar.gz

chkparse-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+*.egg-info/
+*.pdf
+docs/
+scripts/

chkparse-1.0.0/ADDING_BANKS.md

@@ -0,0 +1,322 @@
+# Adding a New Bank Parser
+
+This guide shows how to add support for a new bank in v2.0.
+
+---
+
+## Example: Adding Chase Business Checking
+
+### Step 1: Create Parser File
+
+Create `src/chkparse/parsers/chase_business.py`:
+
+```python
+import re
+from datetime import datetime, date
+
+from ..domain.exceptions import DataIntegrityError
+from ..domain.models import TransactionType
+from .base import BankConfig, StatementParser
+
+
+class ChaseBusinessCheckingParser(StatementParser):
+    """Parser for Chase Business Checking statements."""
+    
+    def get_config(self) -> BankConfig:
+        return BankConfig(
+            # Chase uses different column coordinates
+            col_date=(40, 95),
+            col_desc=(100, 450),
+            col_amount=(480, 550),
+            col_serial=None,  # Chase doesn't show check serial numbers
+            
+            # Chase uses different patterns
+            date_pattern=r"^\d{2}/\d{2}$",
+            amount_pattern=r"^[\d,]+\.\d{2}$",
+            
+            # Chase uses different labels (with spaces)
+            summary_labels={
+                "Beginning Balance": "beginning_balance",
+                "Total Deposits": "deposits",
+                "Total Electronic Deposits": "electronic_deposits",
+                "Total Credits": "other_credits",
+                "Total Checks": "checks_paid",
+                "Total Electronic Payments": "electronic_payments",
+                "Total Withdrawals": "other_withdrawals",
+                "Service Charges": "service_charges",
+                "Ending Balance": "ending_balance",
+            },
+            
+            # Chase uses different section headers
+            section_headers={
+                "Deposits and Additions": TransactionType.DEPOSIT,
+                "Electronic Deposits": TransactionType.ELECTRONIC_DEPOSIT,
+                "Other Credits": TransactionType.OTHER_CREDIT,
+                "Checks": TransactionType.CHECK,
+                "Electronic Payments": TransactionType.ELECTRONIC_PAYMENT,
+                "Withdrawals": TransactionType.OTHER_WITHDRAWAL,
+            },
+            
+            # Chase-specific fingerprints
+            fingerprints={"CHASE", "BUSINESS CHECKING", "Account Summary"},
+        )
+    
+    def extract_header(self, rows: list[list[dict]]) -> dict:
+        """Extract Chase-specific header metadata."""
+        result = {}
+        for row in rows:
+            joined = "".join(w["text"] for w in row)
+            
+            # Chase format: "Business Name: ACME CORP"
+            if not result.get("entity") and "Business Name:" in joined:
+                m = re.search(r"Business Name:\s*(.+?)(?:\s|$)", joined)
+                if m:
+                    result["entity"] = m.group(1).strip()
+            
+            # Chase format: "Account Number: 123456789"
+            if not result.get("account") and "Account Number:" in joined:
+                m = re.search(r"Account Number:\s*(\d+)", joined)
+                if m:
+                    result["account"] = m.group(1)
+                    result["suffix"] = m.group(1)[-4:]
+            
+            # Chase format: "Statement Period: 01/26/2024 - 02/25/2024"
+            if not result.get("period") and "Statement Period:" in joined:
+                m = re.search(r"(\d{2}/\d{2}/\d{4})\s*-\s*(\d{2}/\d{2}/\d{4})", joined)
+                if m:
+                    result["period"] = f"{m.group(1)}-{m.group(2)}"
+            
+            if all(k in result for k in ("entity", "account", "period")):
+                break
+        
+        return result
+    
+    def parse_period(self, raw: str) -> tuple[date, date]:
+        """Parse Chase-specific period format: '01/26/2024 - 02/25/2024'."""
+        m = re.match(r"(\d{2}/\d{2}/\d{4})-(\d{2}/\d{2}/\d{4})", raw)
+        if not m:
+            raise DataIntegrityError(f"Cannot parse statement period: {raw!r}")
+        
+        start = datetime.strptime(m.group(1), "%m/%d/%Y").date()
+        end = datetime.strptime(m.group(2), "%m/%d/%Y").date()
+        return start, end
+```
+
+### Step 2: Update Factory
+
+Edit `src/chkparse/parsers/factory.py`:
+
+```python
+import pdfplumber
+
+from ..domain.exceptions import UnsupportedFormatError
+from .base import StatementParser
+from .td_business import TDBusinessCheckingParser
+from .chase_business import ChaseBusinessCheckingParser  # Add import
+
+
+class ParserFactory:
+    @staticmethod
+    def create_parser(pdf_path: str) -> StatementParser:
+        with pdfplumber.open(pdf_path) as pdf:
+            if not pdf.pages:
+                raise UnsupportedFormatError(f"{pdf_path!r} has no pages")
+            
+            text = pdf.pages[0].extract_text()
+            if not text:
+                raise UnsupportedFormatError(f"{pdf_path!r} has no extractable text")
+            
+            normalized = text.replace(" ", "").upper()
+            
+            # TD Business Checking
+            if "TD" in normalized and "ACCOUNTSUMMARY" in normalized:
+                return TDBusinessCheckingParser()
+            
+            # Chase Business Checking (NEW)
+            elif "CHASE" in normalized and "BUSINESSCHECKING" in normalized:
+                return ChaseBusinessCheckingParser()
+            
+            raise UnsupportedFormatError(
+                f"{pdf_path!r} is not a recognized bank statement format. "
+                f"Currently supported: TD Business Checking, Chase Business Checking"
+            )
+```
+
+### Step 3: Update Public API (Optional)
+
+Edit `src/chkparse/__init__.py`:
+
+```python
+from .parsers.chase_business import ChaseBusinessCheckingParser
+
+__all__ = [
+    # ... existing exports
+    "ChaseBusinessCheckingParser",  # Add to exports
+]
+```
+
+### Step 4: Add Tests
+
+Create `tests/test_chase_parser.py`:
+
+```python
+from chkparse import parse, ChaseBusinessCheckingParser
+from chkparse.parsers.factory import ParserFactory
+
+def test_factory_detects_chase():
+    parser = ParserFactory.create_parser("path/to/chase_statement.pdf")
+    assert isinstance(parser, ChaseBusinessCheckingParser)
+
+def test_parse_chase_statement():
+    statement = parse("path/to/chase_statement.pdf")
+    assert statement.account_suffix is not None
+    assert statement.account_summary.ending_balance is not None
+```
+
+---
+
+## That's It!
+
+You've added Chase support by:
+1. Creating one file (150 lines)
+2. Implementing 3 methods
+3. Adding 2 lines to factory
+4. Writing tests
+
+**No changes to:**
+- Domain models
+- Validators
+- Export layer
+- Infrastructure utilities
+- Existing TD parser
+
+**Time estimate:** 4-6 hours
+
+---
+
+## What You Need to Implement
+
+### Required Methods (3)
+
+1. **`get_config()`** - Return bank-specific configuration
+   - Column coordinates (analyze PDF with pdfplumber)
+   - Label mappings (from PDF text to field names)
+   - Section headers (transaction categories)
+   - Fingerprints (unique strings for detection)
+
+2. **`extract_header()`** - Parse statement metadata
+   - Entity name
+   - Account number
+   - Statement period
+
+3. **`parse_period()`** - Parse date range format
+   - Bank-specific date format
+   - Return (start_date, end_date)
+
+### Inherited (Automatic)
+
+- `parse()` - Template method (same for all banks)
+- `parse_unvalidated()` - Diagnostic parsing
+- `extract_account_summary()` - Uses your config
+- `extract_transactions()` - Uses your config
+- `assert_format()` - Uses your fingerprints
+
+---
+
+## Tips for Adding New Banks
+
+### 1. Analyze PDF Structure
+
+```python
+import pdfplumber
+
+with pdfplumber.open("statement.pdf") as pdf:
+    page = pdf.pages[0]
+    
+    # Extract words with coordinates
+    words = page.extract_words()
+    for w in words[:20]:
+        print(f"{w['text']:20} x0={w['x0']:.1f} top={w['top']:.1f}")
+```
+
+### 2. Find Column Ranges
+
+Look for consistent x0 coordinates:
+- Date column: x0 ≈ 40-95
+- Description: x0 ≈ 100-450
+- Amount: x0 ≈ 480-550
+
+### 3. Identify Fingerprints
+
+Unique strings that appear in every statement:
+- Bank name
+- "Account Summary" or similar
+- Specific formatting patterns
+
+### 4. Map Labels
+
+Find the exact text used for:
+- Beginning Balance
+- Deposits
+- Withdrawals
+- Ending Balance
+
+### 5. Test Thoroughly
+
+- Multiple statement periods
+- Edge cases (year boundaries)
+- Different transaction types
+- Balance validation
+
+---
+
+## Common Patterns
+
+### Pattern 1: Different Date Format
+
+```python
+def parse_period(self, raw: str) -> tuple[date, date]:
+    # Wells Fargo: "January 26, 2024 to February 25, 2024"
+    m = re.match(r"(\w+ \d+, \d{4}) to (\w+ \d+, \d{4})", raw)
+    start = datetime.strptime(m.group(1), "%B %d, %Y").date()
+    end = datetime.strptime(m.group(2), "%B %d, %Y").date()
+    return start, end
+```
+
+### Pattern 2: No Check Serial Numbers
+
+```python
+def get_config(self) -> BankConfig:
+    return BankConfig(
+        col_serial=None,  # Bank doesn't show check numbers
+        # ...
+    )
+```
+
+### Pattern 3: Different Section Names
+
+```python
+section_headers={
+    "Deposits": TransactionType.DEPOSIT,
+    "ACH Credits": TransactionType.ELECTRONIC_DEPOSIT,
+    "Wire Transfers": TransactionType.OTHER_CREDIT,
+    # ...
+}
+```
+
+---
+
+## Summary
+
+Adding a new bank requires:
+- ✅ 1 new file (~150 lines)
+- ✅ 3 methods to implement
+- ✅ 2 lines in factory
+- ✅ Tests
+
+**Reuses:**
+- ✅ All infrastructure (PDF extraction, coordinate detection)
+- ✅ All domain logic (validation, models)
+- ✅ All export logic (DataFrame, future OFX/CSV)
+
+**Time:** 4-6 hours per bank

chkparse-1.0.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: chkparse
+Version: 1.0.0
+Summary: Parse checking account PDF statements into structured financial data. Extensible multi-bank support with Strategy Pattern.
+Project-URL: Repository, https://github.com/rmuktader/chkparse
+Author-email: Rayhan Muktader <rmuktader@gmail.com>
+License: MIT
+Keywords: accounting,bank,checking,finance,parser,pdf,statement,td bank,toronto dominion bank
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: pandas>=2.0
+Requires-Dist: pdfplumber>=0.11
+Description-Content-Type: text/markdown
+
+# chkparse
+
+A Python library for extracting financial data from TD Business Convenience Plus checking account PDF statements.
+
+Parses transactions, account summaries, and validates the Golden Equation on every parse.
+
+---
+
+## Features
+
+- Extracts all transactions with posting date, description, amount, and type
+- Categorises transactions: `DEPOSIT`, `ELECTRONIC_DEPOSIT`, `OTHER_CREDIT`, `CHECK`, `ELECTRONIC_PAYMENT`, `OTHER_WITHDRAWAL`
+- Checks include `serial_number`
+- Validates `Beginning Balance + Credits - Debits = Ending Balance` on every parse
+- All monetary values use `decimal.Decimal`
+- Exports to Pandas DataFrame with `datetime64` date column
+
+---
+
+## Installation
+
+```bash
+pip install chkparse
+```
+
+Requires Python 3.11+.
+
+---
+
+## Quick Start
+
+```python
+from chkparse import parse
+
+statement = parse("path/to/statement.pdf")
+
+print(statement.account_suffix)           # "7410"
+print(statement.statement_period_start)   # datetime.date(2024, 12, 26)
+print(statement.account_summary.ending_balance)  # Decimal('4482.23')
+
+for t in statement.transactions:
+    print(t.posting_date, t.transaction_type, t.description, t.amount)
+```
+
+### Pandas Export
+
+```python
+from chkparse import parse
+from chkparse.export.export_service import to_df
+
+statement = parse("path/to/statement.pdf")
+df = to_df(statement)
+
+print(df.dtypes)
+# posting_date        datetime64[ns]
+# description                 object
+# amount                     float64
+# transaction_type            object
+# serial_number               object
+```
+
+---
+
+## Error Handling
+
+```python
+from chkparse import parse, BalanceMismatchError, DataIntegrityError
+
+try:
+    statement = parse("path/to/statement.pdf")
+except BalanceMismatchError as e:
+    print(e)
+except DataIntegrityError as e:
+    print(e)
+```
+
+| Exception | Raised when |
+|---|---|
+| `BalanceMismatchError` | Golden Equation validation fails |
+| `DataIntegrityError` | A required field is missing or unparseable |
+| `UnsupportedFormatError` | PDF is not a TD Business checking statement |
+| `ChkParserError` | Base class for all library errors |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/rmuktader/chkparse
+cd chkparse
+uv sync
+uv run pytest tests/ -v
+```

chkparse-1.0.0/README.md

@@ -0,0 +1,93 @@
+# chkparse
+
+A Python library for extracting financial data from TD Business Convenience Plus checking account PDF statements.
+
+Parses transactions, account summaries, and validates the Golden Equation on every parse.
+
+---
+
+## Features
+
+- Extracts all transactions with posting date, description, amount, and type
+- Categorises transactions: `DEPOSIT`, `ELECTRONIC_DEPOSIT`, `OTHER_CREDIT`, `CHECK`, `ELECTRONIC_PAYMENT`, `OTHER_WITHDRAWAL`
+- Checks include `serial_number`
+- Validates `Beginning Balance + Credits - Debits = Ending Balance` on every parse
+- All monetary values use `decimal.Decimal`
+- Exports to Pandas DataFrame with `datetime64` date column
+
+---
+
+## Installation
+
+```bash
+pip install chkparse
+```
+
+Requires Python 3.11+.
+
+---
+
+## Quick Start
+
+```python
+from chkparse import parse
+
+statement = parse("path/to/statement.pdf")
+
+print(statement.account_suffix)           # "7410"
+print(statement.statement_period_start)   # datetime.date(2024, 12, 26)
+print(statement.account_summary.ending_balance)  # Decimal('4482.23')
+
+for t in statement.transactions:
+    print(t.posting_date, t.transaction_type, t.description, t.amount)
+```
+
+### Pandas Export
+
+```python
+from chkparse import parse
+from chkparse.export.export_service import to_df
+
+statement = parse("path/to/statement.pdf")
+df = to_df(statement)
+
+print(df.dtypes)
+# posting_date        datetime64[ns]
+# description                 object
+# amount                     float64
+# transaction_type            object
+# serial_number               object
+```
+
+---
+
+## Error Handling
+
+```python
+from chkparse import parse, BalanceMismatchError, DataIntegrityError
+
+try:
+    statement = parse("path/to/statement.pdf")
+except BalanceMismatchError as e:
+    print(e)
+except DataIntegrityError as e:
+    print(e)
+```
+
+| Exception | Raised when |
+|---|---|
+| `BalanceMismatchError` | Golden Equation validation fails |
+| `DataIntegrityError` | A required field is missing or unparseable |
+| `UnsupportedFormatError` | PDF is not a TD Business checking statement |
+| `ChkParserError` | Base class for all library errors |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/rmuktader/chkparse
+cd chkparse
+uv sync
+uv run pytest tests/ -v
+```

chkparse-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chkparse"
+version = "1.0.0"
+description = "Parse checking account PDF statements into structured financial data. Extensible multi-bank support with Strategy Pattern."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [
+    { name = "Rayhan Muktader", email = "rmuktader@gmail.com" }
+]
+keywords = ["checking", "bank", "pdf", "finance", "statement", "parser", "accounting", "td bank", "toronto dominion bank"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pdfplumber>=0.11",
+    "pandas>=2.0",
+]
+
+[project.urls]
+Repository = "https://github.com/rmuktader/chkparse"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chkparse"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "openpyxl>=3.1",
+]

chkparse-1.0.0/src/chkparse/__init__.py

@@ -0,0 +1,55 @@
+# Domain models and exceptions
+from .domain.exceptions import (
+    BalanceMismatchError,
+    ChkParserError,
+    DataIntegrityError,
+    UnsupportedFormatError,
+)
+from .domain.models import AccountSummary, Statement, Transaction, TransactionType
+
+# Parsers
+from .parsers.factory import ParserFactory
+from .parsers.td_business import TDBusinessCheckingParser
+
+
+def parse(pdf_path: str) -> Statement:
+    """
+    Parse a checking account statement PDF (auto-detects bank).
+    
+    Args:
+        pdf_path: Path to the PDF statement file.
+    
+    Returns:
+        Statement: Parsed and validated statement.
+    
+    Raises:
+        UnsupportedFormatError: If bank format is not recognized.
+        BalanceMismatchError: If Golden Equation validation fails.
+        DataIntegrityError: If required fields are missing or unparseable.
+    
+    Example:
+        >>> from chkparse import parse
+        >>> statement = parse("statement.pdf")
+        >>> print(statement.account_summary.ending_balance)
+    """
+    parser = ParserFactory.create_parser(pdf_path)
+    return parser.parse(pdf_path)
+
+
+__all__ = [
+    # Main API
+    "parse",
+    "ParserFactory",
+    # Domain models
+    "Statement",
+    "Transaction",
+    "TransactionType",
+    "AccountSummary",
+    # Exceptions
+    "ChkParserError",
+    "BalanceMismatchError",
+    "DataIntegrityError",
+    "UnsupportedFormatError",
+    # Parsers (for advanced use)
+    "TDBusinessCheckingParser",
+]

chkparse-1.0.0/src/chkparse/domain/exceptions.py

@@ -0,0 +1,11 @@
+class ChkParserError(Exception):
+    pass
+
+class BalanceMismatchError(ChkParserError):
+    pass
+
+class DataIntegrityError(ChkParserError):
+    pass
+
+class UnsupportedFormatError(ChkParserError):
+    pass

chkparse-1.0.0/src/chkparse/domain/models.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass, field
+from datetime import date
+from decimal import Decimal
+from enum import Enum
+from typing import List
+
+
+class TransactionType(str, Enum):
+    DEPOSIT             = "DEPOSIT"
+    ELECTRONIC_DEPOSIT  = "ELECTRONIC_DEPOSIT"
+    OTHER_CREDIT        = "OTHER_CREDIT"
+    CHECK               = "CHECK"
+    ELECTRONIC_PAYMENT  = "ELECTRONIC_PAYMENT"
+    OTHER_WITHDRAWAL    = "OTHER_WITHDRAWAL"
+
+
+@dataclass(frozen=True)
+class Transaction:
+    posting_date: date
+    description: str
+    amount: Decimal          # always positive; sign implied by transaction_type
+    transaction_type: TransactionType
+    serial_number: str | None = None  # checks only
+
+
+@dataclass(frozen=True)
+class AccountSummary:
+    beginning_balance:   Decimal
+    deposits:            Decimal = Decimal("0")
+    electronic_deposits: Decimal = Decimal("0")
+    other_credits:       Decimal = Decimal("0")
+    checks_paid:         Decimal = Decimal("0")
+    electronic_payments: Decimal = Decimal("0")
+    other_withdrawals:   Decimal = Decimal("0")
+    service_charges:     Decimal = Decimal("0")
+    ending_balance:      Decimal = Decimal("0")
+
+
+@dataclass
+class Statement:
+    entity_name:            str
+    account_number:         str
+    account_suffix:         str
+    statement_period_start: date
+    statement_period_end:   date
+    account_summary:        AccountSummary
+    transactions:           List[Transaction] = field(default_factory=list)