GeneralManager 0.16.1__py3-none-any.whl → 0.18.0__py3-none-any.whl

general_manager/bucket/databaseBucket.py

@@ -1,15 +1,15 @@
 """Database-backed bucket implementation for GeneralManager collections."""
 
 from __future__ import annotations
-from typing import Type, Any, Generator, TypeVar, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Generator, Type, TypeVar
+
+from django.core.exceptions import FieldError
 from django.db import models
-from general_manager.interface.baseInterface import (
-    GeneralManagerType,
-)
-from general_manager.utils.filterParser import create_filter_function
-from general_manager.bucket.baseBucket import Bucket
 
+from general_manager.bucket.baseBucket import Bucket
+from general_manager.interface.baseInterface import GeneralManagerType
 from general_manager.manager.generalManager import GeneralManager
+from general_manager.utils.filterParser import create_filter_function
 
 modelsModel = TypeVar("modelsModel", bound=models.Model)
 
@@ -17,6 +17,108 @@ if TYPE_CHECKING:
     from general_manager.interface.databaseInterface import DatabaseInterface
 
 
+class DatabaseBucketTypeMismatchError(TypeError):
+    """Raised when attempting to combine buckets of different types."""
+
+    def __init__(self, bucket_type: type, other_type: type) -> None:
+        """
+        Initialize the error for attempting to combine two incompatible bucket types.
+
+        Parameters:
+            bucket_type (type): The bucket type used in the operation.
+            other_type (type): The other bucket type that is incompatible with `bucket_type`.
+        """
+        super().__init__(
+            f"Cannot combine {bucket_type.__name__} with {other_type.__name__}."
+        )
+
+
+class DatabaseBucketManagerMismatchError(TypeError):
+    """Raised when combining buckets backed by different manager classes."""
+
+    def __init__(self, first_manager: type, second_manager: type) -> None:
+        """
+        Raised when attempting to combine buckets that are backed by different manager classes.
+
+        Parameters:
+            first_manager (type): The first manager class involved in the attempted combination.
+            second_manager (type): The second manager class involved in the attempted combination.
+        """
+        super().__init__(
+            f"Cannot combine buckets for {first_manager.__name__} and {second_manager.__name__}."
+        )
+
+
+class NonFilterablePropertyError(ValueError):
+    """Raised when attempting to filter on a property without filter support."""
+
+    def __init__(self, property_name: str, manager_name: str) -> None:
+        """
+        Raised when a filter is requested for a GraphQL property that is not marked as filterable on the given manager.
+
+        Parameters:
+            property_name (str): The GraphQL property name that was used for filtering.
+            manager_name (str): The name of the manager (or manager class) where the property is not filterable.
+        """
+        super().__init__(
+            f"Property '{property_name}' is not filterable in {manager_name}."
+        )
+
+
+class InvalidQueryAnnotationTypeError(TypeError):
+    """Raised when a query annotation callback returns a non-queryset value."""
+
+    def __init__(self) -> None:
+        """
+        Exception raised when a query annotation callback returns a non-QuerySet.
+
+        The exception carries a standardized message: "Query annotation must return a Django QuerySet."
+        """
+        super().__init__("Query annotation must return a Django QuerySet.")
+
+
+class QuerysetFilteringError(ValueError):
+    """Raised when applying ORM filters fails."""
+
+    def __init__(self, original: Exception) -> None:
+        """
+        Initialize a QuerysetFilteringError that wraps an original exception raised during ORM filtering.
+
+        Parameters:
+            original (Exception): The original exception encountered while filtering the queryset; its message is included in this error's message.
+        """
+        super().__init__(f"Error filtering queryset: {original}")
+
+
+class QuerysetOrderingError(ValueError):
+    """Raised when applying ORM ordering fails."""
+
+    def __init__(self, original: Exception) -> None:
+        """
+        Initialize the QuerysetOrderingError by wrapping the originating exception.
+
+        Parameters:
+            original (Exception): The original exception raised while ordering the queryset; retained as the wrapped cause.
+        """
+        super().__init__(f"Error ordering queryset: {original}")
+
+
+class NonSortablePropertyError(ValueError):
+    """Raised when attempting to sort on a property lacking sort support."""
+
+    def __init__(self, property_name: str, manager_name: str) -> None:
+        """
+        Initialize an error indicating a property cannot be used for sorting on a manager.
+
+        Parameters:
+            property_name (str): The name of the property that was requested for sorting.
+            manager_name (str): The name of the manager (or manager class) where the property was queried.
+        """
+        super().__init__(
+            f"Property '{property_name}' is not sortable in {manager_name}."
+        )
+
+
 class DatabaseBucket(Bucket[GeneralManagerType]):
     """Bucket implementation backed by Django ORM querysets."""
 
@@ -59,25 +161,28 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         other: Bucket[GeneralManagerType] | GeneralManagerType,
     ) -> DatabaseBucket[GeneralManagerType]:
         """
-        Merge two database buckets (or bucket and instance) into a single result.
+        Produce a new DatabaseBucket representing the union of this bucket with another DatabaseBucket or a GeneralManager instance of the same manager class.
 
         Parameters:
-            other (Bucket[GeneralManagerType] | GeneralManagerType): Bucket or manager instance to merge.
+            other (Bucket[GeneralManagerType] | GeneralManagerType): The bucket or manager instance to merge with this bucket.
 
         Returns:
-            DatabaseBucket[GeneralManagerType]: New bucket containing the combined queryset.
+            DatabaseBucket[GeneralManagerType]: A new bucket containing the combined items from both operands.
 
         Raises:
-            ValueError: If the operand is incompatible or uses a different manager class.
+            DatabaseBucketTypeMismatchError: If `other` is not a DatabaseBucket of the same class and not a compatible GeneralManager.
+            DatabaseBucketManagerMismatchError: If `other` is a DatabaseBucket but uses a different manager class.
         """
         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")
+            raise DatabaseBucketTypeMismatchError(self.__class__, type(other))
         if self._manager_class != other._manager_class:
-            raise ValueError("Cannot combine different bucket managers")
+            raise DatabaseBucketManagerMismatchError(
+                self._manager_class, other._manager_class
+            )
         return self.__class__(
             self._data | other._data,
             self._manager_class,
@@ -109,19 +214,24 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
     def __parseFilterDeifintions(
         self,
         **kwargs: Any,
-    ) -> tuple[dict[str, Any], dict[str, list[Any]], list[tuple[str, Any, str]]]:
+    ) -> tuple[dict[str, Any], dict[str, Any], list[tuple[str, Any, str]]]:
         """
-        Separate ORM-compatible filters from Python-side property filters.
+        Split provided filter kwargs into three parts: query annotations required by properties, ORM-compatible lookup mappings, and Python-evaluated filter specifications.
 
         Parameters:
             **kwargs: Filter lookups supplied to `filter` or `exclude`.
 
         Returns:
-            tuple[dict[str, Any], dict[str, Any], list[tuple[str, Any, str]]]:
-                Query annotations, ORM-compatible lookups, and Python-evaluated filter specifications.
+            tuple:
+                - annotations (dict[str, Any]): Mapping from property name to its `query_annotation` (callable or annotation object) for properties that require ORM annotations.
+                - orm_kwargs (dict[str, list[Any]]): Mapping of ORM lookup strings (e.g., "field__lookup") to their values to be passed to the queryset.
+                - python_filters (list[tuple[str, Any, str]]): List of tuples (lookup, value, root_property_name) for properties that must be evaluated in Python.
+
+        Raises:
+            NonFilterablePropertyError: If a lookup targets a property that is not allowed to be filtered.
         """
         annotations: dict[str, Any] = {}
-        orm_kwargs: dict[str, list[Any]] = {}
+        orm_kwargs: dict[str, Any] = {}
         python_filters: list[tuple[str, Any, str]] = []
         properties = self._manager_class.Interface.getGraphQLProperties()
 
@@ -129,9 +239,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             root = k.split("__")[0]
             if root in properties:
                 if not properties[root].filterable:
-                    raise ValueError(
-                        f"Property '{root}' is not filterable in {self._manager_class.__name__}"
-                    )
+                    raise NonFilterablePropertyError(root, self._manager_class.__name__)
                 prop = properties[root]
                 if prop.query_annotation is not None:
                     annotations[root] = prop.query_annotation
@@ -172,17 +280,18 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
 
     def filter(self, **kwargs: Any) -> DatabaseBucket[GeneralManagerType]:
         """
-        Produce a bucket filtered by the supplied lookups in addition to existing state.
+        Return a new DatabaseBucket refined by the given Django-style lookup expressions.
 
         Parameters:
-            **kwargs (Any): Django-style lookup expressions applied to the underlying queryset.
+            **kwargs (Any): Django-style lookup expressions to apply to the underlying queryset.
 
         Returns:
-            DatabaseBucket[GeneralManagerType]: New bucket representing the refined queryset.
+            DatabaseBucket[GeneralManagerType]: New bucket containing items matching the existing state combined with the provided lookups.
 
         Raises:
-            ValueError: If the ORM rejects the filter arguments.
-            TypeError: If a query annotation callback does not return a queryset.
+            NonFilterablePropertyError: If a provided property is not filterable for this manager.
+            InvalidQueryAnnotationTypeError: If a query-annotation callback returns a non-QuerySet.
+            QuerysetFilteringError: If the ORM rejects the filter arguments or filtering fails.
         """
         annotations, orm_kwargs, python_filters = self.__parseFilterDeifintions(
             **kwargs
@@ -196,12 +305,12 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
                     continue
                 qs = value(qs)
             if not isinstance(qs, models.QuerySet):
-                raise TypeError("Query annotation must return a Django QuerySet")
+                raise InvalidQueryAnnotationTypeError()
             qs = qs.annotate(**other_annotations)
         try:
             qs = qs.filter(**orm_kwargs)
-        except Exception as e:
-            raise ValueError(f"Error filtering queryset: {e}")
+        except (FieldError, TypeError, ValueError) as error:
+            raise QuerysetFilteringError(error) from error
 
         if python_filters:
             ids = self.__parsePythonFilters(qs, python_filters)
@@ -212,16 +321,18 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
 
     def exclude(self, **kwargs: Any) -> DatabaseBucket[GeneralManagerType]:
         """
-        Produce a bucket that excludes rows matching the supplied lookups.
+        Produce a bucket that excludes rows matching the provided Django-style lookup expressions.
+
+        Accepts ORM lookups, query annotation entries, and Python-only filters; annotation callables will be applied to the underlying queryset as needed.
 
         Parameters:
-            **kwargs (Any): Django-style lookup expressions identifying records to omit.
+            **kwargs (Any): Django-style lookup expressions, annotation entries, or property-based filters used to identify records to exclude.
 
         Returns:
-            DatabaseBucket[GeneralManagerType]: New bucket representing the filtered queryset.
+            DatabaseBucket[GeneralManagerType]: A new bucket whose queryset omits rows matching the provided lookups.
 
         Raises:
-            TypeError: If a query annotation callback does not return a queryset.
+            InvalidQueryAnnotationTypeError: If an annotation callable is applied and does not return a Django QuerySet.
         """
         annotations, orm_kwargs, python_filters = self.__parseFilterDeifintions(
             **kwargs
@@ -235,7 +346,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
                     continue
                 qs = value(qs)
             if not isinstance(qs, models.QuerySet):
-                raise TypeError("Query annotation must return a Django QuerySet")
+                raise InvalidQueryAnnotationTypeError()
             qs = qs.annotate(**other_annotations)
         qs = qs.exclude(**orm_kwargs)
 
@@ -370,18 +481,21 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         reverse: bool = False,
     ) -> DatabaseBucket:
         """
-        Return a new bucket ordered by the specified fields.
+        Return a new DatabaseBucket ordered by the given property name(s).
+
+        Accepts a single property name or a tuple of property names. Properties with ORM annotations are applied at the database level; properties without ORM annotations are evaluated in Python and the resulting records are re-ordered while preserving a queryset result. Stable ordering and preservation of manager wrapping are maintained.
 
         Parameters:
-            key (str | tuple[str, ...]): Field name(s) used for ordering.
-            reverse (bool): Whether to sort in descending order.
+            key (str | tuple[str, ...]): Property name or sequence of property names to sort by, applied in order of appearance.
+            reverse (bool): If True, sort each specified key in descending order.
 
         Returns:
-            DatabaseBucket: Bucket whose queryset is ordered accordingly.
+            DatabaseBucket: A new bucket whose underlying queryset is ordered according to the requested keys.
 
         Raises:
-            ValueError: If sorting by a non-sortable property or when the ORM rejects the ordering.
-            TypeError: If a property annotation callback does not return a queryset.
+            NonSortablePropertyError: If any requested property is not marked as sortable on the manager's GraphQL properties.
+            InvalidQueryAnnotationTypeError: If a property query annotation callable returns a non-QuerySet value.
+            QuerysetOrderingError: If the ORM rejects the constructed ordering (e.g., invalid field or incompatible ordering expression).
         """
         if isinstance(key, str):
             key = (key,)
@@ -393,9 +507,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             if k in properties:
                 prop = properties[k]
                 if not prop.sortable:
-                    raise ValueError(
-                        f"Property '{k}' is not sortable in {self._manager_class.__name__}"
-                    )
+                    raise NonSortablePropertyError(k, self._manager_class.__name__)
                 if prop.query_annotation is not None:
                     if callable(prop.query_annotation):
                         qs = prop.query_annotation(qs)
@@ -404,7 +516,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
                 else:
                     python_keys.append(k)
         if not isinstance(qs, models.QuerySet):
-            raise TypeError("Query annotation must return a Django QuerySet")
+            raise InvalidQueryAnnotationTypeError()
         if annotations:
             qs = qs.annotate(**annotations)
 
@@ -435,8 +547,8 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             order_fields = [f"-{k}" if reverse else k for k in key]
             try:
                 qs = qs.order_by(*order_fields)
-            except Exception as e:
-                raise ValueError(f"Error ordering queryset: {e}")
+            except (FieldError, TypeError, ValueError) as error:
+                raise QuerysetOrderingError(error) from error
 
         return self.__class__(qs, self._manager_class)
 

general_manager/bucket/groupBucket.py

@@ -1,16 +1,110 @@
 """Grouping bucket implementation for aggregating GeneralManager instances."""
 
 from __future__ import annotations
-from typing import (
-    Type,
-    Generator,
-    Any,
-)
+from typing import Any, Generator, Type
 from general_manager.manager.groupManager import GroupManager
-from general_manager.bucket.baseBucket import (
-    Bucket,
-    GeneralManagerType,
-)
+from general_manager.bucket.baseBucket import Bucket, GeneralManagerType
+
+
+class InvalidGroupByKeyTypeError(TypeError):
+    """Raised when a non-string value is provided as a group-by key."""
+
+    def __init__(self) -> None:
+        """
+        Error raised when a non-string group-by key is provided.
+
+        Initializes the exception with the message "groupBy() arguments must be strings."
+        """
+        super().__init__("groupBy() arguments must be strings.")
+
+
+class UnknownGroupByKeyError(ValueError):
+    """Raised when a group-by key does not exist on the manager interface."""
+
+    def __init__(self, manager_name: str) -> None:
+        """
+        Create an UnknownGroupByKeyError indicating a missing attribute on a manager.
+
+        Parameters:
+            manager_name (str): Name of the manager whose attributes were expected; used to format the error message.
+        """
+        super().__init__(f"groupBy() arguments must be attributes of {manager_name}.")
+
+
+class GroupBucketTypeMismatchError(TypeError):
+    """Raised when attempting to merge grouping buckets of different types."""
+
+    def __init__(self, first_type: type, second_type: type) -> None:
+        """
+        Initialize the error for attempting to combine two incompatible bucket types.
+
+        Parameters:
+            first_type (type): The first type involved in the attempted combination.
+            second_type (type): The second type involved in the attempted combination.
+
+        Notes:
+            The exception message is formatted as "Cannot combine {first_type.__name__} with {second_type.__name__}."
+        """
+        super().__init__(
+            f"Cannot combine {first_type.__name__} with {second_type.__name__}."
+        )
+
+
+class GroupBucketManagerMismatchError(ValueError):
+    """Raised when grouping buckets track different manager classes."""
+
+    def __init__(self, first_manager: type, second_manager: type) -> None:
+        """
+        Initialize the exception indicating two group buckets track different manager classes.
+
+        Parameters:
+            first_manager (type): The first manager class involved in the mismatch.
+            second_manager (type): The second manager class involved in the mismatch.
+        """
+        super().__init__(
+            f"Cannot combine buckets for {first_manager.__name__} and {second_manager.__name__}."
+        )
+
+
+class GroupItemNotFoundError(ValueError):
+    """Raised when a grouped manager matching the provided criteria cannot be found."""
+
+    def __init__(self, manager_name: str, criteria: dict[str, Any]) -> None:
+        """
+        Initialize an error indicating a grouped manager matching the provided lookup criteria could not be found.
+
+        Parameters:
+            manager_name (str): Name of the manager type searched for.
+            criteria (dict[str, Any]): Lookup criteria used to locate the manager; included in the error message.
+        """
+        super().__init__(f"Cannot find {manager_name} with {criteria}.")
+
+
+class EmptyGroupBucketSliceError(ValueError):
+    """Raised when slicing a group bucket yields no results."""
+
+    def __init__(self) -> None:
+        """
+        Initialize the EmptyGroupBucketSliceError indicating that slicing a GroupBucket produced no results.
+
+        The exception carries the message "Cannot slice an empty GroupBucket."
+        """
+        super().__init__("Cannot slice an empty GroupBucket.")
+
+
+class InvalidGroupBucketIndexError(TypeError):
+    """Raised when a group bucket is indexed with an unsupported type."""
+
+    def __init__(self, received_type: type) -> None:
+        """
+        Initialize the exception for an unsupported GroupBucket index argument type.
+
+        Parameters:
+            received_type (type): The actual type that was passed as the index; used to construct the error message.
+        """
+        super().__init__(
+            f"Invalid argument type: {received_type}. Expected int or slice."
+        )
 
 
 class GroupBucket(Bucket[GeneralManagerType]):
@@ -65,40 +159,35 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def __checkGroupByArguments(self, group_by_keys: tuple[str, ...]) -> None:
         """
-        Validate the supplied group-by keys.
+        Validate that each provided group-by key is a string and is exposed by the manager interface.
 
         Parameters:
-            group_by_keys (tuple[str, ...]): Attribute names requested for grouping.
-
-        Returns:
-            None
+            group_by_keys (tuple[str, ...]): Attribute names to use for grouping.
 
         Raises:
-            TypeError: If a key is not a string.
-            ValueError: If a key is not an attribute exposed by the manager interface.
+            InvalidGroupByKeyTypeError: If any element of `group_by_keys` is not a string.
+            UnknownGroupByKeyError: If any key is not listed in the manager class's interface attributes.
         """
         if not all(isinstance(arg, str) for arg in group_by_keys):
-            raise TypeError("groupBy() arguments must be a strings")
+            raise InvalidGroupByKeyTypeError()
         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__}"
-            )
+            raise UnknownGroupByKeyError(self._manager_class.__name__)
 
     def __buildGroupedManager(
         self,
         data: Bucket[GeneralManagerType],
     ) -> list[GroupManager[GeneralManagerType]]:
         """
-        Construct grouped manager objects for every unique combination of key values.
+        Builds a GroupManager for each distinct combination of configured group-by attribute values.
 
         Parameters:
-            data (Bucket[GeneralManagerType]): Source bucket that will be partitioned by the configured keys.
+            data (Bucket[GeneralManagerType]): Source bucket whose entries are partitioned by the bucket's configured group-by keys.
 
         Returns:
-            list[GroupManager[GeneralManagerType]]: Group managers covering all key combinations.
+            list[GroupManager[GeneralManagerType]]: A list of GroupManager objects, one per unique tuple of group-by key values; groups are produced in order sorted by the string representation of their key tuples.
         """
         group_by_values: set[tuple[tuple[str, Any], ...]] = set()
         for entry in data:
@@ -118,21 +207,24 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def __or__(self, other: object) -> GroupBucket[GeneralManagerType]:
         """
-        Combine two grouping buckets produced from the same manager class.
+        Return a new GroupBucket representing the union of this bucket and another compatible GroupBucket.
 
         Parameters:
-            other (object): Another grouping bucket to merge.
+            other (GroupBucket): The grouping bucket to merge with this one.
 
         Returns:
-            GroupBucket[GeneralManagerType]: Bucket representing the union of both inputs.
+            GroupBucket[GeneralManagerType]: A GroupBucket with the same manager class and grouping keys whose basis data is the union of both inputs.
 
         Raises:
-            ValueError: If `other` is not a compatible GroupBucket instance.
+            GroupBucketTypeMismatchError: If `other` is not a GroupBucket of the same class.
+            GroupBucketManagerMismatchError: If `other` tracks a different manager class.
         """
         if not isinstance(other, self.__class__):
-            raise ValueError("Cannot combine different bucket types")
+            raise GroupBucketTypeMismatchError(self.__class__, type(other))
         if self._manager_class != other._manager_class:
-            raise ValueError("Cannot combine different manager classes")
+            raise GroupBucketManagerMismatchError(
+                self._manager_class, other._manager_class
+            )
         return GroupBucket(
             self._manager_class,
             self._group_by_keys,
@@ -226,40 +318,37 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def get(self, **kwargs: Any) -> GroupManager[GeneralManagerType]:
         """
-        Retrieve the first grouped manager matching the supplied filters.
+        Retrieve the first GroupManager matching the provided lookups.
 
         Parameters:
-            **kwargs: Field lookups applied to the grouped data.
+            **kwargs: Field lookups used to filter the grouped managers.
 
         Returns:
-            GroupManager[GeneralManagerType]: Matching grouped manager.
+            The first matching GroupManager.
 
         Raises:
-            ValueError: If no grouped manager matches the filters.
+            GroupItemNotFoundError: If no grouped manager matches the filters.
         """
         first_value = self.filter(**kwargs).first()
         if first_value is None:
-            raise ValueError(
-                f"Cannot find {self._manager_class.__name__} with {kwargs}"
-            )
+            raise GroupItemNotFoundError(self._manager_class.__name__, kwargs)
         return first_value
 
     def __getitem__(
         self, item: int | slice
     ) -> GroupManager[GeneralManagerType] | GroupBucket[GeneralManagerType]:
         """
-        Access a specific group or a slice of groups.
+        Retrieve a single grouped manager by index or construct a new GroupBucket from a slice of groups.
 
         Parameters:
-            item (int | slice): Index or slice describing the desired groups.
+            item (int | slice): Integer index to select a single GroupManager, or a slice to select a subsequence of groups.
 
         Returns:
-            GroupManager[GeneralManagerType] | GroupBucket[GeneralManagerType]:
-                Group at the specified index or a new bucket built from the selected groups.
+            GroupManager[GeneralManagerType] if `item` is an int, otherwise a GroupBucket[GeneralManagerType] built from the selected groups.
 
         Raises:
-            ValueError: If the requested slice contains no groups.
-            TypeError: If the argument is not an integer or slice.
+            EmptyGroupBucketSliceError: If the slice selects no groups.
+            InvalidGroupBucketIndexError: If `item` is not an int or slice.
         """
         if isinstance(item, int):
             return self._data[item]
@@ -272,9 +361,9 @@ class GroupBucket(Bucket[GeneralManagerType]):
                 else:
                     new_base_data = new_base_data | manager._data
             if new_base_data is None:
-                raise ValueError("Cannot slice an empty GroupBucket")
+                raise EmptyGroupBucketSliceError()
             return GroupBucket(self._manager_class, self._group_by_keys, new_base_data)
-        raise TypeError(f"Invalid argument type: {type(item)}. Expected int or slice.")
+        raise InvalidGroupBucketIndexError(type(item))
 
     def __len__(self) -> int:
         """

general_manager/cache/__init__.py

@@ -12,10 +12,19 @@ __all__ = list(CACHE_EXPORTS)
 _MODULE_MAP = CACHE_EXPORTS
 
 if TYPE_CHECKING:
-    from general_manager._types.cache import *  # noqa: F401,F403
+    from general_manager._types.cache import *  # noqa: F403
 
 
 def __getattr__(name: str) -> Any:
+    """
+    Resolve a public API export by attribute name for module-level dynamic access.
+
+    Parameters:
+        name (str): The attribute name being accessed on the module.
+
+    Returns:
+        Any: The object exported under `name` from the module's cached public API, or raises AttributeError if not found.
+    """
     return resolve_export(
         name,
         module_all=__all__,