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
```
