README.rst

Budget Envelopes

This python package is an implementation of the envelope budget system.

In other words, when supplied with target budgets (envelope start balances) and categorised transactions (money drawn from envelopes), this software can be run via cli, to calculate what the envelope balances are taking into account the expenses and the set budgets.

Installation

Disclaimer: This library has been written to meet personal needs and is thoroughly not tested. In any case of interest, I am glad to assist, improve documentation and accept pull requests.

Via poetry: poetry install

Via pip: pip install

Features

Done:

• Reads transactions from file in custom formats (see CLI options: budget-envelopes --help)

  • Example JSON-transactions & example csv-transactions. See examples/

• Reads budgets from file in specific format (see example file examples/envelope_budget.csv)

  • Supply budgets indicating the budgeting period as

    • month: m
    • quarter: q
    • half-year: h
    • year: y

• Adjustments: One-off adjustments and transfer between envelopes (see example file examples/envelope_adjustments.csv)

  • Adjust a budget for a single month

    • one-off entries: o
    • envelope-transfers entries: t

• Envelope carryovers to next month
• Output envelope stats and plot
• For home assistant integration see the budgetenvelope-homeassistant-repository

Todo:

• proper testing (surpriiiiise!). Available tests probablyl don't work anymore * Pytest is set up.
• Proper visualisation in homeassistant
• Explain envelope_budget.csv and envelope_adjustments.csv better

Command line options:

see also Documentation: http://budget-envelopes.rtfd.io

> budget-envelopes --help

Usage: budget-envelopes [OPTIONS]

Console script for budget_envelopes.

Options:
-b, --budgets TEXT         Path to budgets csv file (fixed format)
-t, --transactions TEXT    Path to file including transactions in either csv
                        or json format. Json should be an array of
                        objects.
-$, --amount-field TEXT    The field which supplying the amount of the
                        transactions
-D, --date-field TEXT      The field supplying the date of the transaction.
                        Can be supplied multiple times in order of
                        priority (e.g. transaction date, booking date)
-E, --envelope-field TEXT  Field supplying the envelope (category) from
                        which the money is drawn or put into. Must match
                        categories in budgets-file
--debit-flag-field TEXT    Field supplying the debit/credit flag. Also
                        supply --debit-flag
--debit-flag TEXT          Content of --debit-flag-field when transaction is
                        a debit transaction. Otherwise credit transaction
                        assumed.
--first-month TEXT         Supply from which month the transctions and
                        budgets should be calculated forwards. The format
                        is '2023-05'
-o, --output-file TEXT     Output file name for .json file
-x, --extra-files          Stores multiple extra files along the envelope-
                        stats.json: envelope-stats-history.json: Monthly
                        development history of the envelopesenvelope-
                        stats-aggregated.json: Yearly aggregation of the
                        envelopesenvelope-stats.png: A somewhat weird
                        plot of the current state.
-S, --session TEXT         When adding multiple files per CLI, use a session
                        string that ties the calls together
--help                     Show this message and exit.

Credits

• This package was created with poetry
• Docs tutorials: - https://eikonomega.medium.com/getting-started-with-sphinx-autodoc-part-1-2cebbbca5365 - https://leanmind.es/en/blog/how-to-publish-your-python-project-documentation-on-read-the-docs/

Other blabla's

• Free software: MIT license