django-ledger 0.7.10__py3-none-any.whl → 0.8.0__py3-none-any.whl

django_ledger/models/estimate.py

@@ -10,6 +10,7 @@ Once approved, the user may initiate purchase orders, bills and invoices that wi
 for tracking purposes. It is however not required to always have an EstimateModel, but recommended in order to be able
 to produce more specific financial reports associated with a specific scope of work.
 """
+import warnings
 from datetime import date
 from decimal import Decimal
 from string import ascii_uppercase, digits
@@ -27,7 +28,7 @@ from django.urls import reverse
 from django.utils.translation import gettext_lazy as _
 
 from django_ledger.io.io_core import get_localdate
-from django_ledger.models import BillModelQuerySet, InvoiceModelQuerySet
+from django_ledger.models import BillModelQuerySet, InvoiceModelQuerySet, lazy_loader, deprecated_entity_slug_behavior
 from django_ledger.models.customer import CustomerModel
 from django_ledger.models.entity import EntityModel, EntityStateModel
 from django_ledger.models.items import ItemTransactionModelQuerySet, ItemTransactionModel, ItemModelQuerySet, ItemModel
@@ -41,7 +42,8 @@ from django_ledger.models.signals import (
     estimate_status_completed,
     estimate_status_in_review
 )
-from django_ledger.settings import DJANGO_LEDGER_DOCUMENT_NUMBER_PADDING, DJANGO_LEDGER_ESTIMATE_NUMBER_PREFIX
+from django_ledger.settings import DJANGO_LEDGER_DOCUMENT_NUMBER_PADDING, DJANGO_LEDGER_ESTIMATE_NUMBER_PREFIX, \
+    DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR
 
 ESTIMATE_NUMBER_CHARS = ascii_uppercase + digits
 
@@ -57,6 +59,14 @@ class EstimateModelQuerySet(models.QuerySet):
     A custom-defined LedgerModelManager that implements custom QuerySet methods related to the EstimateModel.
     """
 
+    def for_user(self, user_model):
+        if user_model.is_superuser:
+            return self
+        return self.filter(
+            Q(entity__admin=user_model) |
+            Q(entity__managers__in=[user_model])
+        )
+
     def approved(self):
         """
         Approved Estimates or Sales Orders are those that have been approved or completed.
@@ -113,43 +123,62 @@ class EstimateModelQuerySet(models.QuerySet):
 
 class EstimateModelManager(models.Manager):
     """
-    A custom defined EstimateModelManager that that implements custom QuerySet methods related to the EstimateModel.
+    A custom-defined EstimateModelManager that that implements custom QuerySet methods related to the EstimateModel.
     """
 
-    def for_user(self, user_model):
-        qs = self.get_queryset()
-        if user_model.is_superuser:
-            return qs
-        return qs.filter(
-            Q(entity__admin=user_model) |
-            Q(entity__managers__in=[user_model])
-        )
-
-    def for_entity(self, entity_slug: Union[EntityModel, str], user_model):
+    @deprecated_entity_slug_behavior
+    def for_entity(self, entity_model: Union[EntityModel, str, UUID] = None, **kwargs) -> EstimateModelQuerySet:
         """
-        Fetches a QuerySet of EstimateModels associated with a specific EntityModel & UserModel.
-        May pass an instance of EntityModel or a String representing the EntityModel slug.
+        Filters the queryset based on the given entity model.
+
+        This method allows filtering the queryset by an `entity_model` parameter, which can
+        be of type `EntityModel`, `str`, or `UUID`. It also handles deprecated behavior if
+        `user_model` is passed in the `kwargs`.
 
         Parameters
         ----------
-        entity_slug: str or EntityModel
-            The entity slug or EntityModel used for filtering the QuerySet.
-        user_model
-            Logged in and authenticated django UserModel instance.
+        entity_model : EntityModel, str, UUID
+            Specifies the entity against which the queryset should be filtered. Accepts an
+            `EntityModel` instance, a string (representing the entity slug), or a UUID
+            (representing the entity ID).
+        **kwargs
+            Additional keyword arguments. Supports a deprecated `user_model` argument for
+            backward compatibility.
 
         Returns
         -------
-        EstimateModelQuerySet
-            Returns a EstimateModelQuerySet with applied filters.
+        QuerySet
+            A Django QuerySet filtered according to the given entity model.
+
+        Raises
+        ------
+        EstimateModelValidationError
+            If `entity_model` is of an unsupported type.
         """
-        qs = self.for_user(user_model)
-        if isinstance(entity_slug, EntityModel):
-            return qs.filter(
-                Q(entity=entity_slug)
+        EntityModel = lazy_loader.get_entity_model()
+
+        qs = self.get_queryset()
+        if 'user_model' in kwargs:
+            warnings.warn(
+                'user_model parameter is deprecated and will be removed in a future release. '
+                'Use for_user(user_model).for_entity(entity_model) instead to keep current behavior.',
+                DeprecationWarning,
+                stacklevel=2
             )
-        return qs.filter(
-            Q(entity__slug__exact=entity_slug)
-        )
+            if DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR:
+                qs = qs.for_user(kwargs['user_model'])
+
+        if isinstance(entity_model, EntityModel):
+            qs = qs.filter(entity=entity_model)
+        elif isinstance(entity_model, str):
+            qs = qs.filter(entity__slug__exact=entity_model)
+        elif isinstance(entity_model, UUID):
+            qs = qs.filter(entity_id=entity_model)
+        else:
+            raise EstimateModelValidationError(
+                message='entity_model must be either a string, UUID or an EntityModel'
+            )
+        return qs
 
 
 class EstimateModelAbstract(CreateUpdateMixIn,

django_ledger/models/invoice.py

@@ -16,11 +16,11 @@ ________
 >>> ledger_model, invoice_model = invoice_model.configure(entity_slug=entity_slug, user_model=user_model)
 >>> invoice_model.save()
 """
-
+import warnings
 from datetime import date, datetime
 from decimal import Decimal
 from typing import Union, Optional, Tuple, Dict
-from uuid import uuid4
+from uuid import uuid4, UUID
 
 from django.contrib.auth import get_user_model
 from django.core.exceptions import ValidationError, ObjectDoesNotExist
@@ -37,6 +37,7 @@ from django_ledger.models import (
     lazy_loader, ItemTransactionModelQuerySet,
     ItemModelQuerySet, ItemModel, QuerySet, Manager
 )
+from django_ledger.models.deprecations import deprecated_entity_slug_behavior
 from django_ledger.models.entity import EntityModel
 from django_ledger.models.mixins import (
     CreateUpdateMixIn, AccrualMixIn,
@@ -51,7 +52,8 @@ from django_ledger.models.signals import (
     invoice_status_canceled,
     invoice_status_void
 )
-from django_ledger.settings import DJANGO_LEDGER_DOCUMENT_NUMBER_PADDING, DJANGO_LEDGER_INVOICE_NUMBER_PREFIX
+from django_ledger.settings import DJANGO_LEDGER_DOCUMENT_NUMBER_PADDING, DJANGO_LEDGER_INVOICE_NUMBER_PREFIX, \
+    DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR
 
 UserModel = get_user_model()
 
@@ -176,6 +178,14 @@ class InvoiceModelQuerySet(QuerySet):
         """
         return self.filter(invoice_status__exact=InvoiceModel.INVOICE_STATUS_APPROVED)
 
+    def for_user(self, user_model):
+        if user_model.is_superuser:
+            return self
+        return self.filter(
+            Q(ledger__entity__admin=user_model) |
+            Q(ledger__entity__managers__in=[user_model])
+        )
+
 
 class InvoiceModelManager(Manager):
     """
@@ -183,48 +193,52 @@ class InvoiceModelManager(Manager):
     The default "get_queryset" has been overridden to refer the custom defined "InvoiceModelQuerySet"
     """
 
-    def get_queryset(self):
-        qs = super().get_queryset()
+    def get_queryset(self) -> InvoiceModelQuerySet:
+        qs = InvoiceModelQuerySet(self.model, using=self._db)
         return qs.select_related(
             'ledger',
             'ledger__entity'
         )
 
-    def for_user(self, user_model):
-        qs = self.get_queryset()
-        if user_model.is_superuser:
-            return qs
-        return qs.filter(
-            Q(ledger__entity__admin=user_model) |
-            Q(ledger__entity__managers__in=[user_model])
-        )
-
-    def for_entity(self, entity_slug, user_model) -> InvoiceModelQuerySet:
+    @deprecated_entity_slug_behavior
+    def for_entity(self, entity_model: EntityModel | str | UUID = None, **kwargs) -> InvoiceModelQuerySet:
         """
         Returns a QuerySet of InvoiceModels associated with a specific EntityModel & UserModel.
         May pass an instance of EntityModel or a String representing the EntityModel slug.
 
         Parameters
         ----------
-        entity_slug: str or EntityModel
+        entity_model: str or EntityModel
             The entity slug or EntityModel used for filtering the QuerySet.
-        user_model
-            The request UserModel to check for privileges.
 
         Returns
         -------
         InvoiceModelQuerySet
             A Filtered InvoiceModelQuerySet.
         """
-        qs = self.for_user(user_model)
-        if isinstance(entity_slug, EntityModel):
-            return qs.filter(ledger__entity=entity_slug)
-        elif isinstance(entity_slug, str):
-            return qs.filter(ledger__entity__slug__exact=entity_slug)
+        qs = self.get_queryset()
 
-    def for_entity_unpaid(self, entity_slug, user_model):
-        qs = self.for_entity(entity_slug=entity_slug, user_model=user_model)
-        return qs.approved()
+        if 'user_model' in kwargs:
+            warnings.warn(
+                'user_model parameter is deprecated and will be removed in a future release. '
+                'Use for_user(user_model).for_entity(entity_model) instead to keep current behavior.',
+                DeprecationWarning,
+                stacklevel=2
+            )
+            if DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR:
+                qs = qs.for_user(kwargs['user_model'])
+
+        if isinstance(entity_model, EntityModel):
+            qs = qs.filter(ledger__entity=entity_model)
+        elif isinstance(entity_model, UUID):
+            qs = qs.filter(ledger__entity_id=entity_model)
+        elif isinstance(entity_model, str):
+            qs = qs.filter(ledger__entity__slug__exact=entity_model)
+        else:
+            raise InvoiceModelValidationError(
+                message='Must provide either a string, UUID or an EntityModel',
+            )
+        return qs
 
 
 class InvoiceModelAbstract(
@@ -309,6 +323,11 @@ class InvoiceModelAbstract(
     """
 
     uuid = models.UUIDField(default=uuid4, editable=False, primary_key=True)
+    entity_model = models.ForeignKey('django_ledger.EntityModel',
+                                     on_delete=models.CASCADE,
+                                     null=True,
+                                     blank=True,
+                                     editable=False)
     invoice_number = models.SlugField(max_length=20,
                                       editable=False,
                                       verbose_name=_('Invoice Number'))
@@ -320,14 +339,20 @@ class InvoiceModelAbstract(
 
     cash_account = models.ForeignKey('django_ledger.AccountModel',
                                      on_delete=models.RESTRICT,
+                                     null=True,
+                                     blank=True,
                                      verbose_name=_('Cash Account'),
                                      related_name=f'{REL_NAME_PREFIX}_cash_account')
     prepaid_account = models.ForeignKey('django_ledger.AccountModel',
                                         on_delete=models.RESTRICT,
+                                        null=True,
+                                        blank=True,
                                         verbose_name=_('Prepaid Account'),
                                         related_name=f'{REL_NAME_PREFIX}_prepaid_account')
     unearned_account = models.ForeignKey('django_ledger.AccountModel',
                                          on_delete=models.RESTRICT,
+                                         null=True,
+                                         blank=True,
                                          verbose_name=_('Unearned Account'),
                                          related_name=f'{REL_NAME_PREFIX}_unearned_account')
 
@@ -567,7 +592,8 @@ class InvoiceModelAbstract(
         """
         return f'Invoice {self.invoice_number} account adjustment.'
 
-    def get_migration_data(self, queryset: Optional[ItemTransactionModelQuerySet] = None) -> ItemTransactionModelQuerySet:
+    def get_migration_data(self,
+                           queryset: Optional[ItemTransactionModelQuerySet] = None) -> ItemTransactionModelQuerySet:
 
         """
         Fetches necessary item transaction data to perform a migration into the LedgerModel.
@@ -600,7 +626,8 @@ class InvoiceModelAbstract(
             'total_amount').annotate(
             account_unit_total=Sum('total_amount'))
 
-    def update_amount_due(self, itemtxs_qs: Optional[ItemTransactionModelQuerySet] = None) -> ItemTransactionModelQuerySet:
+    def update_amount_due(self,
+                          itemtxs_qs: Optional[ItemTransactionModelQuerySet] = None) -> ItemTransactionModelQuerySet:
         """
         Updates the InvoiceModel amount due.
 
@@ -1835,5 +1862,8 @@ def invoicemodel_presave(instance: InvoiceModel, **kwargs):
     if instance.can_generate_invoice_number():
         instance.generate_invoice_number(commit=False)
 
+    if not instance.entity_model_id:
+        instance.entity_model = instance.ledger.entity
+
 
 pre_save.connect(receiver=invoicemodel_presave, sender=InvoiceModel)