# MiniBudget
[](https://www.gnu.org/licenses/agpl-3.0)
MiniBudget is a tool designed to enable personal and small business
budgeting using a plaintext format. It's inspired by [beancount](https://github.com/beancount/beancount) and [plainbudget](https://github.com/galvez/plainbudget).
I wrote the MVP in an evening because:
1. Beancount doesn't have a budgeting feature
2. Google Sheets seemed far too complex and inefficient for such a simple set of operations
## Quickstart
### Install with pipx
This is the recommended way to use minibudget. First [install pipx](https://pipx.pypa.io/stable/installation/) if you
don't already have it.
Then install. It's best to install the version with `[convert]` extras.
```sh
pipx install "minibudget[convert]" --pip-args "'--pre'"
```
You should be able to run `minibudget` from the command line like other CLI tools:
```sh
wget https://raw.githubusercontent.com/fdavies93/minibudget/refs/heads/main/budgets/example.budget
minibudget report example.budget
```
### Run from Source
Clone the repo. [Poetry](https://python-poetry.org/) is the easiest way to run it.
```sh
poetry run minibudget report budgets/example.budget
```
Now take a look at `example.budget` to learn more about it.
If you want to use the convert feature then use `poetry install -E convert` to
get the required packages.
## Documentation
- [budget format](docs/budget-format.md)
- [`minibudget report`](docs/report.md)
- [`minibudget diff`](docs/diff.md)
- [`minibudget convert`](docs/convert.md)
- [`minibudget chart`](docs/chart.md)
- [currency formats](docs/currency-formats.md)
## Possible Features
Since this is a deliberately simple tool, the preferred way to implement these
is as command line options which generate different types of output. A proper
TUI in curses or similar would make this into a finance tool from the 80s,
which is probably redundant versus a web app.
**Pull requests welcome. I may or may not implement these myself when I feel
like it.**
### Budget Format / Parsing
- [ ] Attach notes to budget categories; view them by using a flag
- [ ] Comment syntax
- [ ] Metadata for specifying period the budget covers, default currency, etc.
- [ ] Budget assertions for explicit and implicit categories
- [ ] Allow negative income and positive expenses accounts for edge cases
in business & financial records.
- [ ] Add a formatting mode.
- [ ] Write a treesitter grammar for neovim etc.
### Data Handling
- [ ] Make treatment of numbers / currency consistent
- [ ] Use Decimal / bespoke money handler consistently for currency
- [ ] Write consistent currency formatter class or interface; build
in concept of 'normal' decimalisation (e.g. USD has 2, NTD has 0).
- [ ] Proper multi-currency support
- [ ] Add more canned currency formats
- [ ] Implement non-regression and unit testing
### Conversion from other formats
- [ ] Convert ledger records to minibudget format
- [ ] Convert csvs to minibudget format
- [ ] Convert JSON output format back into
### Outputs / rendering
- [ ] CSV output for `report`
- [ ] JSON output for `diff`
- [ ] JSON output for `report`
- [ ] Make formatting and report structure customizable
- [ ] Stacked bar chart for income and expenses over time (visualising `diff`)
- [ ] Sunburst chart for income reports, for people with many income streams
## Completed Features
- [x] Switch to Calendar Versioning (likely YYYY-MM-R or YYYY-MM-DD)
- [x] Sunburst chart for expenses reports
- [x] CSV output for `diff`
- [x] Cool formatting for CLI
- [x] Integrate with beancount via bean-query to import real spending
- [x] Totals for budget categories, not just the top level income / expenses / unassigned
Raw data
{
"_id": null,
"home_page": "https://github.com/fdavies93/minibudget",
"name": "minibudget",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "minibudget, plaintext, plaintext-accounting, cli",
"author": "Frank Davies",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cd/a6/3c01b7266de41a003abc1f544687aab66ea28cfbec74c8502be660f82a63/minibudget-2024.11.4.tar.gz",
"platform": null,
"description": "# MiniBudget\n\n[](https://www.gnu.org/licenses/agpl-3.0)\n\nMiniBudget is a tool designed to enable personal and small business\nbudgeting using a plaintext format. It's inspired by [beancount](https://github.com/beancount/beancount) and [plainbudget](https://github.com/galvez/plainbudget).\n\nI wrote the MVP in an evening because:\n\n1. Beancount doesn't have a budgeting feature\n2. Google Sheets seemed far too complex and inefficient for such a simple set of operations\n\n## Quickstart\n\n### Install with pipx\n\nThis is the recommended way to use minibudget. First [install pipx](https://pipx.pypa.io/stable/installation/) if you\ndon't already have it.\n\nThen install. It's best to install the version with `[convert]` extras.\n\n```sh\npipx install \"minibudget[convert]\" --pip-args \"'--pre'\"\n```\n\nYou should be able to run `minibudget` from the command line like other CLI tools:\n\n```sh\nwget https://raw.githubusercontent.com/fdavies93/minibudget/refs/heads/main/budgets/example.budget\nminibudget report example.budget\n```\n\n### Run from Source\n\nClone the repo. [Poetry](https://python-poetry.org/) is the easiest way to run it.\n\n```sh\npoetry run minibudget report budgets/example.budget\n```\n\nNow take a look at `example.budget` to learn more about it.\n\nIf you want to use the convert feature then use `poetry install -E convert` to \nget the required packages.\n\n## Documentation\n\n- [budget format](docs/budget-format.md) \n- [`minibudget report`](docs/report.md)\n- [`minibudget diff`](docs/diff.md)\n- [`minibudget convert`](docs/convert.md)\n- [`minibudget chart`](docs/chart.md)\n- [currency formats](docs/currency-formats.md)\n\n## Possible Features\n\nSince this is a deliberately simple tool, the preferred way to implement these \nis as command line options which generate different types of output. A proper \nTUI in curses or similar would make this into a finance tool from the 80s, \nwhich is probably redundant versus a web app.\n\n**Pull requests welcome. I may or may not implement these myself when I feel \nlike it.**\n\n### Budget Format / Parsing\n\n- [ ] Attach notes to budget categories; view them by using a flag\n- [ ] Comment syntax\n- [ ] Metadata for specifying period the budget covers, default currency, etc. \n- [ ] Budget assertions for explicit and implicit categories\n- [ ] Allow negative income and positive expenses accounts for edge cases\n in business & financial records.\n- [ ] Add a formatting mode.\n- [ ] Write a treesitter grammar for neovim etc.\n\n### Data Handling\n\n- [ ] Make treatment of numbers / currency consistent\n - [ ] Use Decimal / bespoke money handler consistently for currency\n - [ ] Write consistent currency formatter class or interface; build\n in concept of 'normal' decimalisation (e.g. USD has 2, NTD has 0).\n- [ ] Proper multi-currency support\n- [ ] Add more canned currency formats\n- [ ] Implement non-regression and unit testing\n\n### Conversion from other formats\n\n- [ ] Convert ledger records to minibudget format\n- [ ] Convert csvs to minibudget format\n- [ ] Convert JSON output format back into \n\n### Outputs / rendering\n\n- [ ] CSV output for `report`\n- [ ] JSON output for `diff`\n- [ ] JSON output for `report`\n- [ ] Make formatting and report structure customizable\n- [ ] Stacked bar chart for income and expenses over time (visualising `diff`)\n- [ ] Sunburst chart for income reports, for people with many income streams\n\n## Completed Features\n\n- [x] Switch to Calendar Versioning (likely YYYY-MM-R or YYYY-MM-DD)\n- [x] Sunburst chart for expenses reports\n- [x] CSV output for `diff`\n- [x] Cool formatting for CLI\n- [x] Integrate with beancount via bean-query to import real spending\n- [x] Totals for budget categories, not just the top level income / expenses / unassigned\n\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "A simple CLI tool for personal and small business budgeting.",
"version": "2024.11.4",
"project_urls": {
"Homepage": "https://github.com/fdavies93/minibudget",
"Repository": "https://github.com/fdavies93/minibudget"
},
"split_keywords": [
"minibudget",
" plaintext",
" plaintext-accounting",
" cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ac0b617a7c7e4d633ee371ad743b67a6fc36278f3d2ddfcf10b0060878fd4dbc",
"md5": "ed79b2301a26627d2e68f223337c42bb",
"sha256": "460db2e688492fe66036718ebcbf87b016b2aca8f2022dd937d0e957a67d5bbf"
},
"downloads": -1,
"filename": "minibudget-2024.11.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ed79b2301a26627d2e68f223337c42bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 12240,
"upload_time": "2024-11-10T04:40:03",
"upload_time_iso_8601": "2024-11-10T04:40:03.187460Z",
"url": "https://files.pythonhosted.org/packages/ac/0b/617a7c7e4d633ee371ad743b67a6fc36278f3d2ddfcf10b0060878fd4dbc/minibudget-2024.11.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cda63c01b7266de41a003abc1f544687aab66ea28cfbec74c8502be660f82a63",
"md5": "372a5cd6a6f4ae788d08f41416a0f24e",
"sha256": "8794371711f9d632b42db42ec553221e7f5e4ac58299d99db9c3750c77b217b5"
},
"downloads": -1,
"filename": "minibudget-2024.11.4.tar.gz",
"has_sig": false,
"md5_digest": "372a5cd6a6f4ae788d08f41416a0f24e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 11097,
"upload_time": "2024-11-10T04:40:05",
"upload_time_iso_8601": "2024-11-10T04:40:05.286772Z",
"url": "https://files.pythonhosted.org/packages/cd/a6/3c01b7266de41a003abc1f544687aab66ea28cfbec74c8502be660f82a63/minibudget-2024.11.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-10 04:40:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fdavies93",
"github_project": "minibudget",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "minibudget"
}
JSON
