Files
accounts/src/statements.py
T
jimmyandClaude Opus 5.5 971de14356 Add cashbook web app for importing ANZ statements
Local web app and CLI that fill a NZ cashbook spreadsheet (one sheet per
month, April-March) from ANZ CSV exports and PDF statements, via a
headless LibreOffice.

- Import with preview; duplicates matched on date and amount so CSV and
  PDF versions of the same period don't double up
- Statement upload (drag and drop), view, download, rename and remove,
  with per-book import status
- Month review with GST and category editing, year summary and
  six-monthly GST returns
- Docker Compose setup; books and statements live in data/ (ignored)
- Blank cashbook template (NZ Government, CC BY 4.0); code under AGPL-3.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 17:10:05 +13:00

193 lines
7.4 KiB
Python

"""Read ANZ (NZ) statements — CSV exports or PDF statements — into transactions.
Each transaction is a dict with the CSV export's fields (Type, Details,
Particulars, Code, Reference, ForeignCurrencyAmount) plus `date` and `amount`
(negative for money out).
"""
import csv
import hashlib
import os
import re
import subprocess
from datetime import date, datetime
# ANZ "Type" -> cashbook "Payment origin" dropdown value
ORIGIN = {
"Visa Purchase": "Eftpos",
"Visa Refund": "Eftpos",
"Eft-Pos": "Eftpos",
"Bank Fee": "Direct Debit",
"Transfer": "Transfer",
"Direct Credit": "Direct credit",
"Direct Debit": "Direct Debit",
"Automatic Payment": "Auto payment",
"Payment": "Internet banking",
"Deposit": "Bank Deposit",
"Cash": "Cash",
"Cheque": "Cheque",
}
# Your own accounts (any suffix): transfers in are funds introduced, out are drawings
OWN_ACCOUNT_PREFIX = "01-0822-0082180-"
CARD_TYPES = ("Visa Purchase", "Visa Refund", "Eft-Pos")
def classify(t):
"""Return (gst, category heading or None) for a transaction."""
typ, amount = t["Type"], t["amount"]
if typ == "Bank Fee":
return "Excl GST", "Bank fees"
if t["Details"].strip().startswith(OWN_ACCOUNT_PREFIX):
return "Excl GST", ("Funds Intr." if amount > 0 else "Drawings")
if t["ForeignCurrencyAmount"].strip():
# Overseas purchases: no NZ GST to claim on the statement amount
return "Excl GST", None
if amount < 0:
return "Incl GST", None
return "Excl GST", None
def describe(t):
details = t["Details"].strip()
if t["Type"] in CARD_TYPES:
# Details is the card number; the merchant is in Code
details = t["Code"].strip() or details
if t["Type"] == "Visa Refund":
details += " (refund)"
extra = [t[k].strip() for k in ("Particulars", "Reference")
if t["Type"] not in CARD_TYPES + ("Transfer",) and t[k].strip()]
if t["ForeignCurrencyAmount"].strip():
extra.append(t["ForeignCurrencyAmount"].split(" converted")[0])
return " ".join([details] + ([f"({', '.join(extra)})"] if extra else []))
def read_statement(path):
if path.lower().endswith(".pdf"):
return read_pdf(path)[0]
return read_csv(path)
def read_csv(path):
with open(path, newline="", encoding="utf-8-sig") as f:
rows = list(csv.DictReader(f))
if rows and not {"Type", "Details", "Amount", "Date"} <= set(rows[0]):
raise ValueError("not an ANZ CSV export (missing Type/Details/Amount/Date columns)")
for t in rows:
t["date"] = datetime.strptime(t["Date"].strip(), "%d/%m/%Y").date()
t["amount"] = float(t["Amount"])
t["source"] = path
return rows
# --- PDF statements -------------------------------------------------------
PDF_TYPES = {
"VT": "Visa Purchase", "EP": "Eft-Pos", "IP": "Eft-Pos",
"BP": "Payment", "IF": "Payment", "DC": "Direct Credit",
"AP": "Automatic Payment", "DD": "Direct Debit", "CQ": "Cheque",
"AT": "Cash", "IA": "Cash", "FX": "Foreign Exchange", "ED": "Dishonour",
}
MONTHS = {m: i for i, m in enumerate(
"Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split(), 1)}
MONEY = r"-?[\d,]+\.\d{2}"
RE_PERIOD = re.compile(r"Statement period\s+(\d{1,2} \w{3} \d{4}) - (\d{1,2} \w{3} \d{4})")
RE_ACCOUNT = re.compile(r"Account number\s+([\d-]+)")
RE_TXN = re.compile(rf"^(\d{{2}}) ([A-Z][a-z]{{2}})\s+(?:([A-Z]{{2}})\s+)?(.*?)\s{{2,}}({MONEY})\s+({MONEY})(-|\s*OD)?\s*$")
RE_BALANCE = re.compile(rf"(?:Opening balance|Balance brought forward).*?\s({MONEY})(-|\s*OD)?\s*$")
RE_FOREIGN = re.compile(r"\s*\(([A-Z]{3} [\d,]+\.\d{2}) @ [\d.]+ ?\)")
def _money(s, overdrawn=None):
v = float(s.replace(",", ""))
return -v if overdrawn and overdrawn.strip() else v
def read_pdf(path):
"""Return (transactions, statement periods) from an ANZ PDF statement.
A file can hold several statements. Withdrawal vs deposit is taken from the
running balance, so it doesn't depend on column positions.
"""
text = subprocess.run(["pdftotext", "-layout", path, "-"], check=True,
capture_output=True, text=True).stdout
txns, periods = [], []
period_end = balance = None
seen_periods = set()
for line in text.splitlines():
m = RE_PERIOD.search(line)
if m:
start, end = (datetime.strptime(s, "%d %b %Y").date() for s in m.groups())
period_end = end
if (start, end) not in seen_periods:
seen_periods.add((start, end))
periods.append({"start": start, "end": end, "opening": None, "closing": None})
continue
m = RE_BALANCE.search(line)
if m:
balance = _money(*m.groups())
if "Opening balance" in line and periods and periods[-1]["opening"] is None:
periods[-1]["opening"] = balance
continue
m = RE_TXN.match(line)
if not m or period_end is None or balance is None:
continue
day, mon, code, details, amount, new_balance, od = m.groups()
new_balance = _money(new_balance, od)
change = round(new_balance - balance, 2)
if abs(abs(change) - _money(amount)) > 0.005:
raise ValueError(f"{path}: amount doesn't match balance on line: {line.strip()}")
balance = new_balance
periods[-1]["closing"] = balance
year = period_end.year if MONTHS[mon] <= period_end.month else period_end.year - 1
t = {"Type": PDF_TYPES.get(code, code or ""), "Details": "", "Particulars": "",
"Code": "", "Reference": "", "ForeignCurrencyAmount": "",
"date": date(year, MONTHS[mon], int(day)), "amount": change, "source": path}
fx = RE_FOREIGN.search(details)
if fx:
t["ForeignCurrencyAmount"] = fx.group(1)
details = RE_FOREIGN.sub("", details)
fields = re.split(r"\s{2,}", details.strip())
if t["Type"] in CARD_TYPES:
t["Code"] = fields[0]
if change > 0 and t["Type"] == "Visa Purchase":
t["Type"] = "Visa Refund"
else:
fields += [""] * 4
t["Details"], t["Particulars"], t["Code"], t["Reference"] = fields[:4]
if not code and "FEE" in details.upper():
t["Type"], t["Details"] = "Bank Fee", details.strip().capitalize()
elif t["Code"].upper() == "TRANSFER":
t["Type"] = "Transfer"
txns.append(t)
return txns, periods
RE_ACCOUNT_NO = re.compile(r"\d{2}-\d{4}-\d{7}-\d{2,3}")
def statement_info(path):
"""Summary of a statement file for listing: account, date range, count, balances."""
with open(path, "rb") as f:
sha = hashlib.sha256(f.read()).hexdigest()
if path.lower().endswith(".pdf"):
txns, periods = read_pdf(path)
text = subprocess.run(["pdftotext", "-l", "1", path, "-"],
capture_output=True, text=True).stdout
m = RE_ACCOUNT_NO.search(text)
else:
txns, periods = read_csv(path), []
m = RE_ACCOUNT_NO.search(os.path.basename(path))
dates = [t["date"] for t in txns]
return {
"sha256": sha,
"account": m.group(0) if m else None,
"count": len(txns),
"first": min(dates).isoformat() if dates else None,
"last": max(dates).isoformat() if dates else None,
"periods": [{k: (v.isoformat() if isinstance(v, date) else v) for k, v in p.items()}
for p in periods],
}