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>
193 lines
7.4 KiB
Python
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],
|
|
}
|