Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/LaunchPlatform/beancount-black
Opinionated code formatter, just like Python's black code formatter but for Beancount
https://github.com/LaunchPlatform/beancount-black
beancount formatter python
Last synced: about 1 month ago
JSON representation
Opinionated code formatter, just like Python's black code formatter but for Beancount
- Host: GitHub
- URL: https://github.com/LaunchPlatform/beancount-black
- Owner: LaunchPlatform
- License: mit
- Created: 2022-04-02T22:14:56.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-10-09T21:56:19.000Z (2 months ago)
- Last Synced: 2024-10-09T22:10:04.937Z (2 months ago)
- Topics: beancount, formatter, python
- Language: Python
- Homepage:
- Size: 117 KB
- Stars: 37
- Watchers: 3
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-beancount - beancount-black - Opinionated code formatter, just like Python's black code formatter but for Beancount (Tools / Misc)
README
# beancount-black [](https://circleci.com/gh/LaunchPlatform/beancount-black/tree/master)
Opinionated Beancount formatter library, just like Python's [black](https://pypi.org/project/black/) code formatter but for Beancount
Try it out online [here](https://app.beanhub.io/tools/beancount-formatter)
## Features
- **MIT licensed** - based on [beancount-parser](https://github.com/LaunchPlatform/beancount-parser), a [Lark](https://github.com/lark-parser/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](https://launchplatform.com) for
A modern accounting book service based on the most popular open source version control system [Git](https://git-scm.com/) and text-based double entry accounting book software [Beancount](https://beancount.github.io/docs/index.html).
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](https://github.com/LaunchPlatform/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
```bash
pip install beancount-black
```
## Usage
Run
```bash
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 `.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
```bash
bean-black -n /path/to/file.bean
```
It's highly recommended to use [BeanHub](https://beanhub.io), 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
```python
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:
```bash
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:
```bash
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.