Budget report for beancount files
Project description
Budget Report for Beancount Ledgers
1. Introcudtion
If you use the text-based ledger system ie beancount, and feel the need for a tools to track your expenses against your budget, then this tool may be what you need.
budget_report
is a simple tool to read beancount ledger files as input and generate simple budget report based on the budget entries within the input beancount file.
2. Installation
The simplest way to install and use budget_report
is via pip:
pip install budget_report
, for installing globally
or
pip install budget_report --user
, if you want to install for local user
or
pip install --user --no-cache-dir
, if you get error during installation saying something like ERROR: Failed building wheel for budget-report
.
3. How-To Use
Using budget_report
with your beancount files is a two step process:
- Specify your budget in the beancount files,
- Specifying the transactions to include in a particular budger and
- Generate budget report using
budget-report
script provided by this package.
3.1 Specifying Budget in beancount files
You specify your budget by entering a sequenct of beancount custom
directives in the following format:
<Date> custom "budget" <Account> <Amount> <Currency>
Where:
- Date is in the formate YYYY-MM-DD,
- Account is the name of the account you want to specify budget followed by 2 or more spaces,
- Amount is a number specifying the budget amount allocated for this account,
- Currency is the currency in which budget is specified.
Here is an example budget:
2021-12-06 custom "budget" Liabilities:CreditCard 10000 RS
2021-12-06 custom "budget" Expenses:Car:Fuel 5000 RS
2021-12-06 custom "budget" Expenses:Clothing 10000 RS
2021-12-06 custom "budget" Expenses:Education:Fees 11000 RS
2021-12-06 custom "budget" Expenses:Food:DiningOut 3000 RS
2021-12-06 custom "budget" Expenses:Groceries 50000 RS
2021-12-06 custom "budget" Expenses:Medicine 2000 RS
2021-12-06 custom "budget" Expenses:PocketMoney 10000 RS
Please note that:
a. Any budgets entries in the beancount file would override any previously specified entries for the same account.
b. The budget entries could also be put into a separate file such as mybudget.bean
and included into your main ledger file as below:
include "mybudget.bean"
3.2 Specifying Transaction to include in budget
There are two ways you can tell budget-report
which transactions to include while computing budget report:
a. Using budget name tags in your beancount ledger, and specifying the same tag at budget-report
command line, or
b. Giving start date as command line argument.
3.2.1 Using Budget Tags
Tags can be used in your beancount ledger to specify transactions to include in a particular budget report. The easiest way to use beancount pushtag
and poptag
directive as below. However, individullay tagging each transaction with a tag should also work.
pushtag #Budget-Dec21 ; or any tag you want to use to name your budget!
....
<< transactions go here! >>
....
poptag #Budget-Dec21
Later, you can specify the same tag at budget-report
command line using -t
or --tag
option, while generating budget report.
Note: If budget-report
encounters a posting in the ledger with the budget tag, it is included into the bugetted postings regardless of the existence a corresponding budget
directive. If no corresponding budget
directive entry is found, an entry for the posting account with zero budget value is automatically added for this purpose.
3.2.2 Using start and end dates
Another way to tell budget-report
which ledger entries to include in budget calculation, is to give it a start date (-s
or --start-date
command line option) and/or an end date (-e
or --end-date
command line option). budget-report
will include all transactions in the ledger falling at or after the given start date and at or before the given end date.
Note: Both the tag and start/end dates could be given together to fine tune the filtering, if that makes sense in your case.
3.3 Generating Budget report
After you have added the budget entries in your beancount file, you can generate the budget report by calling the budget-report
script provided by this package from your shell console as below:
$ budget-report -t Budget-Dec21 /path/to/your/beancount_file.bean
, or
$ budget-report -s 2021-12-01 -e 2021-12-31 /path/to/your/beancount_file.bean
It would generate output similar to that shown below:
Account Budget Expense (%) Remaining (%)
----------------------- -------- --------- ----- ----------- -----
Liabilities:CreditCard 10000.0 5000.0 50.0 5000.0 50.0
Expenses:Car:Fuel 5000.0 1000.0 20.0 4000.0 80.0
Expenses:Clothing 10000.0 5000.0 50.0 5000.0 50.0
Expenses:Education:Fees 11000.0 5000.0 45.5 6000.0 54.5
Expenses:Food:DiningOut 10000.0 3000.0 30.0 7000.0 70.0
Expenses:Gardening 0.0 2000.0 -2000.0
Expenses:Groceries 50000.0 10800.0 21.6 39200.0 78.4
Expenses:Medicine 2000.0 1000.0 50.0 1000.0 50.0
Expenses:PocketMoney 10000.0 6000.0 60.0 4000.0 40.0
Totals 108000.0 38800.0 35.9 69200.0 64.1
Notes:
a. If end data is omitted, all entries in the ledger at/after the start date would be included in the computation.
b. If start date is omitted, and only end date is given, all entries at/before the end date would be included.
c. If both tag and start/end dates are given, bothe will be used to filter the entries in the ledger.
Help at Command Line
You can get help about all budget-report
options at the command line using the -h switch.
$ budget-report -h
usage: budget-report [-h] [-v] [-t TAG] [-s START_DATE] [-e END_DATE] filename
Budget report for beancount files
positional arguments:
filename Name of beancount file to process
optional arguments:
-h, --help show this help message and exit
-v, --version Print version number and exit
-t TAG, --tag TAG Budget tag to use
-s START_DATE, --start-date START_DATE
Budget start date
-e END_DATE, --end-date END_DATE
Budget end date
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for budget_report-0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9354be164829440fdae8d1c71e4c3a8bfce11d684aa3ced61ddd374a9c3b892e |
|
MD5 | a3d27ed4c51907ed05991c50ed0ce3bc |
|
BLAKE2b-256 | 24b28f21bce875d603fd3779916d4f30919ebc39219d9f0e31a13c098b41fcdf |