beancount-black 0.1.15

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

beancount-black

Opinionated code formatter, 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 beancount file a mess. So obviously, 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. We think it would be greatly beneficial for the community to access a tool like this, so we've decided to open source it under MIT license, hope you find this tool useful 😄

Install

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.