GeneralManager 0.5.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

general_manager/bucket/databaseBucket.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+from typing import (
+    Type,
+    Any,
+    Generator,
+    TypeVar,
+)
+from django.db import models
+from general_manager.interface.baseInterface import (
+    GeneralManagerType,
+)
+from general_manager.bucket.baseBucket import Bucket
+
+from general_manager.manager.generalManager import GeneralManager
+
+modelsModel = TypeVar("modelsModel", bound=models.Model)
+
+
+class DatabaseBucket(Bucket[GeneralManagerType]):
+
+    def __init__(
+        self,
+        data: models.QuerySet[modelsModel],
+        manager_class: Type[GeneralManagerType],
+        filter_definitions: dict[str, list[Any]] | None = None,
+        exclude_definitions: dict[str, list[Any]] | None = None,
+    ):
+        """
+        Initializes a DatabaseBucket with a queryset, manager class, and optional filter and exclude definitions.
+
+        If no queryset is provided, constructs one using the manager class and the given filters and excludes. Stores the queryset, manager class, and copies of the filter and exclude definitions for further operations.
+        """
+        if data is None:
+            data = manager_class.Interface._model.objects.filter(
+                **filter_definitions
+            ).exclude(**exclude_definitions)
+        self._data = data
+
+        self._manager_class = manager_class
+        self.filters = {**(filter_definitions or {})}
+        self.excludes = {**(exclude_definitions or {})}
+
+    def __iter__(self) -> Generator[GeneralManagerType]:
+        """
+        Yields manager instances for each item in the underlying queryset.
+
+        Iterates over the queryset, returning a new instance of the manager class for each item's primary key.
+        """
+        for item in self._data:
+            yield self._manager_class(item.pk)
+
+    def __or__(
+        self,
+        other: Bucket[GeneralManagerType] | GeneralManager[GeneralManagerType],
+    ) -> DatabaseBucket[GeneralManagerType]:
+        """
+        Combines this bucket with another bucket or manager instance using the union operator.
+
+        If `other` is a manager instance of the same class, creates a bucket containing only that instance and combines it. If `other` is a compatible bucket, returns a new bucket containing the union of both buckets' querysets. Raises a `ValueError` if the types or manager classes are incompatible.
+
+        Returns:
+            A new `DatabaseBucket` containing the combined items.
+        """
+        if isinstance(other, GeneralManager) and other.__class__ == self._manager_class:
+            return self.__or__(
+                self._manager_class.filter(id__in=[other.identification["id"]])
+            )
+        if not isinstance(other, self.__class__):
+            raise ValueError("Cannot combine different bucket types")
+        if self._manager_class != other._manager_class:
+            raise ValueError("Cannot combine different bucket managers")
+        return self.__class__(
+            self._data | other._data,
+            self._manager_class,
+            {},
+        )
+
+    def __mergeFilterDefinitions(
+        self, basis: dict[str, list[Any]], **kwargs: Any
+    ) -> dict[str, list[Any]]:
+        """
+        Combines existing filter definitions with additional criteria by appending new values to each key's list.
+
+        Args:
+            basis: Existing filter definitions as a dictionary mapping keys to lists of values.
+            **kwargs: Additional filter criteria to merge, with each value appended to the corresponding key.
+
+        Returns:
+            A dictionary containing all filter keys with lists of values from both the original and new criteria.
+        """
+        kwarg_filter: dict[str, list[Any]] = {}
+        for key, value in basis.items():
+            kwarg_filter[key] = value
+        for key, value in kwargs.items():
+            if key not in kwarg_filter:
+                kwarg_filter[key] = []
+            kwarg_filter[key].append(value)
+        return kwarg_filter
+
+    def filter(self, **kwargs: Any) -> DatabaseBucket[GeneralManagerType]:
+        """
+        Returns a new bucket with manager instances matching the combined filter criteria.
+
+        Additional filter arguments are merged with any existing filters to further restrict the queryset, producing a new DatabaseBucket instance.
+        """
+        merged_filter = self.__mergeFilterDefinitions(self.filters, **kwargs)
+        return self.__class__(
+            self._data.filter(**kwargs),
+            self._manager_class,
+            merged_filter,
+            self.excludes,
+        )
+
+    def exclude(self, **kwargs: Any) -> DatabaseBucket[GeneralManagerType]:
+        """
+        Returns a new DatabaseBucket excluding items that match the specified criteria.
+
+        Keyword arguments specify field lookups to exclude from the queryset. The resulting bucket contains only items that do not satisfy these exclusion filters.
+        """
+        merged_exclude = self.__mergeFilterDefinitions(self.excludes, **kwargs)
+        return self.__class__(
+            self._data.exclude(**kwargs),
+            self._manager_class,
+            self.filters,
+            merged_exclude,
+        )
+
+    def first(self) -> GeneralManagerType | None:
+        """
+        Returns the first item in the queryset wrapped in the manager class, or None if the queryset is empty.
+        """
+        first_element = self._data.first()
+        if first_element is None:
+            return None
+        return self._manager_class(first_element.pk)
+
+    def last(self) -> GeneralManagerType | None:
+        """
+        Returns the last item in the queryset wrapped in the manager class, or None if the queryset is empty.
+        """
+        first_element = self._data.last()
+        if first_element is None:
+            return None
+        return self._manager_class(first_element.pk)
+
+    def count(self) -> int:
+        """
+        Returns the number of items in the bucket.
+        """
+        return self._data.count()
+
+    def all(self) -> DatabaseBucket:
+        """
+        Returns a new DatabaseBucket containing all items from the current queryset.
+        """
+        return self.__class__(self._data.all(), self._manager_class)
+
+    def get(self, **kwargs: Any) -> GeneralManagerType:
+        """
+        Retrieves a single item matching the given criteria and returns it as a manager instance.
+
+        Args:
+                **kwargs: Field lookups to identify the item to retrieve.
+
+        Returns:
+                A manager instance wrapping the uniquely matched model object.
+
+        Raises:
+                Does not handle exceptions; any exceptions raised by the underlying queryset's `get()` method will propagate.
+        """
+        element = self._data.get(**kwargs)
+        return self._manager_class(element.pk)
+
+    def __getitem__(self, item: int | slice) -> GeneralManagerType | DatabaseBucket:
+        """
+        Enables indexing and slicing of the bucket.
+
+        If an integer index is provided, returns the manager instance for the corresponding item. If a slice is provided, returns a new bucket containing the sliced queryset.
+        """
+        if isinstance(item, slice):
+            return self.__class__(self._data[item], self._manager_class)
+        return self._manager_class(self._data[item].pk)
+
+    def __len__(self) -> int:
+        """
+        Returns the number of items in the bucket.
+        """
+        return self._data.count()
+
+    def __repr__(self) -> str:
+        """
+        Returns a string representation of the bucket, showing the manager class name and the underlying queryset.
+        """
+        return f"{self._manager_class.__name__}Bucket ({self._data})"
+
+    def __contains__(self, item: GeneralManagerType | models.Model) -> bool:
+        """
+        Checks if a manager instance or model instance is present in the bucket.
+
+        Args:
+            item: A manager instance or Django model instance to check for membership.
+
+        Returns:
+            True if the item's primary key exists in the underlying queryset; otherwise, False.
+        """
+        from general_manager.manager.generalManager import GeneralManager
+
+        if isinstance(item, GeneralManager):
+            return item.identification.get("id", None) in self._data.values_list(
+                "pk", flat=True
+            )
+        return item in self._data
+
+    def sort(
+        self,
+        key: tuple[str] | str,
+        reverse: bool = False,
+    ) -> DatabaseBucket:
+        """
+        Returns a new DatabaseBucket sorted by the specified field or fields.
+
+        Args:
+            key: A field name or tuple of field names to sort by.
+            reverse: If True, sorts in descending order.
+
+        Returns:
+            A new DatabaseBucket instance with the sorted queryset.
+        """
+        if isinstance(key, str):
+            key = (key,)
+        if reverse:
+            sorted_data = self._data.order_by(*[f"-{k}" for k in key])
+        else:
+            sorted_data = self._data.order_by(*key)
+        return self.__class__(sorted_data, self._manager_class)

general_manager/bucket/groupBucket.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+from typing import (
+    Type,
+    Generator,
+    Any,
+)
+import json
+from general_manager.manager.groupManager import GroupManager
+from general_manager.bucket.baseBucket import (
+    Bucket,
+    GeneralManagerType,
+)
+
+
+class GroupBucket(Bucket[GeneralManagerType]):
+
+    def __init__(
+        self,
+        manager_class: Type[GeneralManagerType],
+        group_by_keys: tuple[str, ...],
+        data: Bucket[GeneralManagerType],
+    ):
+        """
+        Initializes a GroupBucket by grouping data based on specified attribute keys.
+
+        Args:
+            manager_class: The class type of the manager objects to be grouped.
+            group_by_keys: Tuple of attribute names to group the data by.
+            data: The underlying Bucket containing manager instances to be grouped.
+
+        Raises:
+            TypeError: If any group-by key is not a string.
+            ValueError: If any group-by key is not a valid attribute of the manager class.
+        """
+        super().__init__(manager_class)
+        self.__checkGroupByArguments(group_by_keys)
+        self._group_by_keys = group_by_keys
+        self._data = self.__buildGroupedManager(data)
+        self._basis_data = data
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Checks whether this GroupBucket is equal to another by comparing grouped data, manager class, and group-by keys.
+
+        Returns:
+            True if both instances have identical grouped data, manager class, and group-by keys; otherwise, False.
+        """
+        if not isinstance(other, self.__class__):
+            return False
+        return (
+            set(self._data) == set(other._data)
+            and self._manager_class == other._manager_class
+            and self._group_by_keys == other._group_by_keys
+        )
+
+    def __checkGroupByArguments(self, group_by_keys: tuple[str, ...]) -> None:
+        """
+        Checks that each group-by key is a string and a valid attribute of the manager class.
+
+        Raises:
+            TypeError: If any group-by key is not a string.
+            ValueError: If any group-by key is not a valid attribute of the manager class.
+        """
+        if not all(isinstance(arg, str) for arg in group_by_keys):
+            raise TypeError("groupBy() arguments must be a strings")
+        if not all(
+            arg in self._manager_class.Interface.getAttributes()
+            for arg in group_by_keys
+        ):
+            raise ValueError(
+                f"groupBy() argument must be a valid attribute of {self._manager_class.__name__}"
+            )
+
+    def __buildGroupedManager(
+        self,
+        data: Bucket[GeneralManagerType],
+    ) -> list[GroupManager[GeneralManagerType]]:
+        """
+        Constructs a list of GroupManager instances, each representing a unique group of entries from the provided data bucket based on the current group-by keys.
+
+        Args:
+            data: The bucket of manager instances to be grouped.
+
+        Returns:
+            A list of GroupManager objects, each corresponding to a unique combination of group-by attribute values found in the data.
+        """
+        group_by_values: set[tuple[tuple[str, Any], ...]] = set()
+        for entry in data:
+            key = tuple((arg, getattr(entry, arg)) for arg in self._group_by_keys)
+            group_by_values.add(key)
+
+        groups = []
+        for group_by_value in sorted(group_by_values, key=str):
+            group_by_dict = {key: value for key, value in group_by_value}
+            grouped_manager_objects = data.filter(**group_by_dict)
+            groups.append(
+                GroupManager(
+                    self._manager_class, group_by_dict, grouped_manager_objects
+                )
+            )
+        return groups
+
+    def __or__(self, other: object) -> GroupBucket[GeneralManagerType]:
+        """
+        Returns a new GroupBucket representing the union of this bucket and another, combining their underlying data.
+
+        Raises:
+            ValueError: If the other object is not a GroupBucket of the same type or uses a different manager class.
+        """
+        if not isinstance(other, self.__class__):
+            raise ValueError("Cannot combine different bucket types")
+        if self._manager_class != other._manager_class:
+            raise ValueError("Cannot combine different manager classes")
+        return GroupBucket(
+            self._manager_class,
+            self._group_by_keys,
+            self._basis_data | other._basis_data,
+        )
+
+    def __iter__(self) -> Generator[GroupManager[GeneralManagerType]]:
+        """
+        Yields each grouped manager in the current GroupBucket.
+
+        Returns:
+            A generator yielding GroupManager instances representing each group.
+        """
+        yield from self._data
+
+    def filter(self, **kwargs: Any) -> GroupBucket[GeneralManagerType]:
+        """
+        Returns a new GroupBucket containing only the entries from the underlying data that match the specified filter criteria.
+
+        Keyword arguments correspond to attribute-value pairs used for filtering.
+        """
+        new_basis_data = self._basis_data.filter(**kwargs)
+        return GroupBucket(
+            self._manager_class,
+            self._group_by_keys,
+            new_basis_data,
+        )
+
+    def exclude(self, **kwargs: Any) -> GroupBucket[GeneralManagerType]:
+        """
+        Returns a new GroupBucket excluding entries from the underlying data that match the given criteria.
+
+        Keyword arguments specify attribute-value pairs to exclude from the basis data. The resulting GroupBucket retains the same grouping keys and manager class.
+        """
+        new_basis_data = self._basis_data.exclude(**kwargs)
+        return GroupBucket(
+            self._manager_class,
+            self._group_by_keys,
+            new_basis_data,
+        )
+
+    def first(self) -> GroupManager[GeneralManagerType] | None:
+        """
+        Returns the first grouped manager in the collection, or None if the collection is empty.
+        """
+        try:
+            return next(iter(self))
+        except StopIteration:
+            return None
+
+    def last(self) -> GroupManager[GeneralManagerType] | None:
+        """
+        Returns the last grouped manager in the collection, or None if the collection is empty.
+        """
+        items = list(self)
+        if items:
+            return items[-1]
+        return None
+
+    def count(self) -> int:
+        """
+        Returns the number of grouped managers in the bucket.
+        """
+        return sum(1 for _ in self)
+
+    def all(self) -> Bucket[GeneralManagerType]:
+        """
+        Returns the current GroupBucket instance.
+
+        This method provides compatibility with interfaces expecting an `all()` method to retrieve the full collection.
+        """
+        return self
+
+    def get(self, **kwargs: Any) -> GroupManager[GeneralManagerType]:
+        """
+        Returns the first grouped manager matching the specified filter criteria.
+
+        Args:
+            **kwargs: Attribute-value pairs to filter grouped managers.
+
+        Returns:
+            The first GroupManager instance matching the filter criteria.
+
+        Raises:
+            ValueError: If no grouped manager matches the provided criteria.
+        """
+        first_value = self.filter(**kwargs).first()
+        if first_value is None:
+            raise ValueError(
+                f"Cannot find {self._manager_class.__name__} with {kwargs}"
+            )
+        return first_value
+
+    def __getitem__(
+        self, item: int | slice
+    ) -> GroupManager[GeneralManagerType] | GroupBucket[GeneralManagerType]:
+        """
+        Returns a grouped manager by index or a new GroupBucket by slice.
+
+        If an integer index is provided, returns the corresponding GroupManager. If a slice is provided, returns a new GroupBucket containing the union of the basis data from the selected groups.
+
+        Raises:
+            ValueError: If slicing results in no groups.
+            TypeError: If the argument is not an int or slice.
+        """
+        if isinstance(item, int):
+            return self._data[item]
+        elif isinstance(item, slice):
+            new_data = self._data[item]
+            new_base_data = None
+            for manager in new_data:
+                if new_base_data is None:
+                    new_base_data = manager._data
+                else:
+                    new_base_data = new_base_data | manager._data
+            if new_base_data is None:
+                raise ValueError("Cannot slice an empty GroupBucket")
+            return GroupBucket(self._manager_class, self._group_by_keys, new_base_data)
+        raise TypeError(f"Invalid argument type: {type(item)}. Expected int or slice.")
+
+    def __len__(self) -> int:
+        """
+        Returns the number of grouped managers in the GroupBucket.
+        """
+        return self.count()
+
+    def __contains__(self, item: GeneralManagerType) -> bool:
+        """
+        Checks if the given manager instance is present in the underlying basis data.
+
+        Args:
+            item: The manager instance to check for membership.
+
+        Returns:
+            True if the item exists in the basis data; otherwise, False.
+        """
+        return item in self._basis_data
+
+    def sort(
+        self,
+        key: tuple[str, ...] | str,
+        reverse: bool = False,
+    ) -> Bucket[GeneralManagerType]:
+        """
+        Returns a new GroupBucket with grouped managers sorted by the specified attribute keys.
+
+        Args:
+            key: A string or tuple of strings specifying the attribute(s) to sort by.
+            reverse: If True, sorts in descending order. Defaults to False.
+
+        Returns:
+            A new GroupBucket instance with grouped managers sorted by the given keys.
+        """
+        if isinstance(key, str):
+            key = (key,)
+        if reverse:
+            sorted_data = sorted(
+                self._data,
+                key=lambda x: tuple(getattr(x, k) for k in key),
+                reverse=True,
+            )
+        else:
+            sorted_data = sorted(
+                self._data, key=lambda x: tuple(getattr(x, k) for k in key)
+            )
+
+        new_bucket = GroupBucket(
+            self._manager_class, self._group_by_keys, self._basis_data
+        )
+        new_bucket._data = sorted_data
+        return new_bucket
+
+    def group_by(self, *group_by_keys: str) -> GroupBucket[GeneralManagerType]:
+        """
+        Returns a new GroupBucket grouped by the current and additional specified attribute keys.
+
+        Additional group-by keys are appended to the existing grouping, and the new GroupBucket is constructed from the same underlying data.
+        """
+        return GroupBucket(
+            self._manager_class,
+            tuple([*self._group_by_keys, *group_by_keys]),
+            self._basis_data,
+        )

general_manager/cache/modelDependencyCollector.py

@@ -1,5 +1,6 @@
 from typing import Generator
-from general_manager.manager.generalManager import GeneralManager, Bucket
+from general_manager.manager.generalManager import GeneralManager
+from general_manager.bucket.baseBucket import Bucket
 from general_manager.cache.dependencyIndex import (
     general_manager_name,
     Dependency,
@@ -12,19 +13,15 @@ class ModelDependencyCollector:
     @staticmethod
     def collect(obj) -> Generator[tuple[general_manager_name, filter_type, str]]:
         """
-        Recursively yields dependency information from objects related to Django models.
+        Recursively extracts dependency information from Django model-related objects.
         
-        Traverses the input object and its nested structures to identify instances of
-        GeneralManager and Bucket, yielding tuples that describe their dependencies.
-        Yields a tuple of (manager class name, dependency type, dependency value) for
-        each dependency found.
+        Inspects the input object and its nested structures to identify instances of GeneralManager and Bucket, yielding a tuple for each dependency found. Each tuple contains the manager class name, the dependency type ("identification", "filter", or "exclude"), and the string representation of the dependency value.
         
         Args:
             obj: The object or collection to inspect for model dependencies.
         
         Yields:
-            Tuples containing the manager class name, dependency type ("identification",
-            "filter", or "exclude"), and the string representation of the dependency value.
+            Tuples of (manager class name, dependency type, dependency value) for each dependency discovered.
         """
         if isinstance(obj, GeneralManager):
             yield (

general_manager/interface/__init__.py

@@ -1,3 +0,0 @@
-# from .baseInterface import InterfaceBase, Bucket
-# from .databaseInterface import DatabaseInterface, ReadOnlyInterface, DatabaseBucket
-# from .calculationInterface import CalculationInterface, CalculationBucket