indian-finance-parsers

Parse Indian bank, card, broker and fund statements into plain Python records.

Part of infinparse; store purchase histories live in its sibling package purchase-history-parsers.

Each parser takes one file you downloaded or were emailed (a statement PDF, an Excel or CSV export, a saved web page, a statement saved from a web page) and returns a list of dataclasses. Where a file carries its own totals, row counts or running balances, the parser checks the rows against them and raises ValueError on a mismatch, so a dropped row or a flipped sign fails loudly instead of slipping through.

Supported sources

The decrypt extra is needed only to open password-protected files; the parser itself reads the decrypted copy.

Install and use

pip install "indian-finance-parsers[all]"

The base install needs only pdfplumber. The extras are excel (pandas, xlrd, openpyxl), cas (casparser), decrypt (pikepdf, msoffcrypto-tool) and all.

from indian_finance_parsers import adapter, meta
from indian_finance_parsers.decrypt import decrypted

hdfc = adapter("importers", "hdfc_card")
src = decrypted("statement.PDF", password="...")  # password=None if the file isn't protected
rows = hdfc.parse(src)        # list[Txn]
info = meta(hdfc, src)        # {"bin4": "..."}: which card this statement is for

decrypted() decrypts in memory: it returns an in-memory file (named like the original) that every PDF and Excel parser accepts, so the plaintext never touches disk. It returns the path unchanged when there's no password or the file isn't actually encrypted. Its errors name only the file, never the full path.

For your own adapters, indian_finance_parsers.checks has the reconciliation helpers the built-in bank parsers use: check_balance_chain(rows) (raises at the first row whose running balance doesn't chain; returns the opening balance) and order_by_balance(rows) (re-orders same-day rows a bank printed out of order).

To see a file's structure without seeing its contents: python -m indian_finance_parsers.peek FILE (needs the excel extra).

Models

All in indian_finance_parsers.models. Amounts are Decimal.

Txn (statement row)

Holding (portfolio snapshot row)

Whose holding it is (yours, joint, someone else's) isn't in any of these files, so it isn't a field. Subclass Holding in your own code if you track it.

Trade (Zerodha tradebook row): trade_id, date, symbol, isin, side (buy/sell), quantity, price, exchange.

Privacy

Everything runs locally. Parsers read only the file you pass them: no network, no config files, no environment variables. Parsers report what a file says and check it against itself; valuing holdings at today's prices, judging whether a deposit has matured and naming accounts are left to you. All test fixtures are synthetic, and CI runs a PII check over the tree and the full git history.

Your own parser

Write a module with parse(path) (and optionally meta(path)) anywhere on your Python path, then use it by its dotted path: adapter("importers", "mypkg.mybank"). No fork or registration is needed. To contribute one, add the module, a synthetic fixture, a test and a runbook; see docs/writing-an-adapter.md. examples/sources.example.toml shows one way a pipeline can map files to parsers.

Scope

Files only, including emails you save as files. This package does not fetch mail, log into banks, or store anything. Budgeting, ledgers and syncing to apps are left to the code that calls it.

Related projects

Beancount users write importers on beangulp. Indian-bank importers for it include dumbPy/beancount-importers-india (GPL-3.0) and prabusw/beancount-importers-india (AGPL-3.0), which cover banks and wallets this package doesn't yet. This package is the ledger-agnostic layer underneath: a Beancount importer can call these parsers from its extract().

Licence

MIT. See LICENSE.