Difference between revisions of "Pynomina/ledger"

From BITPlan Wiki
Jump to navigation Jump to search
(Created page with "= pynomina Ledger Model = == Ledger Model == The pynomina ledger model consists of four main classes: Book, Account, Transaction, and Split. These classes work together to...")
 
Line 1: Line 1:
−
= pynomina Ledger Model =
+
= Models and Fileformats =
−
 
+
== Ledger Book ==
−
 
+
The pynomina Ledger Book model consists of four main classes:  
−
 
+
* Book
−
== Ledger Model ==
+
* Account
−
The pynomina ledger model consists of four main classes: Book, Account, Transaction, and Split. These classes work together to represent a comprehensive financial ledger system.
+
* Transaction
 +
* Split
 +
These are the necessary classes which work together to represent a comprehensive financial ledger records.
  
 
=== Class Structure ===
 
=== Class Structure ===
−
[[File:https://diagrams.bitplan.com/render/png/0xfec2cab6.png|thumb|right|400px|Ledger module Class Diagram]]
+
https://diagrams.bitplan.com/render/png/0xfec2cab6.png
  
 
==== Book ====
 
==== Book ====
Line 21: Line 23:
  
 
==== Account ====
 
==== Account ====
−
The Account class represents individual financial accounts within the ledger. It includes:
+
The Account class represents a hierarchy of individual financial accounts within the ledger. It includes:
 
* account_id: Unique identifier for the account
 
* account_id: Unique identifier for the account
 
* name: Human-readable account name
 
* name: Human-readable account name
Line 31: Line 33:
 
==== Transaction ====
 
==== Transaction ====
 
The Transaction class represents individual financial transactions. It includes:
 
The Transaction class represents individual financial transactions. It includes:
−
* isodate: Date of the transaction
+
* isodate: Date of the transaction in International Standards Organization date format yyyy-mm-dd
 
* description: Description of the transaction
 
* description: Description of the transaction
 
* splits: List of Split objects representing the movement of money
 
* splits: List of Split objects representing the movement of money
Line 47: Line 49:
 
== Example Data ==
 
== Example Data ==
 
Here's an example of how the ledger model is used in practice:
 
Here's an example of how the ledger model is used in practice:
−
 
+
=== Yaml Format ===
−
<pre>
+
<source lang='yaml'>
 
owner: Wolfgang Fahl
 
owner: Wolfgang Fahl
 
url: https://github.com/WolfgangFahl/pynomina/blob/main/nomina_examples/expenses2024.yaml
 
url: https://github.com/WolfgangFahl/pynomina/blob/main/nomina_examples/expenses2024.yaml
Line 91: Line 93:
 
         account_id: Expenses:Dining
 
         account_id: Expenses:Dining
 
         memo: 4 whole grain buns
 
         memo: 4 whole grain buns
−
</pre>
+
</source>
  
 
== Implementation ==
 
== 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.
+
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.
−
=== Testing ===
+
The core idea is that the records should be readily available an tabular "list of dicts (lod)" format.
−
The implementation includes comprehensive tests to ensure the correct functioning of the ledger model. Here's an example test case:
 
−
 
 
−
<pre>
 
−
class Test_Ledger(Basetest):
 
−
    def setUp(self, debug=True, profile=True):
 
−
        Basetest.setUp(self, debug=debug, profile=profile)
 
−
        self.examples = NominaExample.get_examples()
 
−
 
 
−
    def test_ledger(self):
 
−
        for name, example in self.examples.items():
 
−
            with self.subTest(f"Testing {name}"):
 
−
                ledger_book = Book.load_from_yaml_file(f"{example.example_path}/{name}.yaml")
 
−
                stats = ledger_book.get_stats()
 
−
                if self.debug:
 
−
                    print(stats)
 
−
                self.assertEqual(stats, example.expected_stats)
 
−
</pre>
 
−
 
 
−
== Conclusion ==
 
−
The pynomina ledger model provides a flexible and robust foundation for personal accounting. Its design allows for easy data interchange, long-term readability, and integration with larger financial management systems.
 
−
 
 
−
== See Also ==
 
−
* [https://github.com/WolfgangFahl/pynomina GitHub Repository]
 
−
* [https://pypi.org/project/pynomina/ PyPI Package]
 
−
* [https://WolfgangFahl.github.io/pynomina/ API Documentation]
 
−
 
 
−
[[Category:Personal Finance]]
 
−
[[Category:Accounting Software]]
 
−
[[Category:Open Source Projects]]
 

Revision as of 13:02, 6 October 2024

Models and Fileformats

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.

Retrieved from "https://wiki.bitplan.com/index.php?title=Pynomina/ledger&oldid=19015"