Skip to content

Monopoly is a Python library & CLI that converts bank statement PDFs to CSV.

License

Notifications You must be signed in to change notification settings

benjamin-awd/monopoly

Repository files navigation


Streamlit Tests CI License: AGPL 3.0

Monopoly is a Python library & CLI that converts bank statement PDFs to CSV.

Supported banks:

Bank Credit Statement Debit Statement
Citibank
DBS/POSB
HSBC
Maybank
OCBC
Standard Chartered

Install

Monopoly is a pip-installable Python package on PyPI under the name monopoly-core.

Since Monopoly uses pdftotext, you'll need to install additional dependencies:

apt-get install build-essential libpoppler-cpp-dev pkg-config ocrmypdf

or

brew install gcc@11 pkg-config poppler ocrmypdf

Then install with pipx:

pipx install monopoly-core

Usage

Monopoly runs in your terminal, allowing you to extract, transform and write bank statements to a CSV file.

To list commands and options:

monopoly --help

You can run it on a single statement

monopoly src/monopoly/examples/example_statement.pdf

or multiple statements

monopoly ./statements

If you need to run monopoly on a password protected file, ensure that passwords are set in the .env file:

cp .env.template .env
PDF_PASSWORDS=["password1","password2"]

Monopoly can also be run as a Python library:

python3 src/monopoly/examples/single_statement.py

Features

  • Parses PDFs using predefined configuration classes per bank.
  • Handles locked PDFs with credentials passed via environment variables.
  • Supports adding OCR for image-based bank statements.
  • Provides a generic parser that can be used without any predefined configuration (caveat emptor).
  • Includes a safety check (enabled by default) that validates totals for debit or credit statements.

Development

Clone the repo

git clone https://github.com/benjamin-awd/monopoly.git

Install dependencies using Homebrew

brew install make
make setup
brew bundle