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

django_ledger/models/journal_entry.py

@@ -25,6 +25,7 @@ The JournalEntryModel is also responsible for validating the Financial Activity
 business. Whenever an account with ASSET_CA_CASH role is involved in a Journal Entry (see roles for more details), the
 JE is responsible for programmatically determine the kind of operation for the JE (Operating, Financing, Investing).
 """
+import warnings
 from datetime import date, datetime
 from decimal import Decimal
 from enum import Enum
@@ -41,6 +42,7 @@ from django.urls import reverse
 from django.utils.timezone import localtime
 from django.utils.translation import gettext_lazy as _
 
+from django_ledger.io import roles
 from django_ledger.io.io_core import get_localtime
 from django_ledger.io.roles import (
     ASSET_CA_CASH, GROUP_CFS_FIN_DIVIDENDS, GROUP_CFS_FIN_ISSUING_EQUITY,
@@ -50,6 +52,7 @@ from django_ledger.io.roles import (
     validate_roles
 )
 from django_ledger.models.accounts import CREDIT, DEBIT
+from django_ledger.models.deprecations import deprecated_entity_slug_behavior
 from django_ledger.models.entity import EntityStateModel, EntityModel
 from django_ledger.models.ledger import LedgerModel
 from django_ledger.models.mixins import CreateUpdateMixIn
@@ -59,13 +62,12 @@ from django_ledger.models.signals import (
     journal_entry_posted,
     journal_entry_unposted
 )
-from django_ledger.models.transactions import TransactionModelQuerySet, TransactionModel
+from django_ledger.models.transactions import TransactionModelQuerySet
 from django_ledger.settings import (
     DJANGO_LEDGER_JE_NUMBER_PREFIX,
     DJANGO_LEDGER_DOCUMENT_NUMBER_PADDING,
-    DJANGO_LEDGER_JE_NUMBER_NO_UNIT_PREFIX
+    DJANGO_LEDGER_JE_NUMBER_NO_UNIT_PREFIX, DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR
 )
-from django_ledger.io import roles
 
 
 class JournalEntryValidationError(ValidationError):
@@ -82,7 +84,33 @@ class JournalEntryModelQuerySet(QuerySet):
     locked entries, and querying entries associated with specific ledgers.
     """
 
-    def create(self, verify_on_save: bool = False, force_create: bool = False, **kwargs):
+    def for_user(self, user_model) -> 'JournalEntryModelQuerySet':
+        """
+        Filters the JournalEntryModel queryset for the given user.
+
+        - Superusers will have access to all journal entries.
+        - Other authenticated users will only see entries for entities where
+          they are admins or managers.
+
+        Parameters
+        ----------
+        user_model : UserModel
+            An authenticated Django user object.
+
+        Returns
+        -------
+        JournalEntryModelQuerySet
+            A filtered queryset restricted by the user's entity relationships.
+        """
+        if user_model.is_superuser:
+            return self
+
+        return self.filter(
+            Q(ledger__entity__admin=user_model) |  # Entries for entities where the user is admin
+            Q(ledger__entity__managers__in=[user_model])  # Entries for entities where the user is a manager
+        )
+
+    def create(self, verify_on_save: bool = False, force_create: bool = False, **kwargs) -> 'JournalEntryModelQuerySet':
         """
         Creates a new Journal Entry while enforcing business logic validations.
 
@@ -124,7 +152,7 @@ class JournalEntryModelQuerySet(QuerySet):
         obj.save(force_insert=True, using=self.db, verify=verify_on_save)
         return obj
 
-    def posted(self):
+    def posted(self) -> 'JournalEntryModelQuerySet':
         """
         Filters the QuerySet to include only "posted" Journal Entries.
 
@@ -135,7 +163,7 @@ class JournalEntryModelQuerySet(QuerySet):
         """
         return self.filter(posted=True)
 
-    def unposted(self):
+    def unposted(self) -> 'JournalEntryModelQuerySet':
         """
         Filters the QuerySet to include only "unposted" Journal Entries.
 
@@ -146,7 +174,7 @@ class JournalEntryModelQuerySet(QuerySet):
         """
         return self.filter(posted=False)
 
-    def locked(self):
+    def locked(self) -> 'JournalEntryModelQuerySet':
         """
         Filters the QuerySet to include only "locked" Journal Entries.
 
@@ -157,7 +185,7 @@ class JournalEntryModelQuerySet(QuerySet):
         """
         return self.filter(locked=True)
 
-    def unlocked(self):
+    def unlocked(self) -> 'JournalEntryModelQuerySet':
         """
         Filters the QuerySet to include only "unlocked" Journal Entries.
 
@@ -168,7 +196,7 @@ class JournalEntryModelQuerySet(QuerySet):
         """
         return self.filter(locked=False)
 
-    def for_ledger(self, ledger_pk: Union[str, UUID, LedgerModel]):
+    def for_ledger(self, ledger_pk: Union[str, UUID, LedgerModel]) -> 'JournalEntryModelQuerySet':
         """
         Filters the QuerySet to include Journal Entries associated with a specific Ledger.
 
@@ -223,34 +251,8 @@ class JournalEntryModelManager(Manager):
             txs_count=Count('transactionmodel')  # Annotates the count of transactions
         )
 
-    def for_user(self, user_model) -> JournalEntryModelQuerySet:
-        """
-        Filters the JournalEntryModel queryset for the given user.
-
-        - Superusers will have access to all journal entries.
-        - Other authenticated users will only see entries for entities where
-          they are admins or managers.
-
-        Parameters
-        ----------
-        user_model : UserModel
-            An authenticated Django user object.
-
-        Returns
-        -------
-        JournalEntryModelQuerySet
-            A filtered queryset restricted by the user's entity relationships.
-        """
-        qs = self.get_queryset()
-        if user_model.is_superuser:
-            return qs
-
-        return qs.filter(
-            Q(ledger__entity__admin=user_model) |  # Entries for entities where the user is admin
-            Q(ledger__entity__managers__in=[user_model])  # Entries for entities where the user is a manager
-        )
-
-    def for_entity(self, entity_slug: Union[str, EntityModel], user_model) -> JournalEntryModelQuerySet:
+    @deprecated_entity_slug_behavior
+    def for_entity(self, entity_model: EntityModel | str | UUID = None, **kwargs) -> JournalEntryModelQuerySet:
         """
         Filters the JournalEntryModel queryset for a specific entity and user.
 
@@ -260,24 +262,36 @@ class JournalEntryModelManager(Manager):
 
         Parameters
         ----------
-        entity_slug : str or EntityModel
+        entity_model : str or EntityModel
             The slug of the entity (or an instance of `EntityModel`) used for filtering.
-        user_model : UserModel
-            An authenticated Django user object.
-
         Returns
         -------
         JournalEntryModelQuerySet
             A customized queryset containing journal entries associated with the
             given entity and restricted by the user's access permissions.
         """
-        qs = self.for_user(user_model)
-
-        # Handle the `entity_slug` as either a string or an EntityModel instance
-        if isinstance(entity_slug, EntityModel):
-            return qs.filter(ledger__entity=entity_slug)
+        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
+            )
+            if DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR:
+                qs = qs.for_user(kwargs['user_model'])
 
-        return qs.filter(ledger__entity__slug__iexact=entity_slug)  # Case-insensitive slug match
+        if isinstance(entity_model, EntityModel):
+            qs = qs.filter(ledger__entity=entity_model)
+        elif isinstance(entity_model, str):
+            qs = qs.filter(ledger__entity__slug__exact=entity_model)
+        elif isinstance(entity_model, UUID):
+            qs = qs.filter(ledger__entity_id=entity_model)
+        else:
+            raise JournalEntryValidationError(
+                message='Must provide EntityModel, slug or UUID',
+            )
+        return qs
 
 
 class ActivityEnum(Enum):

django_ledger/models/ledger.py

@@ -23,20 +23,22 @@ layer as possible in order to minimize the amount of data being pulled for analy
 The Django Ledger core model follows the following structure:
 EntityModel -< LedgerModel -< JournalEntryModel -< TransactionModel
 """
+import warnings
 from datetime import date
 from string import ascii_lowercase, digits
 from typing import Optional
-from uuid import uuid4
+from uuid import uuid4, UUID
 
 from django.core.exceptions import ValidationError, ObjectDoesNotExist
 from django.core.serializers.json import DjangoJSONEncoder
 from django.db import models
-from django.db.models import Q, Min, F, Count
+from django.db.models import Q, Min, F, Count, Manager, QuerySet
 from django.urls import reverse
 from django.utils.translation import gettext_lazy as _
 
 from django_ledger.io.io_core import IOMixIn
 from django_ledger.models import lazy_loader
+from django_ledger.models.deprecations import deprecated_entity_slug_behavior
 from django_ledger.models.mixins import CreateUpdateMixIn
 from django_ledger.models.signals import (
     ledger_posted,
@@ -46,6 +48,7 @@ from django_ledger.models.signals import (
     ledger_hidden,
     ledger_unhidden
 )
+from django_ledger.settings import DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR
 
 LEDGER_ID_CHARS = ascii_lowercase + digits
 
@@ -54,75 +57,130 @@ class LedgerModelValidationError(ValidationError):
     pass
 
 
-class LedgerModelQuerySet(models.QuerySet):
+class LedgerModelQuerySet(QuerySet):
     """
-    Custom defined LedgerModel QuerySet.
+    Custom QuerySet for filtering LedgerModel instances based on specific fields.
+
+    Provides predefined filtering methods to simplify working with ledger data.
+    These filters allow querying for entries that are locked, unlocked, posted,
+    unposted, hidden, visible, or current.
+
+    Methods
+    -------
+    locked()
+        Filters instances based on the 'locked' attribute set to `True`.
+    unlocked()
+        Filters instances based on the 'locked' attribute set to `False`.
+    posted()
+        Filters a queryset to include only posted entries with 'posted' set to `True`.
+    unposted()
+        Filters a queryset to include only unposted entries with 'posted' set to `False`.
+    hidden()
+        Filters a queryset to include only items marked as hidden.
+    visible()
+        Filters out hidden items from the queryset.
+    current()
+        Filters the queryset to include items where the earliest timestamp
+        comes after the entity's last closing date or is null.
     """
 
-    def locked(self):
+    def for_user(self, user_model) -> 'LedgerModelQuerySet':
+        if user_model.is_superuser:
+            return self
+        return self.filter(
+            Q(entity__admin=user_model) |
+            Q(entity__managers__in=[user_model])
+        )
+
+    def locked(self) -> 'LedgerModelQuerySet':
         """
-        Filters the QuerySet to only locked LedgerModel.
+        Filters instances based on the 'locked' attribute.
+
+        This method returns a new instance where the 'locked' attribute is set to `True`.
 
         Returns
         -------
         LedgerModelQuerySet
-            A QuerySet with applied filters.
+            A new instance filtered with the attribute 'locked' set to `True`.
         """
         return self.filter(locked=True)
 
-    def unlocked(self):
+    def unlocked(self) -> 'LedgerModelQuerySet':
         """
-        Filters the QuerySet to only un-locked LedgerModel.
+        Filters and returns an instance where the `locked` attribute is set to `False`.
 
         Returns
         -------
         LedgerModelQuerySet
-            A QuerySet with applied filters.
+            A new or modified instance of the object with the filter applied.
         """
         return self.filter(locked=False)
 
-    def posted(self):
+    def posted(self) -> 'LedgerModelQuerySet':
         """
-        Filters the QuerySet to only posted LedgerModel.
+        Filters a queryset to include only posted entries.
 
         Returns
         -------
         LedgerModelQuerySet
-            A QuerySet with applied filters.
+            A new queryset instance containing only objects with
+            the `posted` field set to True.
         """
         return self.filter(posted=True)
 
-    def unposted(self):
+    def unposted(self) -> 'LedgerModelQuerySet':
         """
-        Filters the QuerySet to only un-posted LedgerModel.
+        Filters a queryset or a similar iterable-like object to include only items that
+        have the attribute `posted` set to `True`. This method returns a new instance
+        containing the filtered results.
 
         Returns
         -------
         LedgerModelQuerySet
-            A QuerySet with applied filters.
+            A new instance containing only the filtered results with `posted` set to True.
         """
         return self.filter(posted=True)
 
-    def hidden(self):
+    def hidden(self) -> 'LedgerModelQuerySet':
+        """
+        Filters the queryset to include only objects marked as hidden.
+
+        Returns
+        -------
+        LedgerModelQuerySet
+            A filtered queryset containing only objects with the `hidden` attribute
+            set to True.
+        """
         return self.filter(hidden=True)
 
-    def visible(self):
+    def visible(self) -> 'LedgerModelQuerySet':
+        """
+        Filters out hidden items from the queryset.
+
+        Ensures that only items with the `hidden` attribute set to `False`
+        are included in the returned queryset.
+
+        Returns
+        -------
+        LedgerModelQuerySet
+            A queryset containing only visible items.
+        """
         return self.filter(hidden=False)
 
-    def current(self):
+    def current(self) -> 'LedgerModelQuerySet':
         return self.filter(
             Q(earliest_timestamp__date__gt=F('entity__last_closing_date'))
             | Q(earliest_timestamp__isnull=True)
         )
 
 
-class LedgerModelManager(models.Manager):
+class LedgerModelManager(Manager):
     """
     A custom-defined LedgerModelManager that implements custom QuerySet methods related to the LedgerModel.
     """
 
-    def get_queryset(self):
-        qs = super().get_queryset()
+    def get_queryset(self) -> LedgerModelQuerySet:
+        qs = LedgerModelQuerySet(self.model, using=self._db)
         return qs.select_related('entity').annotate(
             Count('journal_entries'),
             _entity_slug=F('entity__slug'),
@@ -130,40 +188,46 @@ class LedgerModelManager(models.Manager):
                                    filter=Q(journal_entries__posted=True)),
         )
 
-    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, user_model):
+    @deprecated_entity_slug_behavior
+    def for_entity(self, entity_model: 'EntityModel | str | UUID' = None, **kwargs) -> LedgerModelQuerySet:
         """
         Returns a QuerySet of LedgerModels 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
         -------
         LedgerModelQuerySet
             A Filtered LedgerModelQuerySet.
         """
-        qs = self.for_user(user_model)
-        if isinstance(entity_slug, lazy_loader.get_entity_model()):
-            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 LedgerModelValidationError(
+                message='Must provide entity slug, EntityModel, or UUID parameter'
+            )
+        return qs
 
 
 class LedgerModelAbstract(CreateUpdateMixIn, IOMixIn):

django_ledger/models/mixins.py

@@ -106,7 +106,7 @@ class ContactInfoMixIn(models.Model):
     phone: str
         A string used to document the contact phone.
     """
-    address_1 = models.CharField(max_length=70, verbose_name=_('Address Line 1'))
+    address_1 = models.CharField(max_length=70, verbose_name=_('Address Line 1'), null=True, blank=True)
     address_2 = models.CharField(null=True, blank=True, max_length=70, verbose_name=_('Address Line 2'))
     city = models.CharField(null=True, blank=True, max_length=70, verbose_name=_('City'))
     state = models.CharField(null=True, blank=True, max_length=70, verbose_name=_('State/Province'))
@@ -129,6 +129,10 @@ class ContactInfoMixIn(models.Model):
             return f'{self.city}, {self.state}. {self.zip_code}. {self.country}'
 
     def clean(self):
+        if self.address_2 and not self.address_1:
+            raise ValidationError(
+                {'address_1': _('Address line 1 is required if address_2 is provided.')},
+            )
         super().clean()
 
 
@@ -231,8 +235,6 @@ class AccrualMixIn(models.Model):
                                         null=True,
                                         verbose_name=_('Prepaid Account'),
                                         related_name=f'{REL_NAME_PREFIX}_prepaid_account')
-
-    # todo: rename to payable account...
     unearned_account = models.ForeignKey('django_ledger.AccountModel',
                                          on_delete=models.RESTRICT,
                                          blank=True,

django_ledger/models/purchase_order.py

@@ -12,10 +12,11 @@ starts in draft model by default and goes through different states including InR
 Void. The PurchaseOrderModel also keeps track of when these states take place.
 
 """
+import warnings
 from datetime import date
 from string import ascii_uppercase, digits
 from typing import Tuple, List, Union, Optional, 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
@@ -30,6 +31,7 @@ from django.utils.translation import gettext_lazy as _
 
 from django_ledger.io.io_core import get_localdate
 from django_ledger.models.bill import BillModel, BillModelQuerySet
+from django_ledger.models.deprecations import deprecated_entity_slug_behavior
 from django_ledger.models.entity import EntityModel
 from django_ledger.models.items import ItemTransactionModel, ItemTransactionModelQuerySet, ItemModelQuerySet, ItemModel
 from django_ledger.models.mixins import CreateUpdateMixIn, MarkdownNotesMixIn, ItemizeMixIn
@@ -42,7 +44,8 @@ from django_ledger.models.signals import (
     po_status_in_review
 )
 from django_ledger.models.utils import lazy_loader
-from django_ledger.settings import DJANGO_LEDGER_DOCUMENT_NUMBER_PADDING, DJANGO_LEDGER_PO_NUMBER_PREFIX
+from django_ledger.settings import DJANGO_LEDGER_DOCUMENT_NUMBER_PADDING, DJANGO_LEDGER_PO_NUMBER_PREFIX, \
+    DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR
 
 PO_NUMBER_CHARS = ascii_uppercase + digits
 
@@ -55,9 +58,17 @@ class PurchaseOrderModelValidationError(ValidationError):
 
 class PurchaseOrderModelQuerySet(QuerySet):
     """
-    A custom defined PurchaseOrderModel QuerySet.
+    A custom-defined PurchaseOrderModel QuerySet.
     """
 
+    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):
         """
         Filters the QuerySet to include Approved PurchaseOrderModels only.
@@ -105,16 +116,8 @@ class PurchaseOrderModelManager(Manager):
     A custom defined PurchaseOrderModel Manager.
     """
 
-    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, user_model) -> PurchaseOrderModelQuerySet:
+    @deprecated_entity_slug_behavior
+    def for_entity(self, entity_model: EntityModel | str | UUID = None, **kwargs) -> PurchaseOrderModelQuerySet:
         """
         Fetches a QuerySet of PurchaseOrderModel associated with a specific EntityModel & UserModel.
         May pass an instance of EntityModel or a String representing the EntityModel slug.
@@ -124,10 +127,29 @@ class PurchaseOrderModelManager(Manager):
         PurchaseOrderModelQuerySet
             A PurchaseOrderModelQuerySet with applied filters.
         """
-        qs = self.for_user(user_model)
-        if isinstance(entity_slug, EntityModel):
-            qs = qs.filter(entity=entity_slug)
-        return qs.filter(entity__slug__exact=entity_slug)
+
+        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
+            )
+            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 PurchaseOrderModelValidationError(
+                message='Entity slug must be either an EntityModel or a String representing the EntityModel slug',
+            )
+        return qs
 
 
 class PurchaseOrderModelAbstract(CreateUpdateMixIn,