Refactor transaction queries and add account balance utility

Updated transaction filtering methods to validate input types and support AccountModel, UUID, and string formats. Added new utility methods for cleared and reconciled transaction queries. Introduced an account balance retrieval method in the entity model for better account insights.

Author: elarroba

django_ledger/models/entity.py

@@ -1517,6 +1517,20 @@ def create_account_by_kwargs(self,
         # account_model.clean()
         return coa_model, coa_model.create_account(**account_model_kwargs)
 
+    def get_account_balance(self,
+                            account_codes: List[str],
+                            to_date: Union[datetime, date, str],
+                            **kwargs):
+
+        io_context = self.digest(
+            entity_model=self.slug,
+            accounts=account_codes,
+            to_date=to_date,
+            **kwargs
+        )
+
+        return io_context
+
     # ### LEDGER MANAGEMENT ####
     def get_ledgers(self, posted: Optional[bool] = None):
         if posted is not None:
@@ -3135,12 +3149,12 @@ class EntityModel(EntityModelAbstract):
     """
     Entity Model Base Class From Abstract
     """
+
     class Meta(EntityModelAbstract.Meta):
         swappable = 'DJANGO_LEDGER_ENTITY_MODEL'
         abstract = False
 
 
-
 # ## ENTITY STATE....
 class EntityStateModelAbstract(Model):
     KEY_JOURNAL_ENTRY = 'je'

django_ledger/models/transactions.py

@@ -67,7 +67,7 @@ def posted(self) -> QuerySet:
             Q(journal_entry__ledger__posted=True)
         )
 
-    def for_accounts(self, account_list: List[str or AccountModel]):
+    def for_accounts(self, account_list: List[Union[AccountModel, str, UUID]]):
         """
         Filters transactions based on the accounts they are associated with.
 
@@ -82,9 +82,20 @@ def for_accounts(self, account_list: List[str or AccountModel]):
         TransactionModelQuerySet
             A QuerySet filtered for transactions associated with the specified accounts.
         """
-        if isinstance(account_list, list) > 0 and isinstance(account_list[0], str):
+
+        if not isinstance(account_list, list) or not len(account_list) > 0:
+            raise TransactionModelValidationError(
+                message=_('Account list must be a list of AccountModel, UUID or str objects (codes).')
+            )
+        if isinstance(account_list[0], str):
             return self.filter(account__code__in=account_list)
-        return self.filter(account__in=account_list)
+        elif isinstance(account_list[0], UUID):
+            return self.filter(account__uuid__in=account_list)
+        elif isinstance(account_list[0], AccountModel):
+            return self.filter(account__in=account_list)
+        raise TransactionModelValidationError(
+            message=_('Account list must be a list of AccountModel, UUID or str objects (codes).')
+        )
 
     def for_roles(self, role_list: Union[str, List[str], Set[str]]):
         """
@@ -294,6 +305,18 @@ def with_annotated_details(self):
             timestamp=F('journal_entry__timestamp'),
         )
 
+    def is_cleared(self):
+        return self.filter(cleared=True)
+
+    def not_cleared(self):
+        return self.filter(cleared=False)
+
+    def is_reconciled(self):
+        return self.filter(reconciled=True)
+
+    def not_reconciled(self):
+        return self.filter(reconciled=False)
+
 
 class TransactionModelManager(Manager):
     """
@@ -317,6 +340,7 @@ def get_queryset(self) -> TransactionModelQuerySet:
         """
         qs = TransactionModelQuerySet(self.model, using=self._db)
         return qs.annotate(
+            timestamp=F('journal_entry__timestamp'),
             _coa_id=F('account__coa_model_id')  # Annotates the `coa_model_id` from the related `account`.
         ).select_related(
             'journal_entry',  # Pre-loads the related Journal Entry.