Pynomina/ledger

From BITPlan Wiki
Jump to navigation Jump to search

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

Motivation

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

  • 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

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.

Supported Formats

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

Ledger Book

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.

Class Structure

0xfec2cab6.png

Book

The Book class represents the main container for all financial data. It includes:

  • Basic information: name, owner, creation date, and source URL
  • Collections of accounts and transactions
  • Methods for managing accounts and transactions, including:
    • get_stats(): Retrieves statistics about the book
    • filter(): Filters transactions by date range
    • create_account(): Creates a new account
    • add_account(): Adds an account to the book
    • lookup_account(): Finds an account by ID

Account

The Account class represents a hierarchy of individual financial accounts within the ledger. It includes:

  • account_id: Unique identifier for the account
  • name: Human-readable account name
  • account_type: Type of account (e.g., EXPENSE, INCOME)
  • description: Optional account description
  • currency: Account currency (default: EUR)
  • parent_account_id: Optional parent account for hierarchical structure

Transaction

The Transaction class represents individual financial transactions. It includes:

  • isodate: Date of the transaction in International Standards Organization date format yyyy-mm-dd
  • description: Description of the transaction
  • splits: List of Split objects representing the movement of money
  • payee: Optional payee information
  • memo: Optional additional notes
  • total_amount(): Method to calculate the total transaction amount

Split

The Split class represents the individual components of a transaction, showing how money moves between accounts. It includes:

  • amount: The amount of money involved in the split
  • account_id: The account associated with this part of the transaction
  • memo: Optional notes for this split
  • reconciled: Boolean indicating if the split has been reconciled

Example Data

Here's an example of how the ledger model is used in practice:

Yaml Format

owner: Wolfgang Fahl
url: https://github.com/WolfgangFahl/pynomina/blob/main/nomina_examples/expenses2024.yaml
since: 2024-10-06
accounts:
  Expenses:
    account_id: Expenses
    name: Expenses
    account_type: EXPENSE
    description: 'General Expenses'
    currency: EUR
  Expenses:Food:
    account_id: Expenses:Food
    name: Dining
    account_type: EXPENSE
    description: 'Expenses for Food'
    currency: EUR
    parent_account_id: Expenses
  Cash in wallet:
    account_id: Wallet
    name: Cash in Wallet
    account_type: EXPENSE
    description: ''
    currency: EUR
transactions:
  Bakery2024-10-06_0900_1:
    isodate: '2024-10-06'
    description: Bread
    splits:
      - amount: -3.50
        account_id: Cash in Wallet
      - amount: 3.50
        account_id: Expenses:Dining
        memo: Fresh sourdough bread
  Bakery2024-10-06_0900_2:
    isodate: '2024-10-06'
    description: Buns for Breakfast
    splits:
      - amount: -2.40
        account_id: Cash in Wallet
      - amount: 2.40
        account_id: Expenses:Dining
        memo: 4 whole grain buns

Implementation

The ledger model is implemented in Python, utilizing dataclasses and type hinting for clear and maintainable code. The `@lod_storable` decorator is used to enable easy serialization and deserialization of the data in YAML and/or JSON and other formats. The core idea is that the records should be readily available an tabular "list of dicts (lod)" format.