moneyusage

Based on the gnucash accountant software this commandline tool extends the possibilities of tracking the use of money.

Existing solutions

For my personal tracking of money I spend I use a spreadsheet. It is kind of OK but I cannot do serious evaluation based on that. The easy possibilies are quite limited. For example an yearly evaluation I have never done. The monthly overviews are bad since expenses that are used in other months are in there. Categorisations cannot be detailed.

GnuCash is more professional and would probably enable better evaluations. I would still want a commandline interface to create templates which is work.

Both solutions have one shortcoming: the usage of money is always assumed at the day of paying the stuff. But that is a very bad model of actual consumption: rent is used every day but only paid once a month. A holiday is one week long, maybe months in the future but paid now. A house is insulated with several tens of thousands of euros, so it is a very costly year but actually the use is spread over the following maybe 50 years. Gas is paid the same every month but in the winter you use much more of it. How much you know by regularly looking at your gas meter.

New idea for this project

This wrapper around gnucash should cure this shortcoming, allowing both accounting of payments and accounting of usage to get proper statistics. Using gnucash as a base gives a GUI both for developing as well as for additional usage of the same data. It also should make useful shortcuts and a quick-to-use command-line interface possible, creatable with hopefully easy python interfaces.

Implementation in terms of double accounting

The following paragraph describes the original idea implemented in the master branch. This branch uses a different idea: each split in a transaction can have a time span, implemented in the module time_span.

My understanding of double accounting (doppelte Buchführung) as in gnucash: every transaction has a date and a list of accounts (mostly two, but can be more) for which the transaction adds or subtracts money. The sum for all accounts for one transaction must be zero.

The idea is that one of the accounts is your bank account. It gets lower when you buy a toaster by 20€. At the same time your account „household“ gets higher by 20€ since you spent 20€ on household stuff.

This double accounting is useful to model both amounts of money that you have (bank accounts, cash, credits to and from other people) and categorisation (mobility, food, household, income, presents, donations, ...). My problem is only that the date the transaction has usually reflects well the date when my cash gets decreased but poorly when I actually use the benefit of my spending („use“ of the money). The solution can be achieved within the system of double accounting: one transaction moves money from the account „bank account“ to an intermediate account „tmp-vacation“ at the date of paying and 10 more transactions move each a tenth of the money from „tmp-vacation“ to „vacation“ at the 10 days when I do my vacation months later.

This solution is sound in terms of double accounting but not practical to do by hand. Especially when I have a lot of days (e.g. rent, internet, gas, electricity are a lot of daily costs that also needs changing up to several years later when the bill comes. Here this project comes into play: it should give an interface that captures the described 10 transactions into one „human understandable transaction“, let's call it „delayed transaction“, and allows easy handling and nice evaluation output.

Detail ideas

• Decision necessary: how many proxy accounts should exist. Options are:
  • one. Everything goes via a single one per currency. Used so far.
  • one per category account
  • one per delayed transaction Not sure if they have considerable (dis)advantages. In the best case this decision is only in a low level and could be changed without affecting a lot of code.
• Aggregation of buying things: not only using money but also spending money is spread over several transactions
  • Example: for building a house you need to pay a lot of individual things. Their usage is not independant but one big block, then distributed over 50 years. So it would make sense to collect all these payments and be able to change their use all at once: e.g. let it start as soon as the house in use.

Code

• Python
• with annotations
• with git-flowish workflow
• with tests existing before code existing („Test driven development“)
  • Based on some opinion use pytest
• use properties where useful: https://www.python-course.eu/python3_properties.php
• use type annotations: https://docs.python.org/3/library/typing.html
• use internationalizing: https://docs.python.org/3/library/i18n.html
• An conda environment should be supplied or easily set up.
  • It would be good to seperate the packages that are needed for development and those needed for running the software (much less)
• Thoughts about documentation: google-style for docstrings best for use with sphynx

Usage

To create a python environment with the necessary dependencies, install conda and run conda env create. It uses the configuration of the file environment.yml. Then run conda activate moneyusage to activate the new environment. Since the current piecash version does not work with the current GnuCash version, I probably have to adjust piecash to the current GnuCash (4.0). Right now I have temporarily "solved" the issue by removing the version check. I do not know when this will backfire. A pull request is heading in a similar direction but for GnuCash version 3.7: https://github.com/sdementen/piecash/pull/130. Since I am using a "custom" piecash version it is probably best to include this in a submodule and create pull requests if I adjust it to actually work with version 4.0 of GnuCash.

To run the tests, you need to "install" this project into the current environment. This is done via pip install --editable . in the environment file. Otherwise the source is not in the pythonpath and the tests cannot import it. It uses the setup.py with the setup.cfg config. The tests are run with pytest in the main directory. Test coverage can be calculated with the coverage module: coverage run --source=src -m pytest and shown with coverage report or coverage html afterwards.

To create the documentation go to the docs directory: cd docs and run make html. Then under docs/_build/html/index.html you can view the created documentation.