mincong-h / finance-toolkit

Finance Toolkit
3 stars 1 forks source link
finance python python3

Build Status codecov

Finance Toolkit

Finance Toolkit is a command line interface (CLI) that helps you to better understand your personal finance situation by collecting data from different companies. Currenctly,

Company Transaction Balance Description
BNP Paribas Supported Supported You can download the CSV files from BNP Paribas' website and use Finance Toolkit to integrate the data.
Boursorama Supported Supported You can download the CSV files from Boursorama's website and use Finance Toolkit to integrate the data.
Revolut Supported Supported You can download the CSV files from Revolut's website and use Finance Toolkit to integrate the data.
Fortuneo Supported - You can download the CSV files from Fortuneo's website and use Finance Toolkit to integrate the data. However, Fortuneo does not provide an account statement so Finance Toolkit does not know the balance of your accounts.
Other - Partially supported Declare your account and enter the balance manually in Finance Toolkit. We use this approach for companies like October, Degiro, and E*Trade.

:warning: Currently Finance Toolkit is still in alpha phase and cannot be used easily. You need to clone the Git repository build from source to make it work. Please contact mincong.h [ at ] gmail.com if you want to try.

Usage

$ finance-toolkit --help
Finance Toolkit, a command line interface (CLI) that helps you to better understand your personal
finance situation by collecting data from different companies.

Usage:
  finance-toolkit [options] (cat|categories) [<prefix>]
  finance-toolkit [options] merge
  finance-toolkit [options] move

Arguments:
  cat|categories   Print all categories, or categories starting with the given prefix.
  merge            Merge staging data.
  move             Import data from $HOME/Downloads directory.

Options:
  --finance-root FOLDER    Folder where the configuration file is stored (default: $HOME/finances).
  -X --debug               Enable debugging logs. Default: false.

Install

Install With Docker

The Docker images are built by CI (GitHub Actions), to use the script with Docker, you just need to run the commands directly with wrapper script docker-finance.sh:

# Run Commands, such as:
./bin/docker-finance.sh move
./bin/docker-finance.sh merge

Install Without Docker (Deprecated)

Ensure module finance-tookit is ready to be used:

# clone the project
git clone https://github.com/mincong-h/finance-toolkit.git

# go to project
cd finance-toolkit

# Create a new directory called "venv" as virtual environment
python3 -m venv venv

# Enable virtual environment
source venv/bin/activate

# Install requirements for tests
pip3 install -r requirements-tests.txt

# Install Finance Toolkit and its dependencies (the finance-toolkit executable will be created)
python setup.py install

# Disable virtual environment
deactivate

Create a new directory for storing your finance data. It's recommended to store them into a Git repository so that data are versioned and changes can be reverted in any case. For example, to store finance data in ~/finance-data, you need to edit .bash_profile, .bashrc or similar file to include the following lines:

export FINANCE_ROOT="${HOME}/finance-data"
export PYTHONPATH="${HOME}/github/finance-toolkit/"

Create a new configuration file for configuring your accounts (do not forget to update the sample to adapt your needs):

cp /path/to/finance-toolkit/finance-tools.sample.yml "${FINANCE_ROOT}/finance-tools.yml"

Modify the download directory inside the configuration file finance-tools.yml:

# Download Directory
# ------------------
# Download directory is the place where finance files are stored at the first
# place. Usually, this is download directory of your OS or your browser.
#   - macOS: ~/Downloads
#
download-dir: ~/Downloads

Download files from your banks or other supported companies. Then collect data into your finance data directory by performing a tx-move command:

$ tx move
$$$ Summary $$$
---------------
2 files copied.
---------------
Sources:
- /path/to/download/E1851234.csv
- /path/to/download/HistoriqueOperations_12345_du_14_01_2019_au_14_12_2019.csv
Targets:
- /path/to/finance/2019-04/2019-04.astark-FTN-CHQ.csv
- /path/to/finance/2019-06/2019-06.credit-BNP-P15.csv
- /path/to/finance/2019-12/2019-12.astark-FTN-CHQ.csv
- /path/to/finance/balance.credit-BNP-P15.csv
Finished.

Currency

Currently, Finance Toolkit supports multiple currencies, such as euro (EUR) and US dollar (USD). Currency is defined at account level -- each account can only have one single currency. In the configuration file (finance-tools.yml), specify the currency field. For example, for user "Arya Stark (astark)", her BNP account "Compte de Chèque (CHQ)" in euro should be declared as follows:

accounts:
  astark-BNP-CHQ:
    company: BNP
    id: '****1234'
    category: my-category
    currency: EUR
    type: CHQ
    tags: [ ... ]

You can find out more world currency symbols here: https://www.xe.com/en/symbols.php

Development

Local Development

Build a Docker image:

bin/docker-build.sh

Push a Docker image to the Aliyun Registry (you need to connect to the private registry):

bin/docker-push.sh

Run the Docker image built locally with the right command $cmd:

FTK_DOCKER_MODE=local bin/docker-finance.sh $cmd

Pre-commit Hook

Install pre-commit for day-to-day development. It will ensure a good quality code before commiting anything.

python -m pip install -U --user pre-commit
pre-commit install

Testing

Run unit tests (at root level of the project directory):

python -m pytest

Revolut

Revolut Account Statement Format

File name format:

account-statement_{START_DATE}_{END_DATE}_{LANG}_{STATEMENT_ID}.csv

It consists of several parameters:

Examples:

# EUR
account-statement_2021-01-01_2022-05-27_undefined-undefined_abc123.csv

# USD
account-statement_2021-01-01_2022-05-27_en_def123.csv

Delimiter: ,

Columns:

Column Type Comment
Type String TOPUP, EXCHANGE, TRANSFER, CARD_PAYMENT
Product String Current
Started Date Date Format: yyyy-MM-dd' 'hh:mm:ss
Completed Date Date Format: yyyy-MM-dd' 'hh:mm:ss
Description String Description of the statement
Amount Float
Fee Fee
Currency String USD, EUR, ...
State String COMPLETED, PENDING
Balance Optional[Float] Balance of the account or empty

Download CSV File

https://www.revolut.com/en-US/help/my-accounts/managing-my-account/viewing-my-account-statements

Follow the steps below to download CSV files:

Note that: