polarmutex/fava-envelope

A beancount fava extension to add a envelope budgeting capability

Projects I created

• beancount-language-server (⭐ 128) - A Language Server Protocol (LSP) for beancount files
• fava-envelope (⭐ 96) - A beancount fava extension to add a envelope budgeting capability
• tree-sitter-beancount (⭐ 25) - a tree-sitter parser for the beancount syntax
• git-worktree.nvim (⭐ 20) - None
• beancount.nvim (⭐ 7) - neovim plugin to help with beancount files
• nix-config (⭐ 6) - nix dotfiles for nixos and userspace
• neovim-flake (⭐ 4) - my neovim config as a nix flake
• awesome-flake (⭐ 1) - my awesome wm config as a nixos flake

Projects I help maintain

• nixpkgs (⭐ 15652) - Nix Packages collection & NixOS

Statistics	Languages
Repositories 45 Gists 1 Stargazers 334 Forks 43 Contributed to 5 Commits 2292 Issues 110 Pull requests 511 Followers 37 Following 23	Lua 27.99% Jupyter Notebook 24.06% Rust 19.82% Python 9.75% Nix 6.82% Shell 4.1% CSS 2.25% C 1.55% JavaScript 0.86% TypeScript 0.85%

_{Last updated: 2024-04-24 14:35:32 UTC}

fava-envelope's Issues

Color accentuation of negative and positive values

When overspending or having budget over it could be colored in red or green for a clearer overview.

Add Info about currency to README

Tell the default_currency is USD

will look for option "operating_currency" to set otherwise

When time filter is selected, fava-envelope will not work

I selected 2021 in the time filter box, fava-envelope will not work. following is the screen shot

The exception is:
File "/home/jason/miniconda3/lib/python3.9/site-packages/fava_envelope/modules/beancount_envelope.py", line 48, in init
self.date_start = datetime.datetime.strptime(self.start_date, '%Y-%m').date()
TypeError: strptime() argument 1 must be str, not None

Multi-currency budgeting

To sum things up, I live and work in a country and my immediate family lives in another country, with a different currency, so I need to be able to budget in multiple currencies, so I've tweaked the code for my personal use, creating options allowing to have multiple budgets over multiple currencies.
This is probably not on the project roadmap for now, but just in case, would you be interested in me sharing my code?

Assumes USD

fava-envelope assumes USD in a number of places, including

                if posting.units.currency != "USD":
                    continue

It would be good to look at operating currencies instead.

Python 3.9 Upgrade Broke Plugin (FreeBSD 13.1)

What Happened

I upgraded my python version to the latest supported release for FreeBSD. The webpage is now showing just pure HTML and not rendering properly on any device.

How to reproduce

1. Upgrade the python port to latest release
2. Remove the virtual env directory
3. Run virtualenv env; . env/bin/activate
4. pip install git+https://github.com/polarmutex/fava-envelope.git
5. Start fava

Extra Details

I was perusing my stdout logs and noticed that this keeps appearing when restarting Fava:

Jul 8 03:08:32 budget fava[79407]: Error in atexit._run_exitfuncs: Jul 8 03:08:32 budget fava[79407]: Traceback (most recent call last): Jul 8 03:08:32 budget fava[79407]: File "/usr/home/fava/env/lib/python3.9/site-packages/beancount/query/shell.py", line 63, in save_history Jul 8 03:08:32 budget fava[79407]: readline.write_history_file(filename) Jul 8 03:08:32 budget fava[79407]: PermissionError: [Errno 13] Permission denied

It only started recently

Changes to front end in Fava 1.25 break fava-envelope

Fava-envelope 0.5.6 installed with Fava 1.24.4 working correctly.

Upgrade fava to 1.25, and Envelope Budget main screen fails to load.
Likely due to changes in front-end.

Error from Fava is generic.
Error from systemctl:

Jul 19 09:17:17 fava fava[4809]:     return _cached_url_for(endpoint, **values)
Jul 19 09:17:17 fava fava[4809]:   File "/usr/local/lib/python3.10/dist-packages/flask/helpers.py", line 256, in url_for
Jul 19 09:17:17 fava fava[4809]:     return current_app.url_for(
Jul 19 09:17:17 fava fava[4809]:   File "/usr/local/lib/python3.10/dist-packages/flask/app.py", line 2031, in url_for
Jul 19 09:17:17 fava fava[4809]:     return self.handle_url_build_error(error, endpoint, values)
Jul 19 09:17:17 fava fava[4809]:   File "/usr/local/lib/python3.10/dist-packages/flask/app.py", line 2020, in url_for
Jul 19 09:17:17 fava fava[4809]:     rv = url_adapter.build(  # type: ignore[union-attr]
Jul 19 09:17:17 fava fava[4809]:   File "/usr/local/lib/python3.10/dist-packages/werkzeug/routing/map.py", line 917, in build
Jul 19 09:17:17 fava fava[4809]:     raise BuildError(endpoint, values, method, self)
Jul 19 09:17:17 fava fava[4809]: werkzeug.routing.exceptions.BuildError: Could not build url for endpoint 'extension_report' with values ['bfile', 'currency', 'month', 'report_name']. Did you forget to specify values ['extension_name']?

Income vs Expenses for budget accounts

Need paycheck to paycheck envelope budgeting, not month to month

So I've used envelope budgeting a lot and last time I used it was with Ledger cli.

I've played a bit with fava-envelope now and feel that there is a big limitation to this projects approach vs. the intention of envelope budgeting.

The way I've always understood envelope budgeting (and thus how I've used it) is:

1. I receive money; Source don't matter, date don't really matter either.
2. That money immediatly gets divided into their respective envelopes.
3. Expenses come out of envelopes.

The problem with Fava for me is that fava assumes that you get paid beginning of the month, and calculates budget for the month. I always get paid between 25 to 27th of every month. And I immediately divide up my income to envelopes after I get paid. The problem here is that Fava counts that Income as The income for the month, and Expenses made at the beginning of the month get's removed from the budget. This makes things very awkward.

In addition to this there are times where I would get paid back a Directors Loan or shares, which can happen at different times in a month as well, and right after receiving that money, I want to divide it up into it's containers.

It doesn't feel like Fava is flexible enough to handle this use case at the moment. Am I missing something?

Support fava v1.19

I'm testing this out, but all I get is a display showing lists of object types:

Example beancount file below:

option "title" "Budget Testing Ledger"
option "operating_currency" "GBP"

2000-01-01 custom "fava-extension" "fava_envelope" "{}"

2020-08-01 custom "envelope" "start date" "2020-08"
2020-08-01 custom "envelope" "budget account" "Assets:GBP"

2000-01-01 open Equity:Opening-Balances
2000-01-01 open Assets:GBP:Current
2020-01-01 open Expenses:Learning                               GBP


2020-08-14 pad Assets:GBP:Current Equity:Opening-Balances
2020-08-15 balance Assets:GBP:Current 1000.0 GBP
2020-08-16 custom "envelope" "allocate" "Expenses:Learning" 100.00


2020-08-20 * "Lesson"
  Assets:GBP:Current    -20.00 GBP
  Expenses:Learning     20.00 GBP

Transfer the budget between different categories

Thank you for the great plugin.
Is there a way to transfer the budget between different categories?

For example: in April, I have the 500.00 budget left in Expenses:Foods
In May, I plan to use this budget to take a course, is it possible to transfer this 500 from Expenses:Foods to Expenses:Course without allocating the new budget?

Negative Rollover option -- incorrect budget amount

When using the negative rollover option, it carries over the overspent amount in the available-to-budget calculation, but it should ignore that amount instead.

Example with current code:

January

Name	Amount
Funds for month	100
Overspent in prev month
Budgeted for month	-100
To be budgeted for month
Budgeted in the future

Category	Budgeted	Spent	Available
Food	50	-55	-5
Rent	50	-50

February

Name	Amount
Funds for month	100
Overspent in prev month	-5
Budgeted for month	-100
To be budgeted for month	-5
Budgeted in the future

Category	Budgeted	Spent	Available
Food	50	-50	-5
Rent	50	-50

Notice that the total amount available for the two months was 200, and 200 was budgeted, but the system says you have over-budgeted by 5.

Instead, it should look like this when negative rollover is used:

February

Name	Amount
Funds for month	100
Overspent in prev month
Budgeted for month	-100
To be budgeted for month
Budgeted in the future

Category	Budgeted	Spent	Available
Food	50	-50	-5
Rent	50	-50

Since the overspent amount from the previous month is left on the accounts as a negative available amount, we can't deduct that from the available amount to budget.

budget category transactions

add the ability to click a budget category experiences and see list of transactions

Better Error Reporting

Errors are difficult to troubleshoot. If there is any error in fava-envelope, fava reports "Loading http://localhost:5000/example-file/extension/EnvelopeBudget/ failed." I don't know enough about fava, but is it possible to pipe errors from plugins into fava's error page?

WIP: Testing Framework

The next thing I want to add is a test framework to help keep the plugin in good shape and correct. This post will contain test conditions that we need, feel free to suggest others

List of tests:
[ ] - months with no income

Pandas not installed by default

I just ran a release upgrade on the VM that fava is running on and had to reinstall my third-party plugins.

Fava-envelope was refusing load.
I tried running fava_envelope/main.py manually, and it errored out with a missing dependency for pandas.

pip install pandas

This causes pandas (and numpy) to install. Restarting fava has now cleared the error, and envelopes are back.

Extension url not loading

I installed globally using sudo pip3 install fava-envelope. Fava is also installed globally. The extension link shows up in Fava, but clicking it produces a 404. I tried running fava in debug mode, but got no further log messages.

"GET /<...>/extension/EnvelopeBudget/ HTTP/1.1" 404 -

I am using Python 3.8 on Ubuntu 20.04.

Not accessing Expenses

Hello,
I'm onboarding for the first time into this extension. I have the tab working, and copy pasted your example lines into my accounts.beancount file (also tried transactions.beancount if it matters). For both, while the 100 dollars allocated to Expenses:Food seems to be appearing, the extension does not seem to be accessing what I have spent on food for the month setup, or any month.

Any Suggestions?

fix python publish github action

Internal Server Error 500 when clicking on "Envelope Budget" in navigation bar

Receive the following error:

Exception on /beancount/extension/EnvelopeBudget/ [GET]
Traceback (most recent call last):
File "/home/glenn/finances/venv/lib/python3.8/site-packages/flask/app.py", line 2073, in wsgi_app
response = self.full_dispatch_request()
File "/home/glenn/finances/venv/lib/python3.8/site-packages/flask/app.py", line 1518, in full_dispatch_request
rv = self.handle_user_exception(e)
File "/home/glenn/finances/venv/lib/python3.8/site-packages/flask/app.py", line 1516, in full_dispatch_request
rv = self.dispatch_request()
File "/home/glenn/finances/venv/lib/python3.8/site-packages/flask/app.py", line 1502, in dispatch_request
return self.ensure_sync(self.view_functions[rule.endpoint])(**req.view_args)
File "/home/glenn/finances/venv/lib/python3.8/site-packages/fava/application.py", line 352, in extension_report
content = render_template_string(template, extension=extension)
File "/home/glenn/finances/venv/lib/python3.8/site-packages/flask/templating.py", line 165, in render_template_string
return _render(ctx.app.jinja_env.from_string(source), context, ctx.app)
File "/home/glenn/finances/venv/lib/python3.8/site-packages/flask/templating.py", line 128, in _render
rv = template.render(context)
File "/home/glenn/finances/venv/lib/python3.8/site-packages/jinja2/environment.py", line 1291, in render
self.environment.handle_exception()
File "/home/glenn/finances/venv/lib/python3.8/site-packages/jinja2/environment.py", line 925, in handle_exception
raise rewrite_traceback_stack(source=source)
File "", line 25, in top-level template code
File "/home/glenn/finances/venv/lib/python3.8/site-packages/jinja2/utils.py", line 84, in from_obj
if hasattr(obj, "jinja_pass_arg"):
jinja2.exceptions.UndefinedError: 'url_for_current' is undefined

Not calculating opening balance with Equity for budget.

I was expecting "Funds for month" to equal Assets-(Budgeted+Liabilities) but it seems to only check cash flow from income.
In the below example, I was expecting "Funds for month" to be 1000.00(Checking)+500.00(Saving)-250.00(Credit Card)+50.00(Income)+25.00(Transfer from non-budget asset) = 1325.00

Instead it only shows 50(Income), it shows 1250.00 in a "Equity:Opening-Balances" envelope, and I have no idea where the 25(Transfer from non-budget asset) went.

example.beancount.txt

Importing module "fava_envelope" failed.

Got this error. (fava version == 1.23)

ValueError: unconverted data remains: -01

I have installed this as per #64, and used bean-example >example.beancount, and then added this to example.beancount as per the README:

2000-01-01 custom "fava-extension" "fava_envelope" "{}"
2010-01-01 custom "envelope" "start date" "2020-01-01"
2020-01-01 custom "envelope" "budget account" "Assets:Checking"

but when starting fava example.beancount the follow error occurred when clicking on "Envelope Budget":

Exception on /example-beancount-file/extension/EnvelopeBudget/ [GET]
Traceback (most recent call last):
  File "/home/vorburger/.local/lib/python3.11/site-packages/flask/app.py", line 2525, in wsgi_app
    response = self.full_dispatch_request()
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vorburger/.local/lib/python3.11/site-packages/flask/app.py", line 1822, in full_dispatch_request
    rv = self.handle_user_exception(e)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vorburger/.local/lib/python3.11/site-packages/flask/app.py", line 1820, in full_dispatch_request
    rv = self.dispatch_request()
         ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vorburger/.local/lib/python3.11/site-packages/flask/app.py", line 1796, in dispatch_request
    return self.ensure_sync(self.view_functions[rule.endpoint])(**view_args)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vorburger/.local/lib/python3.11/site-packages/fava/application.py", line 360, in extension_report
    content = Markup(render_template_string(template, extension=extension))
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vorburger/.local/lib/python3.11/site-packages/flask/templating.py", line 159, in render_template_string
    return _render(app, template, context)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vorburger/.local/lib/python3.11/site-packages/flask/templating.py", line 130, in _render
    rv = template.render(context)
         ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vorburger/.local/lib/python3.11/site-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "/home/vorburger/.local/lib/python3.11/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "<template>", line 11, in top-level template code
  File "/home/vorburger/.local/lib/python3.11/site-packages/fava_envelope/__init__.py", line 30, in get_budgets_months_available
    self.generate_budget_df(currency)
  File "/home/vorburger/.local/lib/python3.11/site-packages/fava_envelope/__init__.py", line 20, in generate_budget_df
    module = BeancountEnvelope(
             ^^^^^^^^^^^^^^^^^^
  File "/home/vorburger/.local/lib/python3.11/site-packages/fava_envelope/modules/beancount_envelope.py", line 54, in __init__
    self.date_start = datetime.datetime.strptime(
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib64/python3.11/_strptime.py", line 568, in _strptime_datetime
    tt, fraction, gmtoff_fraction = _strptime(data_string, format)
                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib64/python3.11/_strptime.py", line 352, in _strptime
    raise ValueError("unconverted data remains: %s" %
ValueError: unconverted data remains: -01

Failing with Fava 1.23

Deprecated FavaLegder.entries was removed in Fava 1.23 and fava-envelope uses it:

...
  File "/home/mmoya/.cache/pypoetry/virtualenvs/mmoya-ledger-YHEMojRP-py3.10/lib/python3.10/site-packages/fava_envelope/__init__.py", line 26, in get_budgets_months_available
    self.generate_budget_df(currency)
  File "/home/mmoya/.cache/pypoetry/virtualenvs/mmoya-ledger-YHEMojRP-py3.10/lib/python3.10/site-packages/fava_envelope/__init__.py", line 19, in generate_budget_df
    self.ledger.entries,
AttributeError: 'FavaLedger' object has no attribute 'entries'

downgrading Fava back to 1.22.3 fix the issue.

Example Beancount file with usage pattern

After reading the Beancount mailing list, the Fava Issues post, and this post about envelope budgeting for ledger I gather there are many opinions on how envelope budgeting should be done on top of a double-entry bookkeeping system.

@bryall, in order to understand your vision for this extension and its correct usage it would be very helpful to have a basic example Beancount journal with some transactions in it, and perhaps a few screenshots with some brief commentary.

Latest version of pandas results in empty 'Available' column

Hi.
I noticed that 'available' column on the 'envelope budget' page is completely empty when I use pandas==2.0.0 and above. Seems like some incompatible changes were made when v2 got released. For now I was able to get it to work by pinning pandas to the latest v1 version

pip install --upgrade beancount fava fava-envelope pandas==1.5.3

I'm using Python 3.11.3 on Arch. I will try to take a look, but I suck at pandas (and python overall)

Repeating Allocations

Would be easier if money could be allocated to an envelope once and then have fava-envelope assume that the allocations are the same each month, until the allocations are updated.

Loading Envelope failed

When trying to setup fava-envelope, I recieve the following error message:

fava_envelope/modules/beancount_envelope.py", line 136, in envelope_tables
    self.income_df.loc["Overspent", prev_month] + \
TypeError: unsupported operand type(s) for +: 'float' and 'decimal.Decimal'

Allow roll over negative balances

I know it breaks "YNAB" style budgeting rules as Im essentially budgeting money I don't have yet , but is there a way to allow a negative balance to roll over? I often have to buy things for work that get reimbursed later, so I let that specific bucket sit negative for a week or two until I get the reimbursement. That works fine until the payment and reimbursement fall in different calendar months. Then the amount is pulled out of the "To be budgeted for month" field. I can work around it for now by budgeting -XXX USD at the start of the month, but that throws the "Budgeted for month" field off.

That or have a way leave to a bucket out of the budget completely, as this account has truly no affect on the budget.

404 for "Envelope budget" link in Fava sidebar

Not sure if this is a bug or a newbie mistake by me (only migrated from ledger to beancount this week)

When I click "Envelop Budger" in the sidebar, I get a red error message pop up because of parsing error. This is because the response is a 404.

Am I missing something else that needs installed, configured or some invalid path, or could this be a legit bug?

EDIT: I removed the previous traceback since that was related to another error. I still cannot access the page however.

remove repeating line in example.beancount

doesn't appear to do anything with the current code, so it shouldn't be in the example.beancount

Originally posted by @egetzner in #27 (comment)

Importing module "fava_envelope" failed error

Hello, I have been using fava-envelope v0.5.4 for 3-4 months now. I upgraded to v0.5.5 on my terminal while an instance of fava was accidentally running. Since then it throws an error that it can't load fava_envelope module even if I downgrade to v0.5.4. I'm not sure what broke and I don't know how to debug this. It's more a help plea than an issue. Sorry about that!

Funds for month starting balance?

Is there a way to input a starting balance for the available funds? For instance, input a negative input balance, so I can have a "clean" starting point for a budget without having to physically empty out the budget accounts.