Beancount v3 upgrade documentation

[Martin Michlmayr]

I haven't found any good Beancount v3 upgrade documentation, so I
start collecting some notes. Maybe this can be put into Google Docs
and improved upon.

# Changes in v3

* Several tools were split into separate projects:
* [beanquery](https://github.com/beancount/beanquery/): lightweight SQL query tool.
* [beangulp](https://github.com/beancount/beangulp): import framework for beancount. This is the evolution of beancount's `beancount.ingest`.
* [beancount2ledger](https://github.com/beancount/beancount2ledger): converter from beancount to ledger.

* bean-report was deprecated in beancount v2 and has been removed in beancount v3.
* [beanquery](https://github.com/beancount/beanquery/) is the preferred way to query beancount data.
* [Fava](https://github.com/beancount/fava) is a web UI to interact with beancount journals.

* The beancount syntax has been made more flexible:
* Currencies
* Single-character currency names are now supported
* A leading slash is now allowed (e.g. `/FOO`)
* The limitation for currency names to be 24 characters long has been dropped
* Flags
* Any of the A-Z characters are now valid flags

# Notes about beancount tools

## beangulp

* beangulp is compatible with beancount v2 and v3
* The upgrade to beangulp requires a number of changes from beancount's `beancount.ingest` framework:
* bean-extract no longer exists as a standalone script. You can [convert your config file to a callable script](https://github.com/beancount/beangulp/issues/127), as demonstrated in [import.py](https://github.com/beancount/beangulp/blob/master/examples/import.py). Call with `--help` to see arguments.
* Importers have to migrate from the `beancount.ingest` namespace to the `beangulp` namespace
* Look at [beangulp examples](https://github.com/beancount/beangulp/tree/master/examples) and [docstests](https://github.com/beancount/beangulp/tree/master/beangulp/tests) for some examples
* Optionally, importers can be moved from the old `beangulp.ImporterProtocol` interface to the new `beangulp.Importer` interface, which allows to implement some new features.

## beanquery

* beanquery is compatible with beancount v2 and v3
* beanquery has a lot of improvements over the older bean-query in beancount v2. Documentation is being worked on (Daniele, is there something to link to; or "look at source code" for now?)
* The [query history moved](https://github.com/beancount/beanquery/issues/207) from `~/.bean-shell-history` to `~/.config/beanquery/history`. If you want to preserve your query history, please move the file.

## Fava

* Fava is not compatible with beancount v3. This is [currently being worked on](https://github.com/beancount/fava/pull/1859).

## beancount2ledger

* Currently not tested with v3.

# Upgrade considerations

* The beancount syntax has become more permissive rather than more restrictive, so no changes to beancount journals should be required.
* beangulp and beanquery are compatible with both v2 and v3, so you can migrate to these tools before switching to v3.
* There is no drop-in replacement for `bean-report`. Please migrate to beanquery and the BQL query language.

--
Martin Michlmayr
https://www.cyrius.com/

[Lover O'Bean]

Thanks, Martin.  This addresses some confusion that I have had about which "C++ Rewrite" features were included in to the released v3.

[Daniele Nicolodi]

On 27/10/24 06:25, Martin Michlmayr wrote:
> I haven't found any good Beancount v3 upgrade documentation, so I
> start collecting some notes. Maybe this can be put into Google Docs
> and improved upon.
>
> # Changes in v3
>
> * Several tools were split into separate projects:
> * [beanquery](https://github.com/beancount/beanquery/): lightweight SQL query tool.
> * [beangulp](https://github.com/beancount/beangulp): import framework for beancount. This is the evolution of beancount's `beancount.ingest`.
> * [beancount2ledger](https://github.com/beancount/beancount2ledger): converter from beancount to ledger.

also beanprice https://github.com/beancount/beanprice

> * bean-report was deprecated in beancount v2 and has been removed in beancount v3.
> * [beanquery](https://github.com/beancount/beanquery/) is the preferred way to query beancount data.
> * [Fava](https://github.com/beancount/fava) is a web UI to interact with beancount journals.

bean-web has been removed too.

[...]

> ## beanquery
>
> * beanquery is compatible with beancount v2 and v3
> * beanquery has a lot of improvements over the older bean-query in beancount v2. Documentation is being worked on (Daniele, is there something to link to; or "look at source code" for now?)

The documentation will be living here
https://beancount.github.io/beanquery/ but so far there isn't much to
look at. I haven't done much more than preparing the infrastructure to
publish the documentation. Any contribution is very welcome.

Looking at the source code is always a good way to learn, but
extrapolating the SQL dialect understood by beanquery looking at the
source code may require more effort than the average reader is willing
to invest. The test cases are maybe the best starting point but, because
of its history, the code organization is not the most obvious, and the
relevant tests are a bit scattered around. Refactoring is in progress
but, it not being the most fun thing to do, the progress is slow.

Another good way to grasp what has changed is to look at the merged PRs
https://github.com/beancount/beanquery/pulls?q=is%3Apr+is%3Aclosed

Cheers,
Dan

[Martin Blais]

The C++ rewrite is now on the ice (source is preserved in branch cpp, a nice new parser essentially /shrug).

--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/beancount/f7291180-4a49-4383-83ea-b65181ac5c19n%40googlegroups.com.