beancount-black

Opinionated Beancount formatter library, just like Python's black code formatter but for Beancount

Try it out online here

Features

• MIT licensed - based on beancount-parser, a Lark based LALR(1) Beancount syntax parser
• Extremely fast - 5K+ lines file generated by bean-example can be formatted in around 1 second
• Section awareness - entries separated by Emac org symbol mark * will be formatted in groups without changing the overall structure
• Comment preserving - comments are preserved and will be formatted as well
• Auto column width - calculate maximum column width and adjust accordingly
• Valid beancount file assumed - please notice that the formatter assumes the given beacnount file is valid, it doesn't not perform any kind of validation

Sponsor

The original project beancount-black was meant to be an internal tool built by Launch Platform LLC for

A modern accounting book service based on the most popular open source version control system Git and text-based double entry accounting book software Beancount. We realized adding new entries with BeanHub automatically over time makes the beancount file a mess. So, a strong code formatter is needed. While SaaS businesses won't be required to open-source an internal tool like this, we still love that the service is only possible because of the open-source tool we are using. It would be greatly beneficial for the community to access a tool like this, so we've decided to open-source it under an MIT license. We hope you find this tool useful 😄

Install

Warning

Bean-black command-line is deprecated and will remain as is, with no feature updates. It's subject to removal in future versions. In the future, the beancount-black package will focus on serving as a Beancount formatter library. Please use beanhub-cli instead if you need a formatter command-line tool. Newer features like file traversal, account, or commodity renaming will only be available with beanhub-cli.

To install the formatter, simply run

pip install beancount-black

Usage

Run

bean-black /path/to/file.bean

Then the file will be formatted. Since this tool is still in its early stage, a backup file at <filepath>.backup will be created automatically by default just in case. The creation of backup files can be disabled by passing -n or --no-backup like this

bean-black -n /path/to/file.bean

It's highly recommended to use BeanHub, Git or other version control system to track your Beancount book files before running the formatter against them without a backup.

If you want to run the formatter programmatically, you can do this

import io

from beancount_parser.parser import make_parser
from beancount_black.formatter import Formatter

parser = make_parser()
formatter = Formatter()

tree = parser.parse(beancount_content)
output_file = io.StringIO()
formatter.format(tree, output_file)

Stdin mode

You can run the formatter in STDIN mode by passing -s or --stdin-mode argument like this:

bean-black -s

Debug

Sometimes you might encounter problems when formatting some beancount files. To debug and better understand which line is causing the problem, you can change the log level by passing -l argument with debug or verbose. For example:

bean-black -n /path/to/file.bean -l verbose

With verbose, details of the parsed object will be printed. With debug, only the line number and type of entry will be printed. You can also use LOG_LEVEL environment variable as well. The available log level options are:

• verbose
• debug
• info (default)
• error
• warning
• fatal

Future features

• Add argument for renaming account and commodity
• Add argument for following other files from include statements and also format those files

Feedbacks, bugs reporting or feature requests are welcome 🙌, just please open an issue. No guarantee we have time to deal with them, but will see what we can do.