Technical Implementation

General Remarks

As mentioned in the title, Bankr itself is simple and functional Python. The heavy lifting for the data is done using Pandas DataFrames. However, since manipulations of Series and DataFrames within Pandas can be quite tricky, its major building blocks are explained here.

A CLI based command typically consists of a series of data manipulations or Python functions, as can be seen in the section The Command Line Interface within the Reference. It is therefore straight forward to do individual data manipulations using the REPL of Python or IPython. A modification of the Book's data format for example would consist of the following data manipulation steps:

• Unpickle the Book in Python or IPython
• Change the format of the Book as desired
• Pickle the Book
• Adapt book-v?.yaml accordingly

Further manipulations of the Book can be done again using the CLI commands.

Data Structure

Bankr gets its configuration from ./bankr.yaml in the starting folder, and saves its data within a data folder, which is defined in bankr.yaml. As a YAML file, it is human-readable in any editor. Further YAMLs, see below, define the data structure. These files are commented, so please see the infos there. Furthermore, Bankr never writes any *.yaml config files, but saves only Book data by pickling it.

The structure within the data folder is as follows:

book-v3.pickle              # The Book
book-v3_<DATETIME>.pickle   # Backups of the Book, created at <YYmmdd-HHMMSS>, if present
accounts.yaml               # The accounts, see comments there
book-v3.yaml                # The structure of the Book (of the relevant Pandas DataFrame)
cats.yaml                   # The categories, see comments there
filters.yaml                # The filter information needed for auto categorization
tags.yaml                   # The tag to group entries
csv/
    <IBAN>-<DATE>.csv       # The Transactions of an IBAN until DATE (Hint: See Best Practices!)
    ...                     # Further IBAN of the same web access of a bank
    <BANK_CODE>.yaml        # The data structure of the bank's web access, defining »their« IBANs
    ...                     # Further pairs of CSVs/BANK_CODE. Bank code as calculated by Schwifty
    zip/                    # Not operational in v0.0.1
        <IBAN>.zip          # Backups of the CSVs per IBAN
        <BANK_CODE>.zip     # Backups of the <BANK_CODE>.yaml, if present

All YAML based configuration (Bankr uses PyYAML) is human readable. Adapt these configuration files to your needs in any editor.

The Book, Pages and Transactions

The Book

The Book is a Pandas DataFrame with mandatory and optional columns or Figures. From the allowed optional Figures, a subset can be selected using book-v3.yaml. The Book is the only data structure of Bankr, which is saved to and read from disk during normal operations. All other data needed for presentation of the banking data is generated on the fly.

An Entry ID (or UUID) is marking each Entry individually. It is generated during the parsing of CSV data, or when adding an Entry manually. Within the Pandas DataFrame of the Book, it is used technically as the index.

As seen in the section Data Structure above, a backup of the pickled data is generated during pickling of the Book, which is typically the last step in data processing for CLI commands, and which changes the content of the Book.

The basic data manipulation process is receiving or parsing new data in CSV format from the exports of the bank accounts. When parsing, we generate a Raw Page from the CSV, which is similar to a Page, but contains the data as strings and has potentially unused columns. After generating an Entry ID within the Raw Page, and calculating the cents of the Entry, the Raw Page is validated. This means that the Raw Page is modified having the a.m. format of the Pandas DataFrame. The steps of the data manipulation are described here.

Pages

Pages are just parts of the Book with respect to Entries, where the Pandas DataFrame of a Page follows the data structure of the Book.

Pages typically exist after parsing of a CSV, or as a database to calculate data to be presented.

Entries

An Entry is a Page with one row. Otherwise, it follows the data structure of the Book.

Major Data Manipulation Steps

The major data manipulation steps during routine operation of Bankr are:

• Creating a new Book: create_new_book
• Parsing CSV data from the bank accounts: parse
• Categorizing Transactions manually, if the filter mechanism is failing: categorize_entries_manually
• Potentially adding (create empty Entry and edit) or editing, or deleting Entries in the Book.

These and all other Python functions are described within the Reference. Major data manipulations under the hood, meaning without a direct CLI command of the user, are:

• Pickling and unpickling the Book. Not surprising, most CLI commands begin with fetching the Book from disk or unpickling it.
• Validating of Pages, Entries, and the Book. See the Best Practices for more details.
• Automatically categorize.
• Calculation of further DataFrames for data presentation

More Technical Details

More technical details are discussed in the wiki of Bankr.