Minimal instruction for non Python devs

I just set this up, and these are my notes. I wouldn't call it a definitive set of instructions, but it might be a start. One thing to note is that I am using a python virtual environment and am on macOS. Using system python and/or another OS might change things a bit.

Also, I would guess that the beancount discussion on Google groups would be a good place to ask questions, though I did figure out a few things by searching the issues here. In particular this thread was useful.

Install

pip install --upgrade git+https://github.com/beancount/beangrow

I found I needed to chmod 755 all of the executables, e.g. (note your paths will probably be different from what I have)

chmod 755 python_3/lib/python3.10/site-packages/beangrow/configure.py

And before running I had to set an environment variable to use python for the protocol buffers. I think this is because I had some old versions of various packages in my virtual environment. Regardless, it did work after setting the variable.

export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python

The configure.py script will only consider commodities that have an explicit open statement. I was not using this, so the initial output was empty. You can use a plugin in your ledger file to enforce commodity statements, then if you run validate you will get a list (via error messages) of all the statements you need.

plugin "beancount.plugins.check_commodity"

Then you need a statement such as

1989-01-01 commodity MSFT

The configure.py script assumes that you have an account structure that matches the one in the documentation, e.g. asset and income accounts like

Assets:Investments:Taxable:MyBrokerage:Cash
Assets:Investments:Taxable:MyBrokerage:MSFT
Income:Investments:Taxable:MyBrokerage:MSFT:Dividend

beangrow doesn't require this, but the configure script assumes it. If you don't have an account structure like this I think you would need to manually create the config and/or modify configure.py.

Once I had done this I was able to generate a config using configure.py. It was quite good, with only a few issues. However, it naturally includes all of your investments and so is a lot to start with. I stripped it down to just a single security at this point so that it would be easier to work with. I did this editing manually (just removing all but one security and group), and I'll go back and add the full config later.

Per the issue linked above I needed to enable this plugin

plugin "beancount.plugins.implicit_prices"

to get compute_returns.py to run. I did not have enough price data in my ledger without the implicit prices plugin I guess.

I could then generate some sample output (which are web pages in a set of three directories):

compute_returns.py beancount_ledgers/main.bc ./test.config ./beangrow

This will use some estimated prices for certain points in time and record those in a file. You can use a different script to fetch the actual prices which will improve accuracy:

download_prices_from_file.py -v beangrow/prices/prices.beancount

Finally, I added the Fava plugin to display this information in Fava.

pip install git+https://github.com/andreasgerstmayr/fava-portfolio-returns.git

Then in your ledger enable it:

2010-01-01 custom "fava-extension" "fava_portfolio_returns" "{
  'beangrow_config': '/path/to/beangrow/config.pbtxt',
}"

That's as far as I've gotten, but it did all work without issue.

beancount / beangrow

Minimal instruction for non Python devs #20

Install