django-ledger 0.5.6.2__py3-none-any.whl → 0.5.6.4__py3-none-any.whl

django_ledger/io/io_library.py

@@ -4,13 +4,15 @@ Copyright© EDMA Group Inc licensed under the GPLv3 Agreement.
 
 Contributions to this module:
     * Miguel Sanda <msanda@arrobalytics.com>
+
+This module contains classes and functions used to document, dispatch and commit new transaction into the database.
 """
 from collections import defaultdict
 from dataclasses import dataclass
 from datetime import date, datetime
 from decimal import Decimal
 from itertools import chain
-from typing import Union, Dict, Callable, Optional
+from typing import Union, Dict, Callable, Optional, List
 from uuid import UUID
 
 from django.core.exceptions import ValidationError
@@ -62,6 +64,23 @@ class IOCursorValidationError(ValidationError):
 
 
 class IOCursor:
+    """
+    Represents a Django Ledger cursor capable of dispatching transactions to the database.
+    The Cursor class is responsible for coordinating the creation of new ledgers, journal entries and transactions
+    It is a low level interface to the IOBlueprint and IOLibrary classes.
+
+    Parameters
+    ----------
+    io_library: IOLibrary
+        The IOLibrary class that contains all the necessary instructions to dispatch the transactions.
+    entity_model: EntityModel
+        The EntityModel instance that will be used for the new transactions.
+    user_model: UserModel
+        The UserModel instance that will be used for the new transactions. Used for read permissions of QuerySets.
+    coa_model: ChartOfAccountModel or UUID or str.
+        The ChartOfAccountModel instance that contains the accounts to be used for transactions.
+        Instance, UUID or slug can be sued to retrieve the model.
+    """
 
     def __init__(self,
                  io_library,
@@ -81,25 +100,61 @@ class IOCursor:
         self.instructions = None
 
     def get_ledger_model_qs(self) -> LedgerModelQuerySet:
+        """
+        Determines the ledger model queryset associated with the entity model and user model provided.
+
+        Returns
+        -------
+        LedgerModelQuerySet
+        """
         return LedgerModel.objects.for_entity(
             self.ENTITY_MODEL,
             self.USER_MODEL
         )
 
     def get_account_model_qs(self) -> AccountModelQuerySet:
+        """
+        Determines the AccountModelQuerySet associated with the Chart of Accounts specified.
+
+        Returns
+        -------
+        AccountModelQuerySet
+        """
         return self.ENTITY_MODEL.get_coa_accounts(
             coa_model=self.COA_MODEL
         )
 
-    def resolve_account_model_qs(self, codes):
+    def resolve_account_model_qs(self, codes: List[str]) -> AccountModelQuerySet:
+        """
+        Resolves the final AccountModelQuerySet associated with the given account codes used by the blueprint.
+
+        Parameters
+        ----------
+        codes: List[str]
+            List of codes used during the execution of the blueprint.
+
+
+        Returns
+        -------
+        AccountModelQuerySet
+            The resolved AccountModelQuerySet associated with the given codes.
+        """
         if self.account_model_qs is None:
-            # codes = self.get_account_codes()
             qs = self.get_account_model_qs()
             qs = qs.filter(code__in=codes)
             self.account_model_qs = qs
         return self.account_model_qs
 
-    def resolve_ledger_model_qs(self):
+    def resolve_ledger_model_qs(self) -> LedgerModelQuerySet:
+        """
+        Resolves the final LedgerModelQuerySet associated with the provided ledger model identifiers used by the
+        blueprints.
+
+        Returns
+        -------
+        LedgerModelQuerySet
+            The resolved LedgerModelQuerySet associated with the given ledger model identifiers.
+        """
         if self.ledger_model_qs is None:
             qs = self.get_ledger_model_qs()
             by_uuid = [k for k in self.blueprints.keys() if isinstance(k, UUID)]
@@ -113,6 +168,20 @@ class IOCursor:
                  name,
                  ledger_model: Optional[Union[str, LedgerModel, UUID]] = None,
                  **kwargs):
+        """
+        Stages the instructions to be processed by the IOCursor class. This method does not commit the transactions
+        into the database.
+
+        Parameters
+        ----------
+        name: str
+            The registered blueprint name to be staged.
+        ledger_model: Optional[Union[str, LedgerModel, UUID]]
+            Optional ledger model identifier to house the transactions associated with the blueprint. If none is
+            provided, a new ledger model will be created.
+        kwargs
+            The keyword arguments to be passed to the blueprint function.
+        """
 
         if not isinstance(ledger_model, (str, UUID, LedgerModel)):
             raise IOCursorValidationError(
@@ -126,8 +195,15 @@ class IOCursor:
         blueprint_txs = blueprint_func(**kwargs)
         self.blueprints[ledger_model].append(blueprint_txs)
 
-    def compile_instructions(self):
+    def compile_instructions(self) -> Dict:
+        """
+        Compiles the blueprint instructions into Journal Entries and Transactions to be committed to the ledger.
 
+        Returns
+        -------
+        Dict
+            A dictionary containing the compiled instructions.
+        """
         if self.instructions is None:
             instructions = {
                 ledger_model: list(chain.from_iterable(
@@ -139,8 +215,6 @@ class IOCursor:
                 total_credits = sum(t.amount for t in txs if t.tx_type == CREDIT)
                 total_debits = sum(t.amount for t in txs if t.tx_type == DEBIT)
 
-                # print("{} credits, {} debits".format(total_credits, total_debits))
-
                 if total_credits != total_debits:
                     raise IOCursorValidationError(
                         message=_('Total transactions Credits and Debits must be equal. '
@@ -151,12 +225,39 @@ class IOCursor:
         return self.instructions
 
     def is_committed(self) -> bool:
+        """
+        Determines if the IOCursor instance has committed the transactions into the database.
+        A cursor can only commit transactions once.
+
+        Returns
+        -------
+        bool
+            True if committed, False otherwise.
+        """
         return self.__COMMITTED
 
     def commit(self,
                je_timestamp: Optional[Union[datetime, date, str]] = None,
                post_new_ledgers: bool = False,
-               post_journal_entries: bool = False):
+               post_journal_entries: bool = False,
+               **kwargs):
+
+        """
+        Commits the compiled blueprint transactions into the database. This action is irreversible and if journal
+        entries are posted, the books will be immediately impacted by the new transactions. It is encouraged NOT to
+        post anything until the transaction is reviews for accuracy.
+
+        Parameters
+        ----------
+        je_timestamp: Optional[Union[datetime, date, str]]
+            The date or timestamp used for the committed journal entries. If none, localtime will be used.
+        post_new_ledgers: bool
+            If a new ledger is created, the ledger model will be posted to the database.
+        post_journal_entries: bool
+            If new journal entries are created, the journal entry models will be posted to the database.
+        kwargs
+            Additional keyword arguments passed to the IO commit_txs function.
+        """
         if self.is_committed():
             raise IOCursorValidationError(
                 message=_('Transactions already committed')
@@ -231,7 +332,8 @@ class IOCursor:
             je, txs_models = ledger_model.commit_txs(
                 je_timestamp=je_timestamp if je_timestamp else get_localtime(),
                 je_txs=je_txs,
-                je_posted=post_journal_entries
+                je_posted=post_journal_entries,
+                **kwargs
             )
 
             results[ledger_model] = {
@@ -253,11 +355,41 @@ class IOBluePrintValidationError(ValidationError):
 
 
 class IOBluePrint:
+    """
+    This class documents instructions required to assemble and dispatch transactions into the ledger.
+
+    Parameters
+    ----------
+    name: str, optional
+        The human-readable name of the IOBluePrint instance.
+    precision_decimals: int
+        The number of decimals to use when balancing transactions. Defaults to 2.
+    """
 
-    def __init__(self, precision_decimals: int = 2):
+    def __init__(self, name: Optional[str] = None, precision_decimals: int = 2):
+        self.name = name
         self.precision_decimals = precision_decimals
         self.registry = list()
 
+    def get_name(self, entity_model: EntityModel) -> str:
+        """
+        Determines the name of the blueprint if none provided.
+
+        Parameters
+        ----------
+        entity_model: EntityModel
+            The EntityModel instance where the resulting blueprint transactions will be stored.
+
+        Returns
+        -------
+        str
+            The name of the blueprint.
+        """
+        if self.name is None:
+            l_dt = get_localtime()
+            return f'blueprint-{entity_model.slug}-{l_dt.strftime("%m%d%Y-%H%M%S")}'
+        return self.name
+
     def _round_amount(self, amount: Decimal) -> Decimal:
         return round(amount, self.precision_decimals)
 
@@ -281,7 +413,18 @@ class IOBluePrint:
         )
 
     def credit(self, account_code: str, amount: Union[float, Decimal], description: str = None):
-
+        """
+        Registers a CREDIT to the specified account..
+
+        Parameters
+        ----------
+        account_code: str
+            The account code to use for the transaction.
+        amount: float or Decimal
+            The amount of the transaction.
+        description: str
+            Description of the transaction.
+        """
         self.registry.append(
             TransactionInstructionItem(
                 account_code=account_code,
@@ -291,7 +434,18 @@ class IOBluePrint:
             ))
 
     def debit(self, account_code: str, amount: Union[float, Decimal], description: str = None):
-
+        """
+        Registers a DEBIT to the specified account.
+
+        Parameters
+        ----------
+        account_code: str
+            The account code to use for the transaction.
+        amount: float or Decimal
+            The amount of the transaction.
+        description: str
+            Description of the transaction.
+        """
         self.registry.append(
             TransactionInstructionItem(
                 account_code=account_code,
@@ -306,20 +460,63 @@ class IOBluePrint:
                ledger_model: Optional[Union[str, LedgerModel, UUID]] = None,
                je_timestamp: Optional[Union[datetime, date, str]] = None,
                post_new_ledgers: bool = False,
-               post_journal_entries: bool = False):
+               post_journal_entries: bool = False,
+               **kwargs) -> Dict:
+        """
+        Commits the blueprint transactions to the database.
+
+        Parameters
+        ----------
+        entity_model: EntityModel
+            The entity model instance where transactions will be committed.
+        user_model: UserModel
+            The user model instance executing transactions to check for permissions.
+        ledger_model: Optional[Union[str, LedgerModel, UUID]]
+            The ledger model instance identifier to be used for the transactions. If none, a new ledger will be created.
+        je_timestamp: date or datetime or str, optional
+            The date and/or time to be used for the transactions. If none, localtime will be used.
+        post_new_ledgers: bool
+            If True, newly created ledgers will be posted. Defaults to False.
+        post_journal_entries: bool
+            If True, newly created journal entries will be posted. Defaults to False.
+        kwargs
+            Keyword arguments passed to the IO Library.
+
+        Returns
+        -------
+        Dict
+            A dictionary containing the resulting models of the transactions.
+        """
+        blueprint_lib = IOLibrary(
+            name=self.get_name(
+                entity_model=entity_model
+            ))
+
+        cursor = blueprint_lib.get_cursor(
+            entity_model=entity_model,
+            user_model=user_model
+        )
 
-        blueprint_lib = IOLibrary(name='blueprint')
-        cursor = blueprint_lib.get_cursor(entity_model=entity_model, user_model=user_model)
         cursor.blueprints[ledger_model].append(self)
 
         return cursor.commit(
             je_timestamp=je_timestamp,
             post_new_ledgers=post_new_ledgers,
-            post_journal_entries=post_journal_entries
+            post_journal_entries=post_journal_entries,
+            **kwargs
         )
 
 
 class IOLibrary:
+    """
+    The IO Library is a centralized interface for documenting commonly used operations. The library will register and
+    document the blueprints and their instructions so that they can be dispatched from anywhere in the application.
+
+    Parameters
+    ----------
+    name: str
+        The human-readable name of the library (i.e. PayRoll, Expenses, Rentals, etc...)
+    """
 
     def __init__(self, name: str):
         self.name = name
@@ -332,6 +529,18 @@ class IOLibrary:
         self.registry[func.__name__] = func
 
     def get_blueprint(self, name: str) -> Callable:
+        """
+        Retrieves a blueprint by name.
+
+        Parameters
+        ----------
+        name: str
+            The name of the blueprint to retrieve.
+
+        Returns
+        -------
+        Callable
+        """
         if not self._check_func_name(name):
             raise IOLibraryError(message=f'Function "{name}" is not registered in IO library {self.name}')
         return self.registry[name]
@@ -342,6 +551,22 @@ class IOLibrary:
             user_model,
             coa_model: Optional[Union[ChartOfAccountModel, UUID, str]] = None
     ) -> IOCursor:
+        """
+        Creates a cursor instance for associated with the library, entity and user model.
+
+        Parameters
+        ----------
+        entity_model: EntityModel
+            The entity model instance where transactions will be committed.
+        user_model: UserModel
+            The user model instance executing the transactions.
+        coa_model: ChartOfAccountModel or UUID or str, optional
+            The ChartOfAccountsModel instance or identifier used to determine the AccountModelQuerySet used for the transactions.
+
+        Returns
+        -------
+        IOCursor
+        """
         return IOCursor(
             io_library=self,
             entity_model=entity_model,

django_ledger/io/roles.py

@@ -119,48 +119,52 @@ ROOT_GROUP_LEVEL_2 = [
 ]
 ROOT_GROUP_META = {
     ROOT_COA: {
-        'code': '00000',
+        'code': '00000000',
         'title': 'CoA Root Node',
         'balance_type': DEBIT
     },
     ROOT_ASSETS: {
-        'code': '01000',
+        'code': '01000000',
         'title': 'Asset Accounts Root Node',
         'balance_type': DEBIT
     },
     ROOT_LIABILITIES: {
-        'code': '02000',
+        'code': '02000000',
         'title': 'Liability Accounts Root Node',
         'balance_type': CREDIT
     },
     ROOT_CAPITAL: {
-        'code': '03000',
+        'code': '03000000',
         'title': 'Capital Accounts Root Node',
         'balance_type': CREDIT
     },
     ROOT_INCOME: {
-        'code': '04000',
+        'code': '04000000',
         'title': 'Income Accounts Root Node',
         'balance_type': CREDIT
     },
     ROOT_COGS: {
-        'code': '05000',
+        'code': '05000000',
         'title': 'COGS Accounts Root Node',
         'balance_type': DEBIT
     },
     ROOT_EXPENSES: {
-        'code': '06000',
+        'code': '06000000',
         'title': 'Expense Accounts Root Node',
         'balance_type': DEBIT
     },
 }
 # ------> ROLE GROUPS <-------#
 
+GROUP_ASSETS = list()
+GROUP_ASSETS.append(ROOT_ASSETS)
+
 # ASSET GROUPS...
 GROUP_QUICK_ASSETS = [
     ASSET_CA_CASH,
     ASSET_CA_MKT_SECURITIES
 ]
+GROUP_ASSETS += GROUP_QUICK_ASSETS
 
 GROUP_CURRENT_ASSETS = [
     ASSET_CA_CASH,
@@ -171,6 +175,7 @@ GROUP_CURRENT_ASSETS = [
     ASSET_CA_UNCOLLECTIBLES,
     ASSET_CA_OTHER
 ]
+GROUP_ASSETS += GROUP_CURRENT_ASSETS
 
 GROUP_NON_CURRENT_ASSETS = [
     ASSET_LTI_NOTES_RECEIVABLE,
@@ -187,9 +192,13 @@ GROUP_NON_CURRENT_ASSETS = [
     ASSET_ADJUSTMENTS
 ]
 
-GROUP_ASSETS = GROUP_CURRENT_ASSETS + GROUP_NON_CURRENT_ASSETS
+GROUP_ASSETS += GROUP_NON_CURRENT_ASSETS
+GROUP_ASSETS = list(set(GROUP_ASSETS))
 
 # LIABILITY GROUPS....
+GROUP_LIABILITIES = list()
+GROUP_LIABILITIES.append(ROOT_LIABILITIES)
+
 GROUP_CURRENT_LIABILITIES = [
     LIABILITY_CL_ACC_PAYABLE,
     LIABILITY_CL_DEFERRED_REVENUE,
@@ -200,17 +209,21 @@ GROUP_CURRENT_LIABILITIES = [
     LIABILITY_CL_WAGES_PAYABLE,
     LIABILITY_CL_TAXES_PAYABLE
 ]
+GROUP_LIABILITIES += GROUP_CURRENT_LIABILITIES
 
 GROUP_LT_LIABILITIES = [
     LIABILITY_LTL_NOTES_PAYABLE,
     LIABILITY_LTL_BONDS_PAYABLE,
     LIABILITY_LTL_MORTGAGE_PAYABLE,
 ]
+GROUP_LIABILITIES += GROUP_LT_LIABILITIES
 
-GROUP_LIABILITIES = GROUP_CURRENT_LIABILITIES + GROUP_LT_LIABILITIES
+GROUP_LIABILITIES = list(set(GROUP_LIABILITIES))
 
 # CAPITAL/EQUITY...
+
 GROUP_CAPITAL = [
+    ROOT_CAPITAL,
     EQUITY_CAPITAL,
     EQUITY_COMMON_STOCK,
     EQUITY_PREFERRED_STOCK,
@@ -219,6 +232,7 @@ GROUP_CAPITAL = [
 ]
 
 GROUP_INCOME = [
+    ROOT_INCOME,
     INCOME_OPERATIONAL,
     INCOME_PASSIVE,
     INCOME_INTEREST,
@@ -227,10 +241,12 @@ GROUP_INCOME = [
 ]
 
 GROUP_COGS = [
+    ROOT_COGS,
     COGS
 ]
 
 GROUP_EXPENSES = [
+    ROOT_EXPENSES,
     EXPENSE_OPERATIONAL,
     EXPENSE_INTEREST_ST,
     EXPENSE_INTEREST_LT,
@@ -374,10 +390,14 @@ GROUP_CFS_FINANCING += GROUP_CFS_FIN_LT_DEBT_PAYMENTS
 # Purchase of Assets....
 GROUP_CFS_INV_PURCHASE_OR_SALE_OF_PPE = [
     ASSET_PPE_BUILDINGS,
+    ASSET_PPE_BUILDINGS_ACCUM_DEPRECIATION,
     ASSET_PPE_PLANT,
+    ASSET_PPE_PLANT_ACCUM_DEPRECIATION,
     ASSET_PPE_EQUIPMENT,
+    ASSET_PPE_EQUIPMENT_ACCUM_DEPRECIATION,
     INCOME_CAPITAL_GAIN_LOSS
 ]
+
 GROUP_CFS_INV_LTD_OF_PPE = [
     LIABILITY_LTL_NOTES_PAYABLE,
     LIABILITY_LTL_MORTGAGE_PAYABLE,
@@ -386,14 +406,16 @@ GROUP_CFS_INV_LTD_OF_PPE = [
 
 GROUP_CFS_INVESTING_PPE = GROUP_CFS_INV_PURCHASE_OR_SALE_OF_PPE + GROUP_CFS_INV_LTD_OF_PPE
 
-# Purchase of Securities...
+# Purchase/Sell of Securities...
 GROUP_CFS_INV_PURCHASE_OF_SECURITIES = [
     ASSET_CA_MKT_SECURITIES,
     ASSET_LTI_NOTES_RECEIVABLE,
     ASSET_LTI_SECURITIES,
     INCOME_INTEREST,
     INCOME_PASSIVE,
+    INCOME_CAPITAL_GAIN_LOSS
 ]
+
 GROUP_CFS_INV_LTD_OF_SECURITIES = [
     LIABILITY_LTL_NOTES_PAYABLE,
     LIABILITY_LTL_BONDS_PAYABLE

django_ledger/migrations/0015_remove_chartofaccountmodel_locked_and_more.py

@@ -0,0 +1,22 @@
+# Generated by Django 5.0.3 on 2024-03-14 02:17
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('django_ledger', '0014_ledgermodel_ledger_xid_and_more'),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name='chartofaccountmodel',
+            name='locked',
+        ),
+        migrations.AddField(
+            model_name='chartofaccountmodel',
+            name='active',
+            field=models.BooleanField(default=True, verbose_name='Is Active'),
+        ),
+    ]

django_ledger/models/accounts.py

@@ -164,6 +164,10 @@ class AccountModelManager(MP_NodeManager):
         qs = self.get_queryset()
         if user_model.is_superuser:
             return qs
+        return qs.filter(
+            Q(coa_model__entity__admin=user_model) |
+            Q(coa_model__entity__managers__in=[user_model])
+        )
 
     # todo: search for uses and pass EntityModel whenever possible.
     def for_entity(self,
@@ -238,8 +242,9 @@ class AccountModelManager(MP_NodeManager):
             entity_slug=entity_slug,
             coa_slug=coa_slug)
         return qs.filter(
-            active=True,
-            locked=False
+            Q(active=True) &
+            Q(locked=False) &
+            Q(coa_model__active=True)
         )
 
     def with_roles(self, roles: Union[list, str], entity_slug, user_model) -> AccountModelQuerySet:
@@ -577,7 +582,7 @@ class AccountModelAbstract(MP_Node, CreateUpdateMixIn):
         return self.balance_type == CREDIT
 
     def is_coa_root(self):
-        return self.role in ROOT_GROUP
+        return self.role == ROOT_COA
 
     def is_asset(self) -> bool:
         return self.role in GROUP_ASSETS
@@ -600,6 +605,9 @@ class AccountModelAbstract(MP_Node, CreateUpdateMixIn):
     def is_active(self) -> bool:
         return self.active is True
 
+    def is_locked(self) -> bool:
+        return self.locked is True
+
     def can_activate(self):
         return all([
             self.active is False
@@ -652,10 +660,7 @@ class AccountModelAbstract(MP_Node, CreateUpdateMixIn):
             return '5'
         elif self.is_expense():
             return '6'
-        elif self.is_coa_root():
-            return '0'
-        else:
-            raise AccountModelValidationError(f'Invalid role match for role {self.role}...')
+        raise AccountModelValidationError(f'Invalid role match for role {self.role}...')
 
     def get_root_role(self) -> str:
         if self.is_asset():
@@ -672,8 +677,7 @@ class AccountModelAbstract(MP_Node, CreateUpdateMixIn):
             return ROOT_EXPENSES
         elif self.is_coa_root():
             return ROOT_COA
-        else:
-            raise AccountModelValidationError(f'Invalid role match for role {self.role}...')
+        raise AccountModelValidationError(f'Invalid role match for role {self.role}...')
 
     def get_account_move_choice_queryset(self):
         return self.coa_model.accountmodel_set.filter(

django_ledger/models/bill.py

@@ -481,14 +481,14 @@ class BillModelAbstract(
             ledger_model.clean_fields()
             self.ledger = ledger_model
 
+            if commit_ledger or commit:
+                self.ledger.save()
+
             if self.can_generate_bill_number():
                 self.generate_bill_number(commit=commit)
 
             self.clean()
 
-            if commit_ledger or commit:
-                self.ledger.save()
-
             if commit:
                 self.save()