DEV Community

alapha888
alapha888

Posted on

Bank statement PDFs to CSV with Python: what I built, what I actually tested

Every month the bank sends a PDF statement. The accounting software wants a CSV. In between there is usually a lot of retyping — slow, error-prone, and the file has to leave your machine if you use an online converter.

I built a small local tool that does the conversion on your own machine. This post is a walkthrough of how it works, and an honest account of what it has actually been tested on.

How it works

The converter is Python, with one runtime dependency: pdfplumber (0.11.10). It tries the text layer first:

  1. Table extraction. Most digital statements are tables. pdfplumber reads the ruling lines and pulls out rows with separate debit/credit columns, or a single amount column with +/- signs.
  2. Plain-text fallback. Some statements have no real table, just lines of text. A line parser handles date description amount [balance] rows.
  3. OCR only for scans. Scanned statements go through Tesseract. The OCR path needs Tesseract installed separately — it is not bundled in the Windows exe.

A few details that turned out to matter:

  • Dates come in many shapes (YYYY-MM-DD, YYYY/MM/DD, YYYY年MM月DD日, MM-DD, MM/DD). Everything is normalized to YYYY-MM-DD. A bare MM-DD takes its year from the document (a YYYY年 heading or the first full date), or from a --year flag.
  • Amounts handle thousands separators, +/- signs, and (123.45) parenthesised negatives.
  • NFKC normalization. Some PDF generators write - as U+2011 or put a few CJK characters in the compatibility zone. Normalizing first makes the matching work.
  • CSV output is UTF-8 with BOM, so Excel opens it without garbled characters. Columns are date, description, debit, credit, balance, and the raw source line for traceability.

What I actually tested

Numbers first, because that is the part that matters:

  • Digital PDFs: 4 synthetic layouts, 34 rows total, all fields accurate.
  • Clean scans: 6 sample rows via OCR, all accurate.
  • Windows exe: built in GitHub Actions (windows-latest, Python 3.12, PyInstaller --onefile), then smoke-tested on a 12-row fixture — the exe produced the expected 13-line CSV. The exe covers the digital-PDF path only.

What I have not tested

  • Real bank statements from real banks. The tests above use synthetic fixtures. Real statements have their own quirks, and I have not run the tool on real samples yet.
  • Degraded scans. Heavily degraded scans are out of scope for the first version.

I am writing this down plainly because a conversion tool that silently gets a number wrong is worse than no tool at all. The raw source line is kept in the CSV so every converted row can be traced back to the original.

The tool

The converter is open source: https://github.com/alapha888/bank-statement-presale

There is also a presale page with the full status, scope and refund terms: https://alapha888.github.io/bank-statement-presale/

No installer, no GUI, and no auto-update yet — those are still to do. If you try the converter on your own statements and it gets something wrong, that is exactly the kind of feedback I want to hear about.

Top comments (1)

Collapse
 
ravi_k_bea370720956169efb profile image
Ravi K •

Really like that you listed what you have NOT tested. That's rare in this space. Keeping the raw source line in the CSV is a smart call too. One check that could help once you try real statements: compare opening balance plus all rows against the printed closing balance for each statement. If that doesn't match, a row was dropped or a sign got flipped, and you can flag the file before anyone trusts it. I'm building something nearby (turning statements into categorized books), and multi-line descriptions that wrap onto the next line look like the trickiest part of US bank layouts. Curious how pdf plumber handles those for you.