Automation for Beancount.
Features (for rationale see Notes):
- network downloads (via APIs),
- automated categorization,
- insertion of new transactions.
Supported data sources:
- Fio banka,
- Banka Creditas,
- or any other source implementing the API Importer Protocol.
Project status: rough prototype; tested on Linux only.
Create a config file and save it alongside your existing ledger:
$ ls
beanclerk-config.yml my_ledger.beancount
Import new transactions:
$ bean-clerk import --from-date 2023-01-01
Account: 'Assets:Banks:Fio:Checking'
New transactions: 3, balance OK: 9830.00 CZK
Account: 'Assets:Banks:Fio:Savings'
New transactions: 0, balance OK: 50001.97 CZK
Important
Beanclerk relies on id
key in transaction metadata to check for duplicates and to determine the date of the last import. You may leave out the --from-date
option by adding a transaction like this:
2023-01-01 * "Initial import date for Beanclerk"
id: "dummy"
Assets:Banks:Fio:Checking 0 CZK
Assets:Banks:Fio:Savings 0 CZK
Once Beanclerk encounters a transaction without a matching categorization rule, it prompts you for resolution:
$ bean-clerk import
Account: 'Assets:Banks:Fio:Checking'
...
No categorization rule matches the following transaction:
2023-01-03 *
id: "10000000002"
account_id: "2345678901"
account_name: "Pavel, Žák"
bank_id: "2010"
bank_name: "Fio banka, a.s."
type: "Příjem převodem uvnitř banky"
specification: "test specification"
bic: "TESTBICXXXX"
order_id: "30000000002"
payer_reference: "test payer reference"
Assets:Banks:Fio:Checking 500.0 CZK
Available actions:
'r': reload config (you should add a new rule first)
'i': import as-is (transaction remains unbalanced)
...
pip install beanclerk
Important
Beanclerk requires Beancount. You may need gcc
and python3-devel
(python3-dev
on some distros) for its successful installation. For further details check out Beancount Download & Installation.
Confirm successful installation by running:
bean-clerk -h
Beanclerk automates some areas not addressed by Beancount:
- Network downloads: As financial institutions start to provide access to their services via APIs, it is more convenient and less error-prone to use them instead of a manual download and multi-step import from CSV (or similar) reports. Compared to these reports, APIs usually have a stable specification and provide transaction IDs, making the importing process (e.g. checking for duplicates) much easier. Therefore, inspired by Beancount Importer Protocol, Beanclerk proposes a simple API Importer Protocol to support virtually any API.
- Automated categorization: With growing number of new transactions, manual categorization quickly becomes repetitive, boring and error-prone. At the moment, Beanclerk provides a way to define rules for automated categorization. However, it might be interesting to augment it by machine-learning capabilities (e.g. via the Smart Importer).
- Insertion of new transactions: Beanclerk appends transactions to the Beancount input file (i.e. the ledger) defined in the config. It saves the step of doing this manually. (With reporting tools like Fava I don't care about the precise position of a new transaction in the file.) Consider to keep your ledger under a version control to make any changes easy to review.
I started Beanclerk to try out some Python packages and programming concepts. Actually, there are a couple of interesting projects of similar sort:
- beancount-import: Web UI for semi-automatically importing external data into beancount.
- finance-dl: Tools for automatically downloading/scraping personal financial data.
- beancount_reds_importers: Simple ingesting tools for Beancount (plain text, double entry accounting software). More importantly, a framework to allow you to easily write your own importers.
- smart_importer: Augment Beancount importers with machine learning functionality.
- autobean: A collection of plugins and scripts that help automating bookkeeping with beancount.
Set up a development environment:
pipenv sync --dev
pipenv run pre-commit install
Note
If you prefer to create the virtual environment in the project's directory, add PIPENV_VENV_IN_PROJECT=1
into .env
file. For more info see Virtualenv mapping caveat.
Run tests:
pytest
Follow Conventional Commits.
Following the Beancount license, this code is distributed under the terms of the "GNU GPLv2 only".