Automation for Beancount
Project description
Beanclerk
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.
Example
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:
Transaction(
meta={
'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'
},
date=datetime.date(2023, 1, 3),
flag='*',
payee=None,
narration='',
tags=frozenset(),
links=frozenset(),
postings=[
Posting(
account='Assets:Banks:Fio:Checking',
units=500.0 CZK,
cost=None,
price=None,
flag=None,
meta={}
)
]
)
Available actions:
'r': reload config (you should add a new rule first)
'i': import as-is (transaction remains unbalanced)
...
Installation
pip install beanclerk
[!IMPORTANT] Beanclerk requires Beancount. You may need
gcc
andpython3-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
Notes
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.
Similar projects
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.
Contributing
Set up a development environment:
pipenv install --dev -e .
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.
License
Following the Beancount license, this code is distributed under the terms of the "GNU GPLv2 only".
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for beanclerk-0.0.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d60c4cc32aa09035cfa90db7427cf7c2e9e10d45c163e3b4f196f88734595b75 |
|
MD5 | 91d37cb559994d9d7284c105ec2fcfd9 |
|
BLAKE2b-256 | 3469edc8e674c59dc61f1bd0918f48363edfb5ad5473cdeab413740cd7d5c1b7 |