Upgrade Beancount & Fava to v3

Beancount 3.0.0 has been released for a while, and Fava recently released a compatible version. Today, I tried to upgrade my project; here are some notes.

My Beancount Ledger started recording in 2021 and has about 18,528 transaction records. I have also written some private plugins. Upgrading these private plugins generated a bit of work, but overall, it was pretty easy.

1. Upgrade version dependencies. I use PDM to manage dependencies, but other dependency management tools should be similar

- "beancount==2.3.6",
+ "beancount==3.0.0",
- "fava==1.29",
+ "fava==1.30",

2. Try running Fava

Running fava main.bean succeeded on the first try, but after startup, I found an error that the beancount.plugins.forecast plugin does not exist. After checking the 3.0.0 code, I discovered that forecast has been removed. So, I copied this plugin code from version 2.3.6, put it in my repository, and modified the plugin configuration in main.bean.

-plugin "beancount.plugins.forecast"
+plugin "my_private_leader.plugins.forecast"

After changing this line, Fava was able to run normally.

3. Run all unit tests

I have some unit tests in my Beancount Ledger, and when running these tests, I found that many of the original packages no longer exist under the beancount package. Here are some of the mappings I encountered:

beancount.query -> beanquery

-from beancount.query import query
+from beanquery import query

beancount.ingest -> beangulp

-from beancount.ingest.cache import _FileMemo
+from beangulp.cache import _FileMemo

Add related dependencies in pyproject.toml

+ "beangulp @ git+https://github.com/beancount/beangulp.git",
+ "beanquery @ git+https://github.com/beancount/beanquery.git",

The assertEqualEntries method for pytest is no longer exported from beancount.parser.cmptest, so I copied this file as well.

4. FileNotFoundError … ninja

If encountered the following issues:

ImportError while loading conftest 'beancount/conftest.py'.
conftest.py:9: in <module>
from beancount.core.data import Directive
.venv/lib/python3.12/site-packages/_beancount_editable_loader.py:311: in find_spec
tree = self._rebuild()
.venv/lib/python3.12/site-packages/_beancount_editable_loader.py:345: in _rebuild
subprocess.run(self._build_cmd, cwd=self._build_path, env=env, stdout=subprocess.DEVNULL, check=True)
/opt/homebrew/Cellar/python@3.12/3.12.6/Frameworks/Python.framework/Versions/3.12/lib/python3.12/subprocess.py:548: in run
with Popen(*popenargs, **kwargs) as process:
/opt/homebrew/Cellar/python@3.12/3.12.6/Frameworks/Python.framework/Versions/3.12/lib/python3.12/subprocess.py:1026: in __init__
self._execute_child(args, executable, preexec_fn, close_fds,
/opt/homebrew/Cellar/python@3.12/3.12.6/Frameworks/Python.framework/Versions/3.12/lib/python3.12/subprocess.py:1955: in _execute_child
raise child_exception_type(errno_num, err_msg, err_filename)
E FileNotFoundError: [Errno 2] No such file or directory: '/var/folders/jq/wsx0rmfs1cn0sd0gz7kvfpwh0000gn/T/pdm-build-env-7w21of0u-overlay/bin/ninja'
make: *** [test] Error 4

Delete the venv directory and rebuild the environment to resolve this issue.

These are all the issues I encountered when upgrading to beancount-v3. I hope this helps others who are upgrading.