| Name | financeager JSON |
| Version |
1.3.7
JSON |
| download |
| home_page | None |
| Summary | command line tool for organizing finances |
| upload_time | 2024-04-02 18:31:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | GPLv3 |
| keywords |
commandline
finances
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.org/project/flake8-pytest-style)
[](https://pypi.org/project/financeager)
[](https://pypistats.org/packages/flake8-pytest-style)
[](https://coveralls.io/github/pylipp/financeager?branch=master)
[](https://en.wikipedia.org/wiki/GNU_General_Public_License#Version_3)
[](https://github.com/ambv/black)
<p align="center">
<h1 align="center">financeager</h1>
<p align="center">Organize your finances from the command line</p>
</p>
An application that helps you administering your daily expenses and earnings using single-entry book-keeping. Interact via the command line interface `fina`.
The `financeager` backend holds databases (internally referred to as 'pockets', stored in `~/.local/share/financeager`). A pocket contains entries for a certain project.
## Quickstart
Who is this for?
----------------
You might be someone who wants to organize finances with a simple software because you're tired of Excel and the like. And you like the command line. And Python.
## Installation
`financeager` requires Python 3.8 or higher (last version supporting Python 3.6/3.7 is 1.0.3/1.2.1).
### From PyPI package
pip install --user --upgrade financeager
### Using pipx
If you have [`pipx`](https://pipxproject.github.io/pipx/) installed, install `financeager` into an isolated environment via
pipx install financeager
## Usage
You can use `financeager` as a client-server or a serverless application (default). The user interacts via the command line interface (CLI).
<details>
<summary>Click here for background information about the modes.</summary>
### Serverless mode
The user request invoked from the CLI is passed to the backend which opens the appropriate database, processes the request, closes the database and returns a response. All communication happens within a single process, hence the label 'serverless'.
In vanilla financeager, this is the default mode.
You can explicitly specify it in the configuration file `~/.config/financeager/config` via
[SERVICE]
name = local
### Client-server mode
Install the [financeager-flask](https://github.com/pylipp/financeager-flask) plugin.
In any case, you're all set up! See the next section about the available client CLI commands and options.
</details>
### Command line interface
The main CLI entry point is called `fina`.
usage: fina [-h] [-V] {add,get,remove,update,copy,list,pockets} ...
optional arguments:
-h, --help show this help message and exit
-V, --version display version info and exit
command
add add an entry to the database
get show information about single entry
remove remove an entry from the database
update update one or more fields of an entry
copy copy an entry from one pocket to another, or within one pocket
list list all entries in the pocket database
pockets list all pocket databases
*Add* earnings (no/positive sign) and expenses (negative sign) to the database:
> fina add burgers -19.99 --category Restaurants
> fina add lottery 123.45 --date 03-14
Category and date can be optionally specified. They default to None and the current day's date, resp. The program will try to derive the entry category from the database if not specified. If several matches are found, the default category is used.
> The date format can be anything that the [parser module](https://dateutil.readthedocs.io/en/stable/parser.html) of the `python-dateutil` library understands (e.g. YYYY-MM-DD, YY-MM-DD or MM-DD).
*Add recurrent* entries by specifying the frequency (yearly, half-yearly, quarterly, bi-monthly, monthly, weekly, daily) with the `-f` flag and optionally start and end date with the `-s` and `-e` flags, resp.
> fina add rent -500 -f monthly -s 01-01 -c rent
By default, the start date is the current date. The entry exists for infinite times, i.e. the end date is evaluated as the current date at query runtime.
Did you make a mistake when adding a new entry? *Update* one or more fields by calling the `update` command with the entry's ID and the respective corrected fields:
> fina update 1 --name "McKing Burgers" --value -18.59
To unset the end date of a recurrent entry, or the category of an entry, use a special indicator: `--end -` and `--category -`
*Remove* an entry by specifying its ID (visible in the output of the `list` command). This removes the `burgers` entry:
> fina remove 1
This would remove the recurrent rent entries (ID is also 1 because standard and recurrent entries are stored in separate tables):
> fina remove 1 --recurrent
Show a side-by-side *overview* of earnings and expenses (filter by date/category/name/value by passing the `--filter` option, e.g. `--filter category=food` to show entries in the categories `food`)
> fina list
Earnings | Expenses
Name Value Date ID | Name Value Date ID
Unspecified 123.45 | Rent 1500.00
Lottery 123.45 03-14 2 | Rent January 500.00 01-01 1
| Rent February 500.00 02-01 1
| Rent March 500.00 03-01 1
=============================================================================
Total 123.45 | Total 1500.00
Difference -1376.55
It might be convenient to list entries of the current month, or a specific month only (example output is omitted):
> fina list --month
> fina list --month January
> fina list --month Dec
> fina list --month 7
> fina list --month 03
In order to only list category entries incl. their respective percentage of earnings/expenses use
> fina list --category-percentage
In order to only list recurrent entries run (you can apply additional filtering (use `-f end=` to list entries with indefinite end) and sorting)
> fina list --recurrent-only
The aforementioned `fina` commands operate on the default database (`main`) unless another pocket is specified by the `--pocket` flag.
> fina add xmas-gifts -42 --date 12-23 --pocket personal
*Copy* an entry from one database to another by specifying entry ID and source/destination pocket:
> fina copy 1 --source 2017 --destination 2018
Detailed information is available from
> fina --help
> fina <subcommand> --help
You can turn on printing debug messages to the terminal using the `--verbose` option, e.g.
> fina list --verbose
You can find a log of interactions at `~/.local/share/financeager/log` (on both the client machine and the server).
### More on configuration
Besides specifying the backend to communicate with, you can also configure frontend options: the name of the default category (assigned when omitting the category option when e.g. adding an entry). The defaults are:
[FRONTEND]
default_category = unspecified
The CLI `fina` tries to read the configuration from `~/.config/financeager/config`. You can specify a custom path by passing it along with the `-C`/`--config` command line option.
### More Goodies
- Command line tab completion is provided by the `argcomplete` package (for bash; limited support for zsh, fish, tcsh). Completion has to be enabled by running `activate-global-python-argcomplete`. Read the [instructions](https://github.com/kislyuk/argcomplete#activating-global-completion) if you want to know more.
### Expansion
Want to use a different database? Should be straightforward by deriving from `Pocket` and implementing the `_entry()` methods. Modify the `Server` class accordingly to use the new pocket type. See also [this issue](https://github.com/pylipp/financeager/issues/18).
### Plugin support
The `financeager` core package can be extended by Python plugins.
The supported groups are:
- `financeager.services`
Available plugins are:
- [financeager-flask](https://github.com/pylipp/financeager-flask)
<details>
<summary>Click here for instructions about creating plugins.</summary>
#### All plugin types
For developing a plugin, create a plugin package containing a `main.py` file:
from financeager import plugin
class _Configuration(plugin.PluginConfiguration):
"""Configuration actions specific to the plugin."""
and implement the required `PluginConfiguration` methods.
Finally, specify the entry point for loading the plugin in `setup.py`:
setup(
...,
entry_points={
<group_name>: <plugin-name> = <package>.main:main,
# e.g.
# "financeager.services": "fancy-service = fancy_service.main:main",
},
)
The plugin name can be different from the package name.
The package name should be prefixed with `financeager-`.
#### Service plugins
For developing a service plugin, extend the aforementioned `main.py` file:
# fancy_service/main.py in the fancy-service package
from financeager import plugin, clients
class _Configuration(plugin.PluginConfiguration):
"""Configuration actions specific to the plugin."""
class _Client(clients.Client):
"""Client to communicate with fancy-service."""
def main():
return plugin.ServicePlugin(
name="fancy-service",
config=_Configuration(),
client=_Client,
)
Provide a suitable client implementation.
Done! When the plugin is correctly installed, and configured to be used (`name = fancy-service`), `financeager` picks it up automatically. The plugin configuration is applied, and the plugin client created.
</details>
## Architecture
The following diagram sketches the relationship between financeager's modules. See the module docstrings for more information.
+--------+
| plugin |
+--------+
¦ ¦
V V
+--------+ +-----------+
| config |-->| cli |
+--------+ +-----------+
¦ Λ +---------+ +---------+
[pre-processing] ¦ ¦ [formatting] <-- | listing | <-- | entries |
V ¦ +---------+ +---------+
+-------------------------------------+
| clients |
+-------------------------------------+
¦ Λ
V ¦
+-------------------------------------+
| | FRONTEND
| |
| localserver | ==========
| |
| | BACKEND
+-------------------------------------+
¦ Λ
V ¦
+-------------------------------------+
| server |
+-------------------------------------+
¦ Λ
V ¦
+-------------------------------------+
| pocket |
+-------------------------------------+
## Contributing
Always welcome! Clone the repo
git clone https://github.com/pylipp/financeager
cd financeager
Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate
Install development dependencies
make install
You're all set for hacking!
Please adhere to test-driven development, if possible: When adding a feature, or fixing a bug, try to construct a test first, and subsequently adapt the implementation. Run the tests from the root directory via
make test
If you added a non-cosmetic change (i.e. a change in functionality, e.g. a bug fix or a new feature), please update `Changelog.md` accordingly as well. Check this README whether the content is still up to date.
## Releasing
1. Tag the latest commit on master by incrementing the current version accordingly (scheme `vmajor.minor.patch`).
1. Run `make release`.
1. The package is automatically published to PyPI using a Github action.
## Related projects
`financeager` aims to be simple in functionality. A related command-line tool is [expenses](https://github.com/manojkarthick/expenses).
For more holistic management of your financial affairs you might consider double-entry book-keeping. The following projects provide mature support:
CLI-focused (GUI/browser extensions available):
- [beancount](https://github.com/beancount/beancount)
- [ledger](https://www.ledger-cli.org/index.html)
Client-server applications
- [firefly-iii](https://www.firefly-iii.org/)
Local GUI applications
- [kmymoney](https://kmymoney.org/)
Raw data
{
"_id": null,
"home_page": null,
"name": "financeager",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "commandline, finances",
"author": null,
"author_email": "Philipp Metzner <beth.aleph@yahoo.de>",
"download_url": "https://files.pythonhosted.org/packages/a5/0e/5f89a62c7be2a5f16500f3739fef7df12eb35087505691cf9fb700e2eb9f/financeager-1.3.7.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/flake8-pytest-style)\n[](https://pypi.org/project/financeager)\n[](https://pypistats.org/packages/flake8-pytest-style)\n\n[](https://coveralls.io/github/pylipp/financeager?branch=master)\n[](https://en.wikipedia.org/wiki/GNU_General_Public_License#Version_3)\n[](https://github.com/ambv/black)\n\n<p align=\"center\">\n <h1 align=\"center\">financeager</h1>\n <p align=\"center\">Organize your finances from the command line</p>\n</p>\n\nAn application that helps you administering your daily expenses and earnings using single-entry book-keeping. Interact via the command line interface `fina`.\n\nThe `financeager` backend holds databases (internally referred to as 'pockets', stored in `~/.local/share/financeager`). A pocket contains entries for a certain project.\n\n## Quickstart\n\n\n\nWho is this for?\n----------------\nYou might be someone who wants to organize finances with a simple software because you're tired of Excel and the like. And you like the command line. And Python.\n\n## Installation\n\n`financeager` requires Python 3.8 or higher (last version supporting Python 3.6/3.7 is 1.0.3/1.2.1).\n\n### From PyPI package\n\n pip install --user --upgrade financeager\n\n### Using pipx\n\nIf you have [`pipx`](https://pipxproject.github.io/pipx/) installed, install `financeager` into an isolated environment via\n\n pipx install financeager\n\n## Usage\n\nYou can use `financeager` as a client-server or a serverless application (default). The user interacts via the command line interface (CLI).\n\n<details>\n <summary>Click here for background information about the modes.</summary>\n\n### Serverless mode\n\nThe user request invoked from the CLI is passed to the backend which opens the appropriate database, processes the request, closes the database and returns a response. All communication happens within a single process, hence the label 'serverless'.\n\nIn vanilla financeager, this is the default mode.\n\nYou can explicitly specify it in the configuration file `~/.config/financeager/config` via\n\n [SERVICE]\n name = local\n\n### Client-server mode\n\nInstall the [financeager-flask](https://github.com/pylipp/financeager-flask) plugin.\n\nIn any case, you're all set up! See the next section about the available client CLI commands and options.\n\n</details>\n\n### Command line interface\n\nThe main CLI entry point is called `fina`.\n\n usage: fina [-h] [-V] {add,get,remove,update,copy,list,pockets} ...\n\n optional arguments:\n -h, --help show this help message and exit\n -V, --version display version info and exit\n\n command\n add add an entry to the database\n get show information about single entry\n remove remove an entry from the database\n update update one or more fields of an entry\n copy copy an entry from one pocket to another, or within one pocket\n list list all entries in the pocket database\n pockets list all pocket databases\n\n*Add* earnings (no/positive sign) and expenses (negative sign) to the database:\n\n > fina add burgers -19.99 --category Restaurants\n > fina add lottery 123.45 --date 03-14\n\nCategory and date can be optionally specified. They default to None and the current day's date, resp. The program will try to derive the entry category from the database if not specified. If several matches are found, the default category is used.\n\n> The date format can be anything that the [parser module](https://dateutil.readthedocs.io/en/stable/parser.html) of the `python-dateutil` library understands (e.g. YYYY-MM-DD, YY-MM-DD or MM-DD).\n\n*Add recurrent* entries by specifying the frequency (yearly, half-yearly, quarterly, bi-monthly, monthly, weekly, daily) with the `-f` flag and optionally start and end date with the `-s` and `-e` flags, resp.\n\n > fina add rent -500 -f monthly -s 01-01 -c rent\n\nBy default, the start date is the current date. The entry exists for infinite times, i.e. the end date is evaluated as the current date at query runtime.\n\nDid you make a mistake when adding a new entry? *Update* one or more fields by calling the `update` command with the entry's ID and the respective corrected fields:\n\n > fina update 1 --name \"McKing Burgers\" --value -18.59\n\nTo unset the end date of a recurrent entry, or the category of an entry, use a special indicator: `--end -` and `--category -`\n\n*Remove* an entry by specifying its ID (visible in the output of the `list` command). This removes the `burgers` entry:\n\n > fina remove 1\n\nThis would remove the recurrent rent entries (ID is also 1 because standard and recurrent entries are stored in separate tables):\n\n > fina remove 1 --recurrent\n\nShow a side-by-side *overview* of earnings and expenses (filter by date/category/name/value by passing the `--filter` option, e.g. `--filter category=food` to show entries in the categories `food`)\n\n > fina list\n\n Earnings | Expenses\n Name Value Date ID | Name Value Date ID\n Unspecified 123.45 | Rent 1500.00\n Lottery 123.45 03-14 2 | Rent January 500.00 01-01 1\n | Rent February 500.00 02-01 1\n | Rent March 500.00 03-01 1\n =============================================================================\n Total 123.45 | Total 1500.00\n Difference -1376.55\n\nIt might be convenient to list entries of the current month, or a specific month only (example output is omitted):\n\n > fina list --month\n > fina list --month January\n > fina list --month Dec\n > fina list --month 7\n > fina list --month 03\n\nIn order to only list category entries incl. their respective percentage of earnings/expenses use\n\n > fina list --category-percentage\n\nIn order to only list recurrent entries run (you can apply additional filtering (use `-f end=` to list entries with indefinite end) and sorting)\n\n > fina list --recurrent-only\n\nThe aforementioned `fina` commands operate on the default database (`main`) unless another pocket is specified by the `--pocket` flag.\n\n > fina add xmas-gifts -42 --date 12-23 --pocket personal\n\n*Copy* an entry from one database to another by specifying entry ID and source/destination pocket:\n\n > fina copy 1 --source 2017 --destination 2018\n\nDetailed information is available from\n\n > fina --help\n > fina <subcommand> --help\n\nYou can turn on printing debug messages to the terminal using the `--verbose` option, e.g.\n\n > fina list --verbose\n\nYou can find a log of interactions at `~/.local/share/financeager/log` (on both the client machine and the server).\n\n### More on configuration\n\nBesides specifying the backend to communicate with, you can also configure frontend options: the name of the default category (assigned when omitting the category option when e.g. adding an entry). The defaults are:\n\n [FRONTEND]\n default_category = unspecified\n\nThe CLI `fina` tries to read the configuration from `~/.config/financeager/config`. You can specify a custom path by passing it along with the `-C`/`--config` command line option.\n\n### More Goodies\n\n- Command line tab completion is provided by the `argcomplete` package (for bash; limited support for zsh, fish, tcsh). Completion has to be enabled by running `activate-global-python-argcomplete`. Read the [instructions](https://github.com/kislyuk/argcomplete#activating-global-completion) if you want to know more.\n\n### Expansion\n\nWant to use a different database? Should be straightforward by deriving from `Pocket` and implementing the `_entry()` methods. Modify the `Server` class accordingly to use the new pocket type. See also [this issue](https://github.com/pylipp/financeager/issues/18).\n\n### Plugin support\n\nThe `financeager` core package can be extended by Python plugins.\nThe supported groups are:\n\n- `financeager.services`\n\nAvailable plugins are:\n\n- [financeager-flask](https://github.com/pylipp/financeager-flask)\n\n<details>\n <summary>Click here for instructions about creating plugins.</summary>\n\n#### All plugin types\n\nFor developing a plugin, create a plugin package containing a `main.py` file:\n\n from financeager import plugin\n\n class _Configuration(plugin.PluginConfiguration):\n \"\"\"Configuration actions specific to the plugin.\"\"\"\n\nand implement the required `PluginConfiguration` methods.\nFinally, specify the entry point for loading the plugin in `setup.py`:\n\n setup(\n ...,\n entry_points={\n <group_name>: <plugin-name> = <package>.main:main,\n # e.g.\n # \"financeager.services\": \"fancy-service = fancy_service.main:main\",\n },\n )\n\nThe plugin name can be different from the package name.\nThe package name should be prefixed with `financeager-`.\n\n#### Service plugins\n\nFor developing a service plugin, extend the aforementioned `main.py` file:\n\n # fancy_service/main.py in the fancy-service package\n from financeager import plugin, clients\n\n class _Configuration(plugin.PluginConfiguration):\n \"\"\"Configuration actions specific to the plugin.\"\"\"\n\n class _Client(clients.Client):\n \"\"\"Client to communicate with fancy-service.\"\"\"\n\n def main():\n return plugin.ServicePlugin(\n name=\"fancy-service\",\n config=_Configuration(),\n client=_Client,\n )\n\nProvide a suitable client implementation.\n\nDone! When the plugin is correctly installed, and configured to be used (`name = fancy-service`), `financeager` picks it up automatically. The plugin configuration is applied, and the plugin client created.\n\n</details>\n\n## Architecture\n\nThe following diagram sketches the relationship between financeager's modules. See the module docstrings for more information.\n\n +--------+\n | plugin |\n +--------+\n \u00a6 \u00a6\n V V\n +--------+ +-----------+\n | config |-->| cli |\n +--------+ +-----------+\n\n \u00a6 \u039b +---------+ +---------+\n [pre-processing] \u00a6 \u00a6 [formatting] <-- | listing | <-- | entries |\n V \u00a6 +---------+ +---------+\n\n +-------------------------------------+\n | clients |\n +-------------------------------------+\n\n \u00a6 \u039b\n V \u00a6\n\n +-------------------------------------+\n | | FRONTEND\n | |\n | localserver | ==========\n | |\n | | BACKEND\n +-------------------------------------+\n\n \u00a6 \u039b\n V \u00a6\n +-------------------------------------+\n | server |\n +-------------------------------------+\n \u00a6 \u039b\n V \u00a6\n +-------------------------------------+\n | pocket |\n +-------------------------------------+\n\n## Contributing\n\nAlways welcome! Clone the repo\n\n git clone https://github.com/pylipp/financeager\n cd financeager\n\nCreate a virtual environment\n\n python3 -m venv .venv\n source .venv/bin/activate\n\nInstall development dependencies\n\n make install\n\nYou're all set for hacking!\nPlease adhere to test-driven development, if possible: When adding a feature, or fixing a bug, try to construct a test first, and subsequently adapt the implementation. Run the tests from the root directory via\n\n make test\n\nIf you added a non-cosmetic change (i.e. a change in functionality, e.g. a bug fix or a new feature), please update `Changelog.md` accordingly as well. Check this README whether the content is still up to date.\n\n## Releasing\n\n1. Tag the latest commit on master by incrementing the current version accordingly (scheme `vmajor.minor.patch`).\n1. Run `make release`.\n1. The package is automatically published to PyPI using a Github action.\n\n## Related projects\n\n`financeager` aims to be simple in functionality. A related command-line tool is [expenses](https://github.com/manojkarthick/expenses).\n\nFor more holistic management of your financial affairs you might consider double-entry book-keeping. The following projects provide mature support:\n\nCLI-focused (GUI/browser extensions available):\n- [beancount](https://github.com/beancount/beancount)\n- [ledger](https://www.ledger-cli.org/index.html)\n\nClient-server applications\n- [firefly-iii](https://www.firefly-iii.org/)\n\nLocal GUI applications\n- [kmymoney](https://kmymoney.org/)\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "command line tool for organizing finances",
"version": "1.3.7",
"project_urls": {
"Bug Tracker": "https://github.com/pylipp/financeager/issues",
"Documentation": "https://github.com/pylipp/financeager",
"Homepage": "https://github.com/pylipp/financeager",
"Source Code": "https://github.com/pylipp/financeager"
},
"split_keywords": [
"commandline",
" finances"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "142a1dacbfdb6ebf6b995c6a9155250dfccc57f728f2b384430ca9c398b7c116",
"md5": "119ae1d469892bfa2721d9b29670382c",
"sha256": "122294076dddf9d0e8dbb2253cba8f27c653a80602e48e4e7322e92b1415c1e4"
},
"downloads": -1,
"filename": "financeager-1.3.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "119ae1d469892bfa2721d9b29670382c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 42230,
"upload_time": "2024-04-02T18:31:53",
"upload_time_iso_8601": "2024-04-02T18:31:53.692637Z",
"url": "https://files.pythonhosted.org/packages/14/2a/1dacbfdb6ebf6b995c6a9155250dfccc57f728f2b384430ca9c398b7c116/financeager-1.3.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a50e5f89a62c7be2a5f16500f3739fef7df12eb35087505691cf9fb700e2eb9f",
"md5": "a8f73d28b4f9195b7a782cd2cfd9fa92",
"sha256": "0033fbbb669dd308c46b0881e76572f61fbbf63322b64b8d51fcca7007addc63"
},
"downloads": -1,
"filename": "financeager-1.3.7.tar.gz",
"has_sig": false,
"md5_digest": "a8f73d28b4f9195b7a782cd2cfd9fa92",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 90200,
"upload_time": "2024-04-02T18:31:55",
"upload_time_iso_8601": "2024-04-02T18:31:55.392282Z",
"url": "https://files.pythonhosted.org/packages/a5/0e/5f89a62c7be2a5f16500f3739fef7df12eb35087505691cf9fb700e2eb9f/financeager-1.3.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-02 18:31:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pylipp",
"github_project": "financeager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "financeager"
}
