django-ledger 0.5.5.4__py3-none-any.whl → 0.5.6.0__py3-none-any.whl

django_ledger/forms/transactions.py

@@ -10,7 +10,7 @@ Michael Noel <noel.michael87@gmail.com>
 from django.forms import ModelForm, modelformset_factory, BaseModelFormSet, TextInput, Select, ValidationError
 from django.utils.translation import gettext_lazy as _
 
-from django_ledger.io import check_tx_balance
+from django_ledger.io.io_core import check_tx_balance
 from django_ledger.models.accounts import AccountModel
 from django_ledger.models.journal_entry import JournalEntryModel
 from django_ledger.models.transactions import TransactionModel

django_ledger/io/__init__.py

@@ -6,6 +6,9 @@ Contributions to this module:
 Miguel Sanda <msanda@arrobalytics.com>
 """
 
-from django_ledger.io.io_mixin import *
+from django_ledger.io.io_digest import *
+from django_ledger.io.io_middleware import *
 from django_ledger.io.ratios import *
 from django_ledger.io.roles import *
+# due to circular import
+# from django_ledger.io.io_library import IOLibrary

django_ledger/io/{io_mixin.py → io_core.py}

@@ -4,6 +4,15 @@ Copyright© EDMA Group Inc licensed under the GPLv3 Agreement.
 
 Contributions to this module:
     * Miguel Sanda <msanda@arrobalytics.com>
+
+This module provides the building block interface for Django Ledger. The classes and functions contained in this module
+provide an interface to Django Ledger to create and manage Transactions into the Database. It also provides an
+optimized interface to push as much work as possible to the database without having to pull transactions from the
+database into the Python memory.
+
+The database records the individual transactions associated with each Journal Entry. However, this interface aggregates
+transactions during the digest method based on a specific request. The Python interpreter is responsible for applying
+accounting rules to the transactions associated with each Journal Entry so the appropriate account balances are computed.
 """
 from collections import namedtuple
 from dataclasses import dataclass
@@ -14,6 +23,7 @@ from random import choice
 from typing import List, Set, Union, Tuple, Optional, Dict
 from zoneinfo import ZoneInfo
 
+from django.conf import settings as global_settings
 from django.contrib.auth import get_user_model
 from django.core.exceptions import ValidationError, ObjectDoesNotExist
 from django.db.models import Sum, QuerySet
@@ -26,14 +36,15 @@ from django.utils.translation import gettext_lazy as _
 from django_ledger import settings
 from django_ledger.exceptions import InvalidDateInputError, TransactionNotInBalanceError
 from django_ledger.io import roles as roles_module
-from django_ledger.io.io_context import (
-    RoleContextManager, GroupContextManager, ActivityContextManager,
-    BalanceSheetStatementContextManager, IncomeStatementContextManager,
-    CashFlowStatementContextManager
+from django_ledger.io.io_middleware import (
+    AccountRoleIOMiddleware, AccountGroupIOMiddleware, JEActivityIOMiddleware,
+    BalanceSheetIOMiddleware, IncomeStatementIOMiddleware,
+    CashFlowStatementIOMiddleware
 )
 from django_ledger.io.io_digest import IODigestContextManager
 from django_ledger.io.ratios import FinancialRatioManager
 from django_ledger.models.utils import lazy_loader
+from django_ledger.settings import DJANGO_LEDGER_PDF_SUPPORT_ENABLED
 
 UserModel = get_user_model()
 
@@ -107,13 +118,6 @@ def validate_io_date(
         return
 
     if isinstance(dt, date):
-        # dt = make_aware(
-        #     value=datetime.combine(
-        #         dt,
-        #         datetime.min.time()
-        #     ),
-        #     timezone=ZoneInfo('UTC')
-        # )
         return dt
 
     elif isinstance(dt, datetime):
@@ -635,7 +639,7 @@ class IODatabaseMixIn:
         io_state['by_activity'] = by_activity
         io_state['by_tx_type'] = by_tx_type
 
-        io_result = self.python_digest(
+        io_result: IOResult = self.python_digest(
             user_model=user_model,
             accounts=accounts,
             role=role,
@@ -656,8 +660,10 @@ class IODatabaseMixIn:
         io_state['io_result'] = io_result
         io_state['accounts'] = io_result.accounts_digest
 
+        # IO Middleware...
+
         if process_roles:
-            roles_mgr = RoleContextManager(
+            roles_mgr = AccountRoleIOMiddleware(
                 io_data=io_state,
                 by_period=by_period,
                 by_unit=by_unit
@@ -672,7 +678,7 @@ class IODatabaseMixIn:
             income_statement,
             cash_flow_statement
         ]):
-            group_mgr = GroupContextManager(
+            group_mgr = AccountGroupIOMiddleware(
                 io_data=io_state,
                 by_period=by_period,
                 by_unit=by_unit
@@ -692,19 +698,19 @@ class IODatabaseMixIn:
             io_state = ratio_gen.digest()
 
         if process_activity:
-            activity_manager = ActivityContextManager(io_data=io_state, by_unit=by_unit, by_period=by_period)
+            activity_manager = JEActivityIOMiddleware(io_data=io_state, by_unit=by_unit, by_period=by_period)
             activity_manager.digest()
 
         if balance_sheet_statement:
-            balance_sheet_mgr = BalanceSheetStatementContextManager(io_data=io_state)
+            balance_sheet_mgr = BalanceSheetIOMiddleware(io_data=io_state)
             io_state = balance_sheet_mgr.digest()
 
         if income_statement:
-            income_statement_mgr = IncomeStatementContextManager(io_data=io_state)
+            income_statement_mgr = IncomeStatementIOMiddleware(io_data=io_state)
             io_state = income_statement_mgr.digest()
 
         if cash_flow_statement:
-            cfs = CashFlowStatementContextManager(io_data=io_state)
+            cfs = CashFlowStatementIOMiddleware(io_data=io_state)
             io_state = cfs.digest()
 
         return IODigestContextManager(io_state=io_state)
@@ -722,7 +728,7 @@ class IODatabaseMixIn:
         Creates JE from TXS list using provided account_id.
 
         TXS = List[{
-            'account_id': Account Database UUID
+            'account': Account Database UUID
             'tx_type': credit/debit,
             'amount': Decimal/Float/Integer,
             'description': string,
@@ -743,12 +749,32 @@ class IODatabaseMixIn:
         JournalEntryModel = lazy_loader.get_journal_entry_model()
         TransactionModel = lazy_loader.get_txs_model()
 
-        # if isinstance(self, lazy_loader.get_entity_model()):
-
         # Validates that credits/debits balance.
         check_tx_balance(je_txs, perform_correction=False)
         je_timestamp = validate_io_date(dt=je_timestamp)
 
+        entity_model = self.get_entity_model_from_io()
+
+        if entity_model.last_closing_date:
+            if isinstance(je_timestamp, datetime):
+                if entity_model.last_closing_date >= je_timestamp.date():
+                    raise IOValidationError(
+                        message=_(
+                            f'Cannot commit transactions. The journal entry date {je_timestamp} is on a closed period.')
+                    )
+            elif isinstance(je_timestamp, date):
+                if entity_model.last_closing_date >= je_timestamp:
+                    raise IOValidationError(
+                        message=_(
+                            f'Cannot commit transactions. The journal entry date {je_timestamp} is on a closed period.')
+                    )
+
+        if self.is_ledger_model():
+            if self.is_locked():
+                raise IOValidationError(
+                    message=_('Cannot commit on locked ledger')
+                )
+
         # if calling from EntityModel must pass an instance of LedgerModel...
         if all([
             isinstance(self, lazy_loader.get_entity_model()),
@@ -836,7 +862,7 @@ class IOReportMixIn:
                              to_date: Union[date, datetime],
                              user_model: Optional[UserModel] = None,
                              txs_queryset: Optional[QuerySet] = None,
-                             **kwargs: Dict) -> Union[IODigestContextManager, Tuple[QuerySet, Dict]]:
+                             **kwargs: Dict) -> IODigestContextManager:
         return self.digest(
             user_model=user_model,
             to_date=to_date,
@@ -854,7 +880,13 @@ class IOReportMixIn:
                                     user_model: Optional[UserModel] = None,
                                     save_pdf: bool = False,
                                     **kwargs
-                                    ):
+                                    ) -> IODigestContextManager:
+
+        if not DJANGO_LEDGER_PDF_SUPPORT_ENABLED:
+            raise IOValidationError(
+                message=_('PDF support not enabled. Install PDF support from Pipfile.')
+            )
+
         io_digest = self.digest_balance_sheet(
             to_date=to_date,
             user_model=user_model,
@@ -870,7 +902,7 @@ class IOReportMixIn:
             report_subtitle=subtitle
         )
         if save_pdf:
-            base_dir = Path(settings.BASE_DIR) if not filepath else Path(filepath)
+            base_dir = Path(global_settings.BASE_DIR) if not filepath else Path(filepath)
             filename = report.get_pdf_filename() if not filename else filename
             filepath = base_dir.joinpath(filename)
             report.create_pdf_report()
@@ -882,7 +914,7 @@ class IOReportMixIn:
                                 to_date: Union[date, datetime],
                                 user_model: Optional[UserModel] = None,
                                 txs_queryset: Optional[QuerySet] = None,
-                                **kwargs) -> Union[IODigestContextManager, Tuple[QuerySet, Dict]]:
+                                **kwargs) -> IODigestContextManager:
         return self.digest(
             user_model=user_model,
             from_date=from_date,
@@ -904,6 +936,11 @@ class IOReportMixIn:
                              save_pdf: bool = False,
                              **kwargs
                              ):
+        if not DJANGO_LEDGER_PDF_SUPPORT_ENABLED:
+            raise IOValidationError(
+                message=_('PDF support not enabled. Install PDF support from Pipfile.')
+            )
+
         io_digest = self.digest_income_statement(
             from_date=from_date,
             to_date=to_date,
@@ -920,7 +957,7 @@ class IOReportMixIn:
             report_subtitle=subtitle
         )
         if save_pdf:
-            base_dir = Path(settings.BASE_DIR) if not filepath else Path(filepath)
+            base_dir = Path(global_settings.BASE_DIR) if not filepath else Path(filepath)
             filename = report.get_pdf_filename() if not filename else filename
             filepath = base_dir.joinpath(filename)
             report.create_pdf_report()
@@ -930,9 +967,9 @@ class IOReportMixIn:
     def digest_cash_flow_statement(self,
                                    from_date: Union[date, datetime],
                                    to_date: Union[date, datetime],
-                                   user_model: UserModel,
+                                   user_model: Optional[UserModel] = None,
                                    txs_queryset: Optional[QuerySet] = None,
-                                   **kwargs) -> Union[IODigestContextManager, Tuple[QuerySet, Dict]]:
+                                   **kwargs) -> IODigestContextManager:
         return self.digest(
             user_model=user_model,
             from_date=from_date,
@@ -953,6 +990,11 @@ class IOReportMixIn:
                                 save_pdf: bool = False,
                                 **kwargs):
 
+        if not DJANGO_LEDGER_PDF_SUPPORT_ENABLED:
+            raise IOValidationError(
+                message=_('PDF support not enabled. Install PDF support from Pipfile.')
+            )
+
         io_digest = self.digest_cash_flow_statement(
             from_date=from_date,
             to_date=to_date,
@@ -969,13 +1011,30 @@ class IOReportMixIn:
             report_subtitle=subtitle
         )
         if save_pdf:
-            base_dir = Path(settings.BASE_DIR) if not filepath else Path(filepath)
+            base_dir = Path(global_settings.BASE_DIR) if not filepath else Path(filepath)
             filename = report.get_pdf_filename() if not filename else filename
             filepath = base_dir.joinpath(filename)
             report.create_pdf_report()
             report.output(filepath)
         return report
 
+    def digest_financial_statements(self,
+                                    from_date: Union[date, datetime],
+                                    to_date: Union[date, datetime],
+                                    user_model: Optional[UserModel] = None,
+                                    **kwargs) -> IODigestContextManager:
+
+        return self.digest(
+            from_date=from_date,
+            to_date=to_date,
+            user_model=user_model,
+            balance_sheet_statement=True,
+            income_statement=True,
+            cash_flow_statement=True,
+            as_io_digest=True,
+            **kwargs
+        )
+
     def get_financial_statements(self,
                                  from_date: Union[date, datetime],
                                  to_date: Union[date, datetime],
@@ -985,14 +1044,15 @@ class IOReportMixIn:
                                  filepath: Optional[Path] = None,
                                  **kwargs) -> ReportTuple:
 
-        io_digest = self.digest(
+        if not DJANGO_LEDGER_PDF_SUPPORT_ENABLED:
+            raise IOValidationError(
+                message=_('PDF support not enabled. Install PDF support from Pipfile.')
+            )
+
+        io_digest = self.digest_financial_statements(
             from_date=from_date,
             to_date=to_date,
             user_model=user_model,
-            balance_sheet_statement=True,
-            income_statement=True,
-            cash_flow_statement=True,
-            as_io_digest=True,
             **kwargs
         )
 
@@ -1019,7 +1079,7 @@ class IOReportMixIn:
         )
 
         if save_pdf:
-            base_dir = Path(settings.BASE_DIR) if not filepath else Path(filepath)
+            base_dir = Path(global_settings.BASE_DIR) if not filepath else Path(filepath)
             bs_report.create_pdf_report()
             bs_report.output(base_dir.joinpath(bs_report.get_pdf_filename(dt_strfmt=dt_strfmt)))
 

django_ledger/io/io_digest.py

@@ -1,3 +1,10 @@
+"""
+Django Ledger created by Miguel Sanda <msanda@arrobalytics.com>.
+Copyright© EDMA Group Inc licensed under the GPLv3 Agreement.
+
+Contributions to this module:
+    * Miguel Sanda <msanda@arrobalytics.com>
+"""
 from collections import defaultdict
 from datetime import date
 from typing import Dict, Optional
@@ -114,6 +121,14 @@ class IODigestContextManager:
                     'IO Digest does not have cash flow statement information available.'
                 )
 
+    # All Available Statements
+    def get_financial_statements_data(self) -> Dict:
+        return {
+            'balance_sheet': self.get_balance_sheet_data() if self.has_balance_sheet() else None,
+            'income_statement': self.get_income_statement_data() if self.has_income_statement() else None,
+            'cash_flow_statement': self.get_cash_flow_statement_data() if self.has_cash_flow_statement() else None,
+        }
+
     # CLOSING ENTRIES...
 
     def get_closing_entry_data(self):

django_ledger/io/{data_generator.py → io_generator.py}

@@ -4,8 +4,18 @@ Copyright© EDMA Group Inc licensed under the GPLv3 Agreement.
 
 Contributions to this module:
 Miguel Sanda <msanda@arrobalytics.com>
-"""
 
+This is a random data generator module used during the testing of the API and for Educational purposes.
+
+The class EntityDataGenerator will only work on new entities that contain no Transactions. This is with the intention
+of avoiding unintentional commingling with an actual EntityModel with production data and the data generated randomly.
+
+This class will conveniently create a Chart of Accounts and populate the database will Bills, Invoices and various
+other Transactions. The user will be able to immediately browse the Entity data by clicking on the newly created entity's
+details page.
+
+All data generated is random and fake, not related to any other entity data.
+"""
 from datetime import date, timedelta, datetime
 from decimal import Decimal
 from itertools import groupby
@@ -15,12 +25,13 @@ from typing import Union, Optional
 
 from django.core.exceptions import ImproperlyConfigured, ValidationError
 from django.utils.timezone import localtime, localdate
+from django.utils.translation import gettext_lazy as _
 
 from django_ledger.io.roles import (INCOME_OPERATIONAL, ASSET_CA_INVENTORY, COGS, ASSET_CA_CASH, ASSET_CA_PREPAID,
                                     LIABILITY_CL_DEFERRED_REVENUE, EXPENSE_OPERATIONAL, EQUITY_CAPITAL,
                                     ASSET_CA_RECEIVABLES, LIABILITY_CL_ACC_PAYABLE)
 from django_ledger.models import (EntityModel, TransactionModel, VendorModel, CustomerModel,
-                                  EntityUnitModel, BankAccountModel, LedgerModel, UnitOfMeasureModel, ItemModel,
+                                  EntityUnitModel, BankAccountModel, UnitOfMeasureModel, ItemModel,
                                   BillModel, ItemTransactionModel, InvoiceModel,
                                   EstimateModel, LoggingMixIn, InvoiceModelValidationError, ChartOfAccountModel)
 from django_ledger.utils import (generate_random_sku, generate_random_upc, generate_random_item_id)
@@ -34,7 +45,28 @@ except ImportError:
     FAKER_IMPORTED = False
 
 
+class EntityModelValidationError(ValidationError):
+    pass
+
+
 class EntityDataGenerator(LoggingMixIn):
+    """
+    A random data generator for Entity Models. Requires a user to me the entity model administrator.
+
+    Attributes
+    ----------
+    user_model : UserModel
+        The Django user model that administers the entity.
+    entity_model : EntityModel
+        The Entity model to populate.
+    start_dttm: datetime
+        The start datetime for new transactions. All transactions will be posted no earlier than this date.
+    capital_contribution: Decimal
+        The initial capital contribution amount for the Entity Model. This will help fund the entity.
+    days_forward: int
+        The number of days to span from the start_dttm for new transactions.
+
+    """
 
     def __init__(self,
                  user_model,
@@ -50,6 +82,11 @@ class EntityDataGenerator(LoggingMixIn):
         if not FAKER_IMPORTED:
             raise ImproperlyConfigured('Must install Faker library to generate random data.')
 
+        if entity_model.admin != user_model:
+            raise EntityModelValidationError(
+                message=_(f'User {user_model} must have admin privileges for entity model {entity_model}.')
+            )
+
         self.fk = Faker(['en_US'])
         self.fk.add_provider(company)
         self.fk.add_provider(address)
@@ -97,7 +134,7 @@ class EntityDataGenerator(LoggingMixIn):
     def get_logger_name(self):
         return self.entity_model.slug
 
-    def populate_entity(self):
+    def populate_entity(self, force_populate: bool = False):
 
         self.logger.info('Checking for existing transactions...')
         txs_qs = TransactionModel.objects.for_entity(
@@ -105,9 +142,10 @@ class EntityDataGenerator(LoggingMixIn):
             user_model=self.user_model
         )
 
-        if txs_qs.count() > 0:
-            raise ValidationError(
-                f'Cannot populate random data on {self.entity_model.name} because it already has existing Transactions')
+        if txs_qs.count() > 0 and not force_populate:
+            raise EntityModelValidationError(
+                f'Cannot populate random data on {self.entity_model.name} because it already has existing Transactions'
+            )
 
         self.create_coa()
         self.logger.info(f'Pulling Entity {self.entity_model} accounts...')
@@ -156,9 +194,14 @@ class EntityDataGenerator(LoggingMixIn):
 
     def create_coa(self):
         entity_model = self.entity_model
-        coa_model = entity_model.create_chart_of_accounts(assign_as_default=True, commit=True)
+
+        if not self.entity_model.has_default_coa():
+            coa_model = entity_model.create_chart_of_accounts(assign_as_default=True, commit=True)
+        else:
+            coa_model = entity_model.get_default_coa()
+
         entity_model.populate_default_coa(coa_model=coa_model, activate_accounts=True)
-        self.default_coa = entity_model.default_coa
+        self.default_coa = coa_model
 
     def create_entity_units(self, nb_units: int = None):
         self.logger.info(f'Creating entity units...')