Pynomina


Wolfgang Fahl

OsProject

OsProject
id  pynomina
state  active
owner  WolfgangFahl
title  pynomina
url  https://github.com/WolfgangFahl/pynomina
version  0.0.5
description  personal finance tool
date  2024-10-10
since  2024-10-06
until  

Demo

https://nomina.bitplan.com

Introduction

pynomina is a personal finance tool designed to provide a flexible and enduring solution for managing financial records from diverse personal accounting tool sources. It aims to address the challenges of data conversion between different accounting software and ensure long-term readability of financial data. There is only limited support for the actual accounting tasks - this can be done much better by existing commercial and open source solutions. pynomina aims to give you the long-term freedom of choice between tools.

OsProject[edit]

OsProject
id  pynomina
state  active
owner  WolfgangFahl
title  pynomina
url  https://github.com/WolfgangFahl/pynomina
version  0.0.5
description  personal finance tool
date  2024-10-10
since  2024-10-06
until  

Demo[edit]

https://nomina.bitplan.com

Introduction[edit]

pynomina is a personal finance tool designed to provide a flexible and enduring solution for managing financial records from diverse personal accounting tool sources. It aims to address the challenges of data conversion between different accounting software and ensure long-term readability of financial data. There is only limited support for the actual accounting tasks - this can be done much better by existing commercial and open source solutions. pynomina aims to give you the long-term freedom of choice between tools.

Motivation[edit]

In the past decades the author used different personal accounting tools:

The pain the conversion between those tools created was finally big enough to do something about it.

Goals[edit]

  • use a computer and human-readable ledger format that is ready to survive decades
  • convert from and to the formats of the tool of choice
  • allow for simple sanity checks and reports
  • allow for systematic tidy up
  • allow for integration into a larger organizational knowledge graph


Hub & Spoke Conversion[edit]

The pyNomina tool follows a Hub and Spoke model for conversion between different personal accounting file formats. The Ledger Book (YAML/JSON) format acts as the hub, with each supported format serving as a spoke. This setup simplifies conversions by allowing data to be transformed from any spoke to the hub and then to any other spoke format.

0xa0be5aae.png

Motivation[edit]

In the past decades the author used different personal accounting tools:

The pain the conversion between those tools created was finally big enough to do something about it.

Goals[edit]

  • use a computer and human-readable ledger format that is ready to survive decades
  • convert from and to the formats of the tool of choice
  • allow for simple sanity checks and reports
  • allow for systematic tidy up
  • allow for integration into a larger organizational knowledge graph

Hub & Spoke Conversion[edit]

The pyNomina tool follows a Hub and Spoke model for conversion between different personal accounting file formats. The Ledger Book (YAML/JSON) format acts as the hub, with each supported format serving as a spoke. This setup simplifies conversions by allowing data to be transformed from any spoke to the hub and then to any other spoke format.

0xa0be5aae.png

Supported Formats[edit]

Format Type Description Wikidata Entry
Ledger Book YAML/JSON Hub Main format of pyNomina for converting between formats. Ledger Book
Beancount Spoke A plaintext accounting format. Beancount
GnuCash XML Spoke An XML-based format used by GnuCash. GnuCash
Microsoft Money Spoke Zip File exported with mny_export script using mdb-tools Microsoft Money
Finanzmanager Deluxe (QIF) Spoke A variant of QIF used by Finanzmanager Deluxe. Finanzmanager Deluxe
Quicken Interchange Format Spoke Quicken Interchange Format (QIF) Quicken
pyNomina Banking ZV YAML Spoke A format for exporting banking data in YAML or JSON. Banking ZV


Installation[edit]

pip install pynomina
# alternatively if your pip is not a python3 pip
pip3 install pynomina 
# local install from source directory of pynomina 
pip install .

upgrade[edit]

pip install pynomina  -U
# alternatively if your pip is not a python3 pip
pip3 install pynomina -U


OsProject[edit]

OsProject
id  pynomina
state  active
owner  WolfgangFahl
title  pynomina
url  https://github.com/WolfgangFahl/pynomina
version  0.0.5
description  personal finance tool
date  2024-10-10
since  2024-10-06
until  

Demo[edit]

https://nomina.bitplan.com

Usage[edit]

command line[edit]

nomina -h
usage: nomina [-h] [-a] [--apache APACHE] [-c] [-d]
              [--debugServer DEBUGSERVER] [--debugPort DEBUGPORT]
              [--debugRemotePath DEBUGREMOTEPATH]
              [--debugLocalPath DEBUGLOCALPATH] [-l] [-i INPUT] [-rol]
              [--host HOST] [--port PORT] [-s] [-V] [-v] [-rp ROOT_PATH]
              [--convert CONVERT] [--format {LB-YAML,GC-XML,BEAN}] [-o OUTPUT]

Personal finance tool

options:
  -h, --help            show this help message and exit
  -a, --about           show about info [default: False]
  --apache APACHE       create an apache configuration file for the given
                        domain
  -c, --client          start client [default: False]
  -d, --debug           show debug info [default: False]
  --debugServer DEBUGSERVER
                        remote debug Server
  --debugPort DEBUGPORT
                        remote debug Port
  --debugRemotePath DEBUGREMOTEPATH
                        remote debug Server path mapping - remotePath - path
                        on debug server
  --debugLocalPath DEBUGLOCALPATH
                        remote debug Server path mapping - localPath - path on
                        machine where python runs
  -l, --local           run with local file system access [default: False]
  -i INPUT, --input INPUT
                        input file
  -rol, --render_on_load
                        render on load [default: False]
  --host HOST           the host to serve / listen from [default: localhost]
  --port PORT           the port to serve from [default: 9849]
  -s, --serve           start webserver [default: False]
  -V, --version         show program's version number and exit
  -v, --verbose         show verbose output [default: False]
  -rp ROOT_PATH, --root_path ROOT_PATH
                        path to nomina files [default:
                        /Users/wf/Library/Python/3.12/lib/python/site-
                        packages/nomina_examples]
  --convert CONVERT     Convert the specified file to the desired format
  --format {LB-YAML,GC-XML,BEAN}
                        Output format for conversion [default: LB-YAML]
  -o OUTPUT, --output OUTPUT
                        Output file

command line conversion[edit]

There is a script test_cmdline that tries out some combinations of input and output file formats. see also Issue 7:command line conversion support 

scripts/test_cmdline 
nomina_examples/empty.yaml →  /tmp/nomina/empty_converted.yaml: LB-YAML✅
nomina_examples/empty.yaml →  /tmp/nomina/empty_converted.gnucash: GC-XML✅
nomina_examples/empty.yaml →  /tmp/nomina/empty_converted.beancount: BEAN✅
...

starting as local webapp[edit]

nomina -s -l 
NiceGUI ready to go on http://localhost:9849

command line[edit]

nomina -h
usage: nomina [-h] [-a] [--apache APACHE] [-c] [-d]
              [--debugServer DEBUGSERVER] [--debugPort DEBUGPORT]
              [--debugRemotePath DEBUGREMOTEPATH]
              [--debugLocalPath DEBUGLOCALPATH] [-l] [-i INPUT] [-rol]
              [--host HOST] [--port PORT] [-s] [-V] [-v] [-rp ROOT_PATH]
              [--convert CONVERT] [--format {LB-YAML,GC-XML,BEAN}] [-o OUTPUT]

Personal finance tool

options:
  -h, --help            show this help message and exit
  -a, --about           show about info [default: False]
  --apache APACHE       create an apache configuration file for the given
                        domain
  -c, --client          start client [default: False]
  -d, --debug           show debug info [default: False]
  --debugServer DEBUGSERVER
                        remote debug Server
  --debugPort DEBUGPORT
                        remote debug Port
  --debugRemotePath DEBUGREMOTEPATH
                        remote debug Server path mapping - remotePath - path
                        on debug server
  --debugLocalPath DEBUGLOCALPATH
                        remote debug Server path mapping - localPath - path on
                        machine where python runs
  -l, --local           run with local file system access [default: False]
  -i INPUT, --input INPUT
                        input file
  -rol, --render_on_load
                        render on load [default: False]
  --host HOST           the host to serve / listen from [default: localhost]
  --port PORT           the port to serve from [default: 9849]
  -s, --serve           start webserver [default: False]
  -V, --version         show program's version number and exit
  -v, --verbose         show verbose output [default: False]
  -rp ROOT_PATH, --root_path ROOT_PATH
                        path to nomina files [default:
                        /Users/wf/Library/Python/3.12/lib/python/site-
                        packages/nomina_examples]
  --convert CONVERT     Convert the specified file to the desired format
  --format {LB-YAML,GC-XML,BEAN}
                        Output format for conversion [default: LB-YAML]
  -o OUTPUT, --output OUTPUT
                        Output file

command line conversion[edit]

There is a script test_cmdline that tries out some combinations of input and output file formats. see also Issue 7:command line conversion support 

scripts/test_cmdline 
nomina_examples/empty.yaml →  /tmp/nomina/empty_converted.yaml: LB-YAML✅
nomina_examples/empty.yaml →  /tmp/nomina/empty_converted.gnucash: GC-XML✅
nomina_examples/empty.yaml →  /tmp/nomina/empty_converted.beancount: BEAN✅
...

starting as local webapp[edit]

nomina -s -l 
NiceGUI ready to go on http://localhost:9849

Tutorials[edit]

Quicken[edit]

Pynomina/Quicken

GnuCash[edit]

Pynomina/GnuCash

Beancount[edit]

Pynomina/Beancount

Microsoft Money[edit]

Pynomina/MsMoney

Quicken[edit]

Pynomina/Quicken

GnuCash[edit]

Pynomina/GnuCash

Beancount[edit]

Pynomina/Beancount

Microsoft Money[edit]

Pynomina/MsMoney

tickets[edit]

  1. Issue 19 - add account view✓
  2. Issue 18 - add a book view✓
  3. Issue 16 - handle VAT Codes
  4. Issue 15 - enforce beancount account naming
  5. Issue 14 - add calc_balances and remove_unused_accounts function✓
  6. Issue 12 - add Microsoft Money support✓
  7. Issue 10 - Beancount conversion problem with expenses2024_bzv example✓
  8. Issue 9 - file format detection✓
  9. Issue 8 - Beancount conversion support✓
  10. Issue 7 - command line conversion support✓
  11. Issue 6 - Subsembly JSON (BankingZV) export support✓
  12. Issue 5 - Quicken QIF format support (very simple or Finanzmanager Deluxe Export format for a start ...)✓
  13. Issue 4 - GnuCash XML support✓
  14. Issue 3 - Abstract ledger✓
  15. Issue 2 - setup open checkos compatible opensource project✓

Testing[edit]

The testcases are python unittest modules see https://github.com/WolfgangFahl/pynomina/tree/main/tests. These tests are run as part of the continuous integration github actions To run the tests manually there is a "test" script in the scripts directory: 

scripts/test 
Starting test test_read_bzv, debug=True ...
# Accounts: 3
# Transactions: 2
Date Range: 2024-10-06 to 2024-10-06
# Categories: 1
# Currencies: EUR: 2
Other Details:
  name: expenses2024
  owner: John Doe
test test_read_bzv, debug=True took   0.0 s
.Starting test test_conversions, debug=True ...
Converting Ledger Book None to GC-XML

...
Ran 17 tests in 4.518s

OK

see also https://github.com/WolfgangFahl/pynomina/issues/3


Ledger Book[edit]

The pynomina Ledger Book model consists of four main classes:

  • Book
  • Account
  • Transaction
  • Split

These are the necessary classes which work together to represent a comprehensive financial ledger records.

OsProject[edit]

OsProject
id  pynomina
state  active
owner  WolfgangFahl
title  pynomina
url  https://github.com/WolfgangFahl/pynomina
version  0.0.5
description  personal finance tool
date  2024-10-10
since  2024-10-06
until  

Supported Formats[edit]

Format Type Description Wikidata Entry
Ledger Book YAML/JSON Hub Main format of pyNomina for converting between formats. Ledger Book
Beancount Spoke A plaintext accounting format. Beancount
GnuCash XML Spoke An XML-based format used by GnuCash. GnuCash
Microsoft Money Spoke Zip File exported with mny_export script using mdb-tools Microsoft Money
Finanzmanager Deluxe (QIF) Spoke A variant of QIF used by Finanzmanager Deluxe. Finanzmanager Deluxe
Quicken Interchange Format Spoke Quicken Interchange Format (QIF) Quicken
pyNomina Banking ZV YAML Spoke A format for exporting banking data in YAML or JSON. Banking ZV


Installation[edit]

pip install pynomina
# alternatively if your pip is not a python3 pip
pip3 install pynomina 
# local install from source directory of pynomina 
pip install .

upgrade[edit]

pip install pynomina  -U
# alternatively if your pip is not a python3 pip
pip3 install pynomina -U


command line[edit]

nomina -h
usage: nomina [-h] [-a] [--apache APACHE] [-c] [-d]
              [--debugServer DEBUGSERVER] [--debugPort DEBUGPORT]
              [--debugRemotePath DEBUGREMOTEPATH]
              [--debugLocalPath DEBUGLOCALPATH] [-l] [-i INPUT] [-rol]
              [--host HOST] [--port PORT] [-s] [-V] [-v] [-rp ROOT_PATH]
              [--convert CONVERT] [--format {LB-YAML,GC-XML,BEAN}] [-o OUTPUT]

Personal finance tool

options:
  -h, --help            show this help message and exit
  -a, --about           show about info [default: False]
  --apache APACHE       create an apache configuration file for the given
                        domain
  -c, --client          start client [default: False]
  -d, --debug           show debug info [default: False]
  --debugServer DEBUGSERVER
                        remote debug Server
  --debugPort DEBUGPORT
                        remote debug Port
  --debugRemotePath DEBUGREMOTEPATH
                        remote debug Server path mapping - remotePath - path
                        on debug server
  --debugLocalPath DEBUGLOCALPATH
                        remote debug Server path mapping - localPath - path on
                        machine where python runs
  -l, --local           run with local file system access [default: False]
  -i INPUT, --input INPUT
                        input file
  -rol, --render_on_load
                        render on load [default: False]
  --host HOST           the host to serve / listen from [default: localhost]
  --port PORT           the port to serve from [default: 9849]
  -s, --serve           start webserver [default: False]
  -V, --version         show program's version number and exit
  -v, --verbose         show verbose output [default: False]
  -rp ROOT_PATH, --root_path ROOT_PATH
                        path to nomina files [default:
                        /Users/wf/Library/Python/3.12/lib/python/site-
                        packages/nomina_examples]
  --convert CONVERT     Convert the specified file to the desired format
  --format {LB-YAML,GC-XML,BEAN}
                        Output format for conversion [default: LB-YAML]
  -o OUTPUT, --output OUTPUT
                        Output file
🖨 🚪