beanclerk 0.0.13

Description:

beanclerk 0.0.13

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:
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)
...

Installation
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

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 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.
License
Following the Beancount license, this code is distributed under the terms of the "GNU GPLv2 only".