| Name | garbanzo JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A collection of utilities related to the beancount (plaintext accounting) framework. |
| upload_time | 2025-01-10 23:04:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2024 Jeremy Silver and Zach Silver
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
beancount
finance
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Garbanzo
[](https://pypi.org/project/garbanzo)
[](https://raw.githubusercontent.com/jeremander/garbanzo/main/LICENSE)
[](https://github.com/pre-commit/pre-commit)
A collection of utilities related to the beancount (plaintext accounting) framework.
Eventually, some of the more public-facing utilities may be migrated to another library.
## This Repository
- `garbanzo/`: Main Python package for garbanzo
- `hooks/`: pre-commit [hooks](#pre-commit-hooks)
- `pyproject.toml`: config file for the `garbanzo` Python package, including the list of requirements
- At present we are maintaining [forks](#forks-of-other-libraries) of some libraries which are not yet compatible with `beancount` v3. Eventually we hope to be able to use the standard versions.
- `tests/`: Contains unit test modules.
- `tests/examples/`: Contains example files for tests, etc.
## Installing the Library
To install the `garbanzo` Python library, do `pip install .` (or `uv pip install .`) from the top-level directory.
## Command-line Program
Installing the library will also install the `garbanzo` command-line program. To see the menu of subcommands, run `garbanzo --help`.
Next we provide an overview of the different subcommands.
### `dl-assistant`
Assists in manually downloading data files from financial institutions and importing them into your beancount ledger.
**Usage**: `garbanzo dl-assistant [ACCOUNTS_FILE] [DATA_DIR]`
This command takes advantage of two metadata fields on "open" directives:
1. `url`: url to transaction download page
2. `manual_edit`: `true` or `false`
The `url` field will tell `dl-assistant` what URL to open when handling the
account. If `manual_edit` is set to `true`, `dl-assistant` won't check for
downloads, and will instead prompt to open the transaction file to add
transactions manually.
### `filter`
Applies one or more filters to entries in a beancount ledger. A *filter* is a function that can either remove entries or (more commonly) modify their contents, e.g. to impose a set of "rules" for assigning narrations/accounts in a consistent way.
**Usage**: `garbanzo filter [LEDGER_FILE] --json-filters [JSON_FILES] --inplace`
- `LEDGER_FILE` is your top-level ledger file. This may have "include" statements to incorporate multiple beancount files, in which case the tool will normalize all included files.
- `JSON_FILES` is a list of one or more paths to JSON files, each of which must contain a list of filters. See below for a description of the JSON schema for specifying filters.
It is generally preferable to use the `--inplace` flag, which will modify all of the files in-place. Otherwise, it will save copies of each file, applying a `.filt.beancount` suffix to each one.
In the future we plan to add more default filters, in addition to expanding the JSON filter schema.
#### JSON Filter Schema
You can specify custom rules for modifying transactions via the `--json-filters` argument. See [`filters.json`](tests/examples/filters.json) for an example of a JSON filter file. It should consist of a list of JSON objects, each containing two keys, `match` and `set`. Each ledger entry will be checked on each filter's `match` condition, and if it matches, the `set` condition will be triggered, possibly modifying the entry. Entries that do not match will be left alone.
At present the JSON filters only apply to transactions, not other types of beancount entries.
The current schema is described below (but note that it is subject to change):
- `match`: a JSON object with the following fields (all optional):
- `narration` (string): [regular expression](https://docs.python.org/3/howto/regex.html#regex-howto) to match the narration
- `payee` (string): regular expression to match the payee
- `account_prefixes` (list of strings): account prefixes to match
- Matches a transaction if for each prefix listed, some posting exists with that prefix.
**NOTE**: Regular expressions only need to match a part of a string, and they match case-insensitively. For example, the regular expression `PIZZA` will match the string `Vincent's Pizza`.
**NOTE**: If multiple fields are set, *all* of the criteria will have to be matched. There is currently no way to match on "any" instead of "all," but in the future there may be.
- `set`: a JSON object with the following fields (all optional):
- `narration` (string): narration to set
- `payee` (string): payee to set
- `tags` (list of strings): tags to set
- `links` (list of strings): links to set
- `account` (string): account to set
- Since transactions have multiple postings, this account will only be set for a unique posting matching this account type.
- For example, if the value of `account` is `"Expenses:Food:Restaurants"`, then it will modify a posting whose account starts with `Expenses`, provided it is the only such posting.
**NOTE**: If a field's value is set to `null`, the corresponding value of the beancount entry will be removed. In contrast, if a field is absent, the value will be left alone. (In other words, absent and `null`-valued do *not* mean the same thing.)
As an illustration of the JSON filter system, if you run the `filter` subcommand on [`transactions.beancount`](tests/examples/transactions.beancount) using [`filters.json`](tests/examples/filters.json), the result is [`transactions.filtered.beancount`](tests/examples/transactions.filtered.beancount).
### `normalize`
Normalizes a beancount ledger. Sorts entries, normalizes whitespace and currency alignment.
**Usage**: `garbanzo normalize [LEDGER_FILE] --inplace`
Here `LEDGER_FILE` is your top-level ledger file. This may have "include" statements to incorporate multiple beancount files, in which case the tool will normalize all included files.
It is generally preferable to use the `--inplace` flag, which will modify all of the files in-place. Otherwise, it will save copies of each file, applying a `.norm.beancount` suffix to each one.
## Pre-commit Hooks
This repo provides [pre-commit](https://pre-commit.com/) hooks, defined in [.pre-commit-hooks.yaml](.pre-commit-hooks.yaml).
Currently there is one hook defined called `bean-check`, which you can install in your beancount ledger repository to validate the ledger before each commit.
To install it:
1. Make sure you have the `pre-commit` tool installed (e.g. with `pip install pre-commit`).
2. Create a `.pre-commit-config.yaml` file at the top level of your repository. It should be identical to the [example-pre-commit.yaml](hooks/example-pre-commit-config.yaml) file, except you should replace `"my_ledger.beancount"` with the path to your own ledger file. Then run `git add .pre-commit-config.yaml` to add it to your repo.
3. Run `pre-commit install`.
The hook should now be installed in `.git/hooks/pre-commit`. It will run automatically whenever you make a commit (as long as at least one file has been updated). You can also do `pre-commit run` to run the hook without having to commit.
## Links
- [beancount](https://github.com/beancount/beancount): core library
- Main [documentation](https://beancount.github.io/docs/)
- Current version is [v3](https://beancount.github.io/docs/beancount_v3.html), still transitioning from v2.
- [fava](https://github.com/beancount/fava): web front-end
- [BeanHub](https://beanhub.io): enterprise-grade app built on beancount
- Free tier only allows 1,000 entries in personal repo.
- [lazy-beancount](https://github.com/Evernight/lazy-beancount): batteries-included system (web interface, extra plugins)
- [beancount-lazy-plugins](https://github.com/Evernight/beancount-lazy-plugins): plugins for beancount, most notably:
- `valuation`: track total value of the opaque fund over time
- `filter_map`: apply operations to group of transactions selected by Fava filters
### Auto-importing
- [SimpleFin](https://www.simplefin.org): open-source interchange language for financial transactions
- [Plaid](https://plaid.com): popular enterprise financial API
- [beanhub-import](/blog/2024/05/27/introduction-of-beanhub-import/): one small step closer to fully automating transaction importing ([Github repo](https://github.com/LaunchPlatform/beanhub-import))
### Forks of other libraries
- [beancount-import](https://github.com/jeremander/beancount-import): Import entries from raw data files.
- [v3-compat](https://github.com/jeremander/beancount-import/tree/v3-compat) branch
- [beangulp](https://github.com/jeremander/beangulp): New importer framework
- [v3-fixups](https://github.com/jeremander/beangulp/tree/v3-fixups) branch
Raw data
{
"_id": null,
"home_page": null,
"name": "garbanzo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "beancount, finance",
"author": null,
"author_email": "Jeremy Silver <jeremys@nessiness.com>, Zach Silver <zach.silver@gradientboostedinvestments.com>",
"download_url": "https://files.pythonhosted.org/packages/1a/a6/1685a4d5a4b0d496d4a36a4f218ec268818dc2209b3765b39b7538b10142/garbanzo-0.1.0.tar.gz",
"platform": null,
"description": "# Garbanzo\n\n[](https://pypi.org/project/garbanzo)\n\n\n[](https://raw.githubusercontent.com/jeremander/garbanzo/main/LICENSE)\n[](https://github.com/pre-commit/pre-commit)\n\nA collection of utilities related to the beancount (plaintext accounting) framework.\n\nEventually, some of the more public-facing utilities may be migrated to another library.\n\n## This Repository\n\n- `garbanzo/`: Main Python package for garbanzo\n- `hooks/`: pre-commit [hooks](#pre-commit-hooks)\n- `pyproject.toml`: config file for the `garbanzo` Python package, including the list of requirements\n - At present we are maintaining [forks](#forks-of-other-libraries) of some libraries which are not yet compatible with `beancount` v3. Eventually we hope to be able to use the standard versions.\n- `tests/`: Contains unit test modules.\n - `tests/examples/`: Contains example files for tests, etc.\n\n## Installing the Library\n\nTo install the `garbanzo` Python library, do `pip install .` (or `uv pip install .`) from the top-level directory.\n\n## Command-line Program\n\nInstalling the library will also install the `garbanzo` command-line program. To see the menu of subcommands, run `garbanzo --help`.\n\nNext we provide an overview of the different subcommands.\n\n### `dl-assistant`\n\nAssists in manually downloading data files from financial institutions and importing them into your beancount ledger.\n\n**Usage**: `garbanzo dl-assistant [ACCOUNTS_FILE] [DATA_DIR]`\n\nThis command takes advantage of two metadata fields on \"open\" directives:\n\n1. `url`: url to transaction download page\n2. `manual_edit`: `true` or `false`\n\nThe `url` field will tell `dl-assistant` what URL to open when handling the\naccount. If `manual_edit` is set to `true`, `dl-assistant` won't check for\ndownloads, and will instead prompt to open the transaction file to add\ntransactions manually.\n\n### `filter`\n\nApplies one or more filters to entries in a beancount ledger. A *filter* is a function that can either remove entries or (more commonly) modify their contents, e.g. to impose a set of \"rules\" for assigning narrations/accounts in a consistent way.\n\n**Usage**: `garbanzo filter [LEDGER_FILE] --json-filters [JSON_FILES] --inplace`\n\n- `LEDGER_FILE` is your top-level ledger file. This may have \"include\" statements to incorporate multiple beancount files, in which case the tool will normalize all included files.\n- `JSON_FILES` is a list of one or more paths to JSON files, each of which must contain a list of filters. See below for a description of the JSON schema for specifying filters.\n\nIt is generally preferable to use the `--inplace` flag, which will modify all of the files in-place. Otherwise, it will save copies of each file, applying a `.filt.beancount` suffix to each one.\n\nIn the future we plan to add more default filters, in addition to expanding the JSON filter schema.\n\n#### JSON Filter Schema\n\nYou can specify custom rules for modifying transactions via the `--json-filters` argument. See [`filters.json`](tests/examples/filters.json) for an example of a JSON filter file. It should consist of a list of JSON objects, each containing two keys, `match` and `set`. Each ledger entry will be checked on each filter's `match` condition, and if it matches, the `set` condition will be triggered, possibly modifying the entry. Entries that do not match will be left alone.\n\nAt present the JSON filters only apply to transactions, not other types of beancount entries.\n\nThe current schema is described below (but note that it is subject to change):\n\n- `match`: a JSON object with the following fields (all optional):\n - `narration` (string): [regular expression](https://docs.python.org/3/howto/regex.html#regex-howto) to match the narration\n - `payee` (string): regular expression to match the payee\n - `account_prefixes` (list of strings): account prefixes to match\n - Matches a transaction if for each prefix listed, some posting exists with that prefix.\n\n**NOTE**: Regular expressions only need to match a part of a string, and they match case-insensitively. For example, the regular expression `PIZZA` will match the string `Vincent's Pizza`.\n\n**NOTE**: If multiple fields are set, *all* of the criteria will have to be matched. There is currently no way to match on \"any\" instead of \"all,\" but in the future there may be.\n\n- `set`: a JSON object with the following fields (all optional):\n - `narration` (string): narration to set\n - `payee` (string): payee to set\n - `tags` (list of strings): tags to set\n - `links` (list of strings): links to set\n - `account` (string): account to set\n - Since transactions have multiple postings, this account will only be set for a unique posting matching this account type.\n - For example, if the value of `account` is `\"Expenses:Food:Restaurants\"`, then it will modify a posting whose account starts with `Expenses`, provided it is the only such posting.\n\n**NOTE**: If a field's value is set to `null`, the corresponding value of the beancount entry will be removed. In contrast, if a field is absent, the value will be left alone. (In other words, absent and `null`-valued do *not* mean the same thing.)\n\nAs an illustration of the JSON filter system, if you run the `filter` subcommand on [`transactions.beancount`](tests/examples/transactions.beancount) using [`filters.json`](tests/examples/filters.json), the result is [`transactions.filtered.beancount`](tests/examples/transactions.filtered.beancount).\n\n### `normalize`\n\nNormalizes a beancount ledger. Sorts entries, normalizes whitespace and currency alignment.\n\n**Usage**: `garbanzo normalize [LEDGER_FILE] --inplace`\n\nHere `LEDGER_FILE` is your top-level ledger file. This may have \"include\" statements to incorporate multiple beancount files, in which case the tool will normalize all included files.\n\nIt is generally preferable to use the `--inplace` flag, which will modify all of the files in-place. Otherwise, it will save copies of each file, applying a `.norm.beancount` suffix to each one.\n\n## Pre-commit Hooks\n\nThis repo provides [pre-commit](https://pre-commit.com/) hooks, defined in [.pre-commit-hooks.yaml](.pre-commit-hooks.yaml).\n\nCurrently there is one hook defined called `bean-check`, which you can install in your beancount ledger repository to validate the ledger before each commit.\n\nTo install it:\n\n1. Make sure you have the `pre-commit` tool installed (e.g. with `pip install pre-commit`).\n2. Create a `.pre-commit-config.yaml` file at the top level of your repository. It should be identical to the [example-pre-commit.yaml](hooks/example-pre-commit-config.yaml) file, except you should replace `\"my_ledger.beancount\"` with the path to your own ledger file. Then run `git add .pre-commit-config.yaml` to add it to your repo.\n3. Run `pre-commit install`.\n\nThe hook should now be installed in `.git/hooks/pre-commit`. It will run automatically whenever you make a commit (as long as at least one file has been updated). You can also do `pre-commit run` to run the hook without having to commit.\n\n## Links\n\n- [beancount](https://github.com/beancount/beancount): core library\n - Main [documentation](https://beancount.github.io/docs/)\n - Current version is [v3](https://beancount.github.io/docs/beancount_v3.html), still transitioning from v2.\n- [fava](https://github.com/beancount/fava): web front-end\n- [BeanHub](https://beanhub.io): enterprise-grade app built on beancount\n - Free tier only allows 1,000 entries in personal repo.\n- [lazy-beancount](https://github.com/Evernight/lazy-beancount): batteries-included system (web interface, extra plugins)\n- [beancount-lazy-plugins](https://github.com/Evernight/beancount-lazy-plugins): plugins for beancount, most notably:\n - `valuation`: track total value of the opaque fund over time\n - `filter_map`: apply operations to group of transactions selected by Fava filters\n\n### Auto-importing\n\n- [SimpleFin](https://www.simplefin.org): open-source interchange language for financial transactions\n- [Plaid](https://plaid.com): popular enterprise financial API\n- [beanhub-import](/blog/2024/05/27/introduction-of-beanhub-import/): one small step closer to fully automating transaction importing ([Github repo](https://github.com/LaunchPlatform/beanhub-import))\n\n### Forks of other libraries\n\n- [beancount-import](https://github.com/jeremander/beancount-import): Import entries from raw data files.\n - [v3-compat](https://github.com/jeremander/beancount-import/tree/v3-compat) branch\n- [beangulp](https://github.com/jeremander/beangulp): New importer framework\n - [v3-fixups](https://github.com/jeremander/beangulp/tree/v3-fixups) branch\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 Jeremy Silver and Zach Silver\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A collection of utilities related to the beancount (plaintext accounting) framework.",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/jeremander/garbanzo#readme",
"Issues": "https://github.com/jeremander/garbanzo/issues",
"Source": "https://github.com/jeremander/garbanzo"
},
"split_keywords": [
"beancount",
" finance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0067d7959d4bec103804a064c64e860efd3be5b4a73e5d67ff1374847a7601da",
"md5": "82050206301317c9aae83ca9fc9478d2",
"sha256": "987cec18be14900256e0e569f21bbf58be0343513ee4087aeca14095dcb12335"
},
"downloads": -1,
"filename": "garbanzo-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "82050206301317c9aae83ca9fc9478d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 21032,
"upload_time": "2025-01-10T23:04:29",
"upload_time_iso_8601": "2025-01-10T23:04:29.240448Z",
"url": "https://files.pythonhosted.org/packages/00/67/d7959d4bec103804a064c64e860efd3be5b4a73e5d67ff1374847a7601da/garbanzo-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1aa61685a4d5a4b0d496d4a36a4f218ec268818dc2209b3765b39b7538b10142",
"md5": "6db7723d7f4356434e2bb327c9b31cf1",
"sha256": "58f1a6de976c6fd9f3e017b64697f2d511195eb86d70cca0fd9139135b0280e1"
},
"downloads": -1,
"filename": "garbanzo-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6db7723d7f4356434e2bb327c9b31cf1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 20798,
"upload_time": "2025-01-10T23:04:30",
"upload_time_iso_8601": "2025-01-10T23:04:30.571081Z",
"url": "https://files.pythonhosted.org/packages/1a/a6/1685a4d5a4b0d496d4a36a4f218ec268818dc2209b3765b39b7538b10142/garbanzo-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-10 23:04:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeremander",
"github_project": "garbanzo#readme",
"github_not_found": true,
"lcname": "garbanzo"
}
