Package: beanclerk
BeanclerkAutomation forBeancount.Features (for rationale seeNotes):network downloads (via APIs),automated categorization,insertion of new transactions.Supported data sources:Fio banka,Banka Creditas,or any other source implementing theAPI Importer Protocol.Project status:rough prototype; tested on Linux only.ExampleCreate aconfig fileand save it alongside your existing ledger:$ ls
beanclerk-config.yml  my_ledger.beancountImport 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 onidkey in transaction metadata to check for duplicates and to determine the date of the last import. You may leave out the--from-dateoption 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 CZKOnce 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)
...Installationpip install beanclerk[!IMPORTANT]
Beanclerk requires Beancount. You may needgccandpython3-devel(python3-devon some distros) for its successful installation. For further details check outBeancount Download & Installation.Confirm successful installation by running:bean-clerk -hNotesBeanclerk 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 BeancountImporter Protocol, Beanclerk proposes a simpleAPI Importer Protocolto 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 theSmart Importer).Insertion of new transactions: Beanclerkappendstransactions to the Beancount input file (i.e. the ledger) defined in the config. It saves the step of doing this manually. (With reporting tools likeFavaI 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 projectsI 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.ContributingSet up a development environment:pipenvsync--dev
pipenvrunpre-commitinstall[!NOTE]
If you prefer to create the virtual environment in the project's directory, addPIPENV_VENV_IN_PROJECT=1into.envfile. For more info seeVirtualenv mapping caveat.Run tests:pytestFollowConventional Commits.LicenseFollowing the Beancount license, this code is distributed under the terms of the "GNU GPLv2 only".