# Welcome to Bankr

*Bankr is simple Python for your Bank Accounting to categorize your incomes and expenses*

## About

*Bankr*…

- …collects all your bank transactions on your chart of accounts using a CLI. The collection of the transactions is performed via CSV export from your bank accounts.
- …categorizes the transactions using a simple filter mechanism for repeated bookings. One-time transactions can be categorized by hand.
- …allows to add, edit and delete bank transactions by hand.
- …shows, finally, plots and statistics on the Book within the CLI or your web browser.
- …is configured via small and human-readable YAML files, which you can modify using any editor.
- …creates, hopefully, an overview over your finances.

!!! Warning "Disclaimer"
    This software is crafted with the intention to be useful for your accounting business. It will not and it will never be responsible for your financial boom or ruin! It provides an overview of bank accounts, it does **NOT** increase or decrease any balance!
    
    Furthermore, please see the license of this software!

!!! Note "**Alpha** Software"
    This software is in **Alpha** state. There are a several TODOs in the source code, and some further limitations to remove for completion of its functionality! However, `v1` of the data format should be quite stable right now.
    

## Motivation

My motivation for writing these lines of Python code are two-fold:

1. Learning *Python*, *Pandas*, and – currently at basic level – *Panel* within this Python project.
2. Starting with CSV based accounting, especially after some negative experiences with trying to use an [HBCI (now FinTS)](https://en.wikipedia.org/wiki/FinTS) based accounting system. At least in Germany, banks tend to break their own HBCI accesses, especially since their most important accesses to bank accounts seem to be their own and individual banking apps. Fortunately, I am not aware of a bank, which does not allow a CSV based download of the respective transaction data.


## Terms & Definitions

We use some simple terms to define the data generated by *Bankr*. These are:

- The **Book** is a table of all *Transactions* of all your relevant accounts, and therefore the main data of *Bankr*. In fact, it is the only data structure saved to disk. We use the term Book (capitalized) as opposed to the more precise »general ledger«, since it is easy to remember, and it is a simplified non-standard version of a ledger. The *Transactions* in all *Pages* define the *Book*.
- A **Page** is mainly the data in one CSV, imported and conditioned fo the data format of the Book. Furthermore, the term is used, if reduced data from the Book is taken for any calculations or statistics.
- A **Transaction** is one deposit to or disbursal from an account or IBAN. The data within a Transaction – or one row of a Page or the Book – is defined by `book-v1.yaml`.

For more technical details see the section [Implementation](implementation.md).


## Commands

The data of the Book is collected and administrated using *Bankr*'s command line interface (CLI). Its commands are:

* `bankr add` - Add a Transaction to the Book.
* `bankr cat` - Categorize Transactions of a Page or the Book.
* `bankr delete` - Delete a Transaction from the Book.
* `bankr edit` - Edit a Transaction of the Book.
* `bankr new` - Create a new Book.
* `bankr parse` - Parse CSV for a Page to check the import and update the Book.
* `bankr plot` - Plot time information on CLI.
* `bankr show` - Show the Transactions of an interval, an IBAN, or a category.
* `bankr stats` - Statistics of the Book or per time interval.
* `bankr [COMMAND] -h` - Print a help message for `[COMMAND]` and exit.

The help messages of the commands show a more detailed explanation, and more details on their options and arguments.


## Bankr App: Dashboards to analyse your money flows

The data within the Book can be presented using Panel Dashboards (tbc). It is currently in understandable, but very preliminary form.

As of `v0.0.1`, the only way to start the App is `panel serve app_*.py`.