GeneralManager 0.14.1__py3-none-any.whl → 0.15.0__py3-none-any.whl

general_manager/bucket/groupBucket.py

@@ -1,10 +1,11 @@
+"""Grouping bucket implementation for aggregating GeneralManager instances."""
+
 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,
@@ -13,37 +14,46 @@ from general_manager.bucket.baseBucket import (
 
 
 class GroupBucket(Bucket[GeneralManagerType]):
+    """Bucket variant that groups managers by specified attributes."""
 
     def __init__(
         self,
         manager_class: Type[GeneralManagerType],
         group_by_keys: tuple[str, ...],
         data: Bucket[GeneralManagerType],
-    ):
+    ) -> None:
         """
-        Initializes a GroupBucket by grouping data based on specified attribute keys.
+        Build a grouping bucket from the provided base data.
+
+        Parameters:
+            manager_class (type[GeneralManagerType]): GeneralManager subclass represented by the bucket.
+            group_by_keys (tuple[str, ...]): Attribute names used to define each group.
+            data (Bucket[GeneralManagerType]): Source bucket whose entries are grouped.
 
-        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.
+        Returns:
+            None
 
         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.
+            TypeError: If a group-by key is not a string.
+            ValueError: If a group-by key is not a valid manager attribute.
         """
         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
+        self._data: list[GroupManager[GeneralManagerType]] = self.__buildGroupedManager(
+            data
+        )
+        self._basis_data: Bucket[GeneralManagerType] = 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.
+        Compare two grouping buckets for equality.
+
+        Parameters:
+            other (object): Object compared against the current bucket.
 
         Returns:
-            True if both instances have identical grouped data, manager class, and group-by keys; otherwise, False.
+            bool: True when grouped data, manager class, and grouping keys match.
         """
         if not isinstance(other, self.__class__):
             return False
@@ -55,11 +65,17 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     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.
+        Validate the supplied group-by keys.
+
+        Parameters:
+            group_by_keys (tuple[str, ...]): Attribute names requested for grouping.
+
+        Returns:
+            None
 
         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.
+            TypeError: If a key is not a string.
+            ValueError: If a key is not an attribute exposed by the manager interface.
         """
         if not all(isinstance(arg, str) for arg in group_by_keys):
             raise TypeError("groupBy() arguments must be a strings")
@@ -76,20 +92,20 @@ class GroupBucket(Bucket[GeneralManagerType]):
         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.
+        Construct grouped manager objects for every unique combination of key values.
 
-        Args:
-            data: The bucket of manager instances to be grouped.
+        Parameters:
+            data (Bucket[GeneralManagerType]): Source bucket that will be partitioned by the configured keys.
 
         Returns:
-            A list of GroupManager objects, each corresponding to a unique combination of group-by attribute values found in the data.
+            list[GroupManager[GeneralManagerType]]: Group managers covering all key combinations.
         """
         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 = []
+        groups: list[GroupManager[GeneralManagerType]] = []
         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)
@@ -102,10 +118,16 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def __or__(self, other: object) -> GroupBucket[GeneralManagerType]:
         """
-        Returns a new GroupBucket representing the union of this bucket and another, combining their underlying data.
+        Combine two grouping buckets produced from the same manager class.
+
+        Parameters:
+            other (object): Another grouping bucket to merge.
+
+        Returns:
+            GroupBucket[GeneralManagerType]: Bucket representing the union of both inputs.
 
         Raises:
-            ValueError: If the other object is not a GroupBucket of the same type or uses a different manager class.
+            ValueError: If `other` is not a compatible GroupBucket instance.
         """
         if not isinstance(other, self.__class__):
             raise ValueError("Cannot combine different bucket types")
@@ -119,18 +141,22 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def __iter__(self) -> Generator[GroupManager[GeneralManagerType], None, None]:
         """
-        Yields each grouped manager in the current GroupBucket.
+        Iterate over the grouped managers produced by this bucket.
 
-        Returns:
-            A generator yielding GroupManager instances representing each group.
+        Yields:
+            GroupManager[GeneralManagerType]: Individual group manager instances.
         """
         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.
+        Return a grouped bucket filtered by the provided lookups.
 
-        Keyword arguments correspond to attribute-value pairs used for filtering.
+        Parameters:
+            **kwargs: Field lookups evaluated against the underlying bucket.
+
+        Returns:
+            GroupBucket[GeneralManagerType]: Grouped bucket containing only matching records.
         """
         new_basis_data = self._basis_data.filter(**kwargs)
         return GroupBucket(
@@ -141,9 +167,13 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def exclude(self, **kwargs: Any) -> GroupBucket[GeneralManagerType]:
         """
-        Returns a new GroupBucket excluding entries from the underlying data that match the given criteria.
+        Return a grouped bucket that excludes records matching the provided lookups.
 
-        Keyword arguments specify attribute-value pairs to exclude from the basis data. The resulting GroupBucket retains the same grouping keys and manager class.
+        Parameters:
+            **kwargs: Field lookups whose matches should be removed from the underlying bucket.
+
+        Returns:
+            GroupBucket[GeneralManagerType]: Grouped bucket built from the filtered base data.
         """
         new_basis_data = self._basis_data.exclude(**kwargs)
         return GroupBucket(
@@ -154,7 +184,10 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def first(self) -> GroupManager[GeneralManagerType] | None:
         """
-        Returns the first grouped manager in the collection, or None if the collection is empty.
+        Return the first grouped manager in the collection.
+
+        Returns:
+            GroupManager[GeneralManagerType] | None: First group when available.
         """
         try:
             return next(iter(self))
@@ -163,7 +196,10 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def last(self) -> GroupManager[GeneralManagerType] | None:
         """
-        Returns the last grouped manager in the collection, or None if the collection is empty.
+        Return the last grouped manager in the collection.
+
+        Returns:
+            GroupManager[GeneralManagerType] | None: Last group when available.
         """
         items = list(self)
         if items:
@@ -172,30 +208,34 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def count(self) -> int:
         """
-        Returns the number of grouped managers in the bucket.
+        Count the number of grouped managers in the bucket.
+
+        Returns:
+            int: Number of groups.
         """
         return sum(1 for _ in self)
 
     def all(self) -> Bucket[GeneralManagerType]:
         """
-        Returns the current GroupBucket instance.
+        Return the current grouping bucket.
 
-        This method provides compatibility with interfaces expecting an `all()` method to retrieve the full collection.
+        Returns:
+            Bucket[GeneralManagerType]: This instance.
         """
         return self
 
     def get(self, **kwargs: Any) -> GroupManager[GeneralManagerType]:
         """
-        Returns the first grouped manager matching the specified filter criteria.
+        Retrieve the first grouped manager matching the supplied filters.
 
-        Args:
-            **kwargs: Attribute-value pairs to filter grouped managers.
+        Parameters:
+            **kwargs: Field lookups applied to the grouped data.
 
         Returns:
-            The first GroupManager instance matching the filter criteria.
+            GroupManager[GeneralManagerType]: Matching grouped manager.
 
         Raises:
-            ValueError: If no grouped manager matches the provided criteria.
+            ValueError: If no grouped manager matches the filters.
         """
         first_value = self.filter(**kwargs).first()
         if first_value is None:
@@ -208,13 +248,18 @@ class GroupBucket(Bucket[GeneralManagerType]):
         self, item: int | slice
     ) -> GroupManager[GeneralManagerType] | GroupBucket[GeneralManagerType]:
         """
-        Returns a grouped manager by index or a new GroupBucket by slice.
+        Access a specific group or a slice of groups.
+
+        Parameters:
+            item (int | slice): Index or slice describing the desired groups.
 
-        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.
+        Returns:
+            GroupManager[GeneralManagerType] | GroupBucket[GeneralManagerType]:
+                Group at the specified index or a new bucket built from the selected groups.
 
         Raises:
-            ValueError: If slicing results in no groups.
-            TypeError: If the argument is not an int or slice.
+            ValueError: If the requested slice contains no groups.
+            TypeError: If the argument is not an integer or slice.
         """
         if isinstance(item, int):
             return self._data[item]
@@ -233,19 +278,22 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def __len__(self) -> int:
         """
-        Returns the number of grouped managers in the GroupBucket.
+        Return the number of grouped managers.
+
+        Returns:
+            int: Number of groups.
         """
         return self.count()
 
     def __contains__(self, item: GeneralManagerType) -> bool:
         """
-        Checks if the given manager instance is present in the underlying basis data.
+        Determine whether the given manager instance exists in the underlying data.
 
-        Args:
-            item: The manager instance to check for membership.
+        Parameters:
+            item (GeneralManagerType): Manager instance checked for membership.
 
         Returns:
-            True if the item exists in the basis data; otherwise, False.
+            bool: True if the instance is present in the basis data.
         """
         return item in self._basis_data
 
@@ -255,14 +303,14 @@ class GroupBucket(Bucket[GeneralManagerType]):
         reverse: bool = False,
     ) -> Bucket[GeneralManagerType]:
         """
-        Returns a new GroupBucket with grouped managers sorted by the specified attribute keys.
+        Return a new GroupBucket sorted by the specified attributes.
 
-        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.
+        Parameters:
+            key (str | tuple[str, ...]): Attribute name(s) used for sorting.
+            reverse (bool): Whether to apply descending order.
 
         Returns:
-            A new GroupBucket instance with grouped managers sorted by the given keys.
+            Bucket[GeneralManagerType]: Sorted grouping bucket.
         """
         if isinstance(key, str):
             key = (key,)
@@ -285,9 +333,13 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def group_by(self, *group_by_keys: str) -> GroupBucket[GeneralManagerType]:
         """
-        Return a new GroupBucket grouped by the current and additional attribute keys.
-        
-        Additional group-by keys are appended to the existing grouping, and the new GroupBucket is constructed from the same underlying data.
+        Extend the grouping with additional attribute keys.
+
+        Parameters:
+            *group_by_keys (str): Attribute names appended to the current grouping.
+
+        Returns:
+            GroupBucket[GeneralManagerType]: New bucket grouped by the combined key set.
         """
         return GroupBucket(
             self._manager_class,
@@ -297,9 +349,10 @@ class GroupBucket(Bucket[GeneralManagerType]):
 
     def none(self) -> GroupBucket[GeneralManagerType]:
         """
-        Return a new empty GroupBucket with the same manager class and group-by keys as the current instance.
-        
-        This method creates a GroupBucket containing no items, preserving the grouping configuration of the original.
+        Produce an empty grouping bucket that preserves the current configuration.
+
+        Returns:
+            GroupBucket[GeneralManagerType]: Empty grouping bucket with identical manager class and grouping keys.
         """
         return GroupBucket(
             self._manager_class, self._group_by_keys, self._basis_data.none()

general_manager/cache/__init__.py

@@ -0,0 +1,38 @@
+"""Caching helpers for GeneralManager dependencies."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from general_manager.utils.public_api import build_module_dir, resolve_export
+
+__all__ = [
+    "cached",
+    "CacheBackend",
+    "DependencyTracker",
+    "record_dependencies",
+    "remove_cache_key_from_index",
+    "invalidate_cache_key",
+]
+
+_MODULE_MAP = {
+    "cached": ("general_manager.cache.cacheDecorator", "cached"),
+    "CacheBackend": ("general_manager.cache.cacheDecorator", "CacheBackend"),
+    "DependencyTracker": ("general_manager.cache.cacheTracker", "DependencyTracker"),
+    "record_dependencies": ("general_manager.cache.dependencyIndex", "record_dependencies"),
+    "remove_cache_key_from_index": ("general_manager.cache.dependencyIndex", "remove_cache_key_from_index"),
+    "invalidate_cache_key": ("general_manager.cache.dependencyIndex", "invalidate_cache_key"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    return resolve_export(
+        name,
+        module_all=__all__,
+        module_map=_MODULE_MAP,
+        module_globals=globals(),
+    )
+
+
+def __dir__() -> list[str]:
+    return build_module_dir(module_all=__all__, module_globals=globals())

general_manager/cache/cacheDecorator.py

@@ -1,4 +1,6 @@
-from typing import Any, Callable, Optional, Protocol, Set
+"""Helpers for caching GeneralManager computations with dependency tracking."""
+
+from typing import Any, Callable, Optional, Protocol, Set, TypeVar, cast
 from functools import wraps
 from django.core.cache import cache as django_cache
 from general_manager.cache.cacheTracker import DependencyTracker
@@ -10,30 +12,34 @@ from general_manager.utils.makeCacheKey import make_cache_key
 class CacheBackend(Protocol):
     def get(self, key: str, default: Optional[Any] = None) -> Any:
         """
-        Retrieves a value from the cache by key, returning a default if the key is not found.
+        Retrieve a value from the cache, falling back to a default.
 
-        Args:
-            key: The cache key to look up.
-            default: Value to return if the key is not present in the cache.
+        Parameters:
+            key (str): Cache key identifying the stored entry.
+            default (Any | None): Value returned when the key is absent.
 
         Returns:
-            The cached value if found; otherwise, the provided default.
+            Any: Cached value when available; otherwise, `default`.
         """
         ...
 
     def set(self, key: str, value: Any, timeout: Optional[int] = None) -> None:
         """
-        Stores a value in the cache under the specified key with an optional expiration timeout.
+        Store a value in the cache with an optional expiration timeout.
+
+        Parameters:
+            key (str): Cache key identifying the stored entry.
+            value (Any): Object written to the cache.
+            timeout (int | None): Expiration in seconds; `None` stores the value indefinitely.
 
-        Args:
-            key: The cache key to associate with the value.
-            value: The value to store in the cache.
-            timeout: Optional expiration time in seconds. If None, the value is cached indefinitely.
+        Returns:
+            None
         """
         ...
 
 
 RecordFn = Callable[[str, Set[Dependency]], None]
+FuncT = TypeVar("FuncT", bound=Callable[..., object])
 
 _SENTINEL = object()
 
@@ -42,16 +48,22 @@ def cached(
     timeout: Optional[int] = None,
     cache_backend: CacheBackend = django_cache,
     record_fn: RecordFn = record_dependencies,
-) -> Callable:
+) -> Callable[[FuncT], FuncT]:
     """
-    Decorator that caches function results and tracks their dependencies.
+    Cache a function call while registering its data dependencies.
+
+    Parameters:
+        timeout (int | None): Expiration in seconds for cached values; `None` stores results until invalidated.
+        cache_backend (CacheBackend): Backend used to read and write cached results.
+        record_fn (RecordFn): Callback invoked to persist dependency metadata when no timeout is defined.
 
-    When applied to a function, this decorator caches the function's output using a generated cache key based on its arguments. It also tracks dependencies accessed during the function's execution and stores them alongside the cached result. On cache hits, previously stored dependencies are re-tracked to maintain dependency tracking continuity. If dependencies exist and no timeout is set, an external recording function is invoked to persist the dependency information.
+    Returns:
+        Callable: Decorator that wraps the target function with caching behaviour.
     """
 
-    def decorator(func: Callable) -> Callable:
+    def decorator(func: FuncT) -> FuncT:
         @wraps(func)
-        def wrapper(*args, **kwargs):
+        def wrapper(*args: object, **kwargs: object) -> object:
             key = make_cache_key(func, args, kwargs)
             deps_key = f"{key}:deps"
 
@@ -76,6 +88,6 @@ def cached(
 
             return result
 
-        return wrapper
+        return cast(FuncT, wrapper)
 
     return decorator

general_manager/cache/cacheTracker.py

@@ -1,11 +1,15 @@
+"""Context manager utilities for tracking cache dependencies per thread."""
+
 import threading
+from types import TracebackType
+
 from general_manager.cache.dependencyIndex import (
-    general_manager_name,
     Dependency,
     filter_type,
+    general_manager_name,
 )
 
-# Thread-lokale Variable zur Speicherung der Abhängigkeiten
+# Thread-local storage for tracking dependencies
 _dependency_storage = threading.local()
 
 
@@ -14,12 +18,10 @@ class DependencyTracker:
         self,
     ) -> set[Dependency]:
         """
-        Enters a new dependency tracking context and returns the set for collecting dependencies.
-
-        Initializes thread-local storage for dependency tracking if not already present, supports nested contexts, and provides a set to accumulate dependencies at the current nesting level.
+        Enter a dependency tracking context and return the collector set.
 
         Returns:
-            The set used to collect dependencies for the current context level.
+            set[Dependency]: Mutable set capturing dependencies discovered inside the context.
         """
         if not hasattr(_dependency_storage, "dependencies"):
             _dependency_storage._depth = 0
@@ -29,18 +31,29 @@ class DependencyTracker:
         _dependency_storage.dependencies.append(set())
         return _dependency_storage.dependencies[_dependency_storage._depth]
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
         """
-        Exits the dependency tracking context, managing cleanup for nested scopes.
+        Leave the dependency tracking context and perform nested-scope cleanup.
+
+        Parameters:
+            exc_type: Exception type raised within the context, if any.
+            exc_val: Exception instance raised within the context, if any.
+            exc_tb: Traceback generated by the exception, if any.
 
-        If exiting the outermost context, removes all dependency tracking data from thread-local storage. Otherwise, decrements the nesting depth and removes the most recent dependency set.
+        Returns:
+            None
         """
         if hasattr(_dependency_storage, "dependencies"):
             if _dependency_storage._depth == 0:
                 self.reset_thread_local_storage()
 
             else:
-                # Ansonsten reduzieren wir nur die Tiefe
+                # For nested contexts only reduce depth and pop one level.
                 _dependency_storage._depth -= 1
                 _dependency_storage.dependencies.pop()
 
@@ -51,23 +64,29 @@ class DependencyTracker:
         identifier: str,
     ) -> None:
         """
-        Records a dependency in all active dependency tracking contexts.
+        Record a dependency tuple in the active tracking scopes.
 
-        Adds the specified dependency tuple to each set in the current stack of dependency tracking scopes, ensuring it is tracked at all nested levels.
+        Parameters:
+            class_name (str): Name of the GeneralManager subclass.
+            operation (filter_type): Operation being tracked, such as `filter` or `exclude`.
+            identifier (str): String representation of the lookup parameters.
+
+        Returns:
+            None
         """
         if hasattr(_dependency_storage, "dependencies"):
             for dep_set in _dependency_storage.dependencies[
                 : _dependency_storage._depth + 1
             ]:
-                dep_set: set[Dependency]
                 dep_set.add((class_name, operation, identifier))
 
     @staticmethod
     def reset_thread_local_storage() -> None:
         """
-        Resets the thread-local storage for dependency tracking.
+        Clear all dependency tracking data from thread-local storage.
 
-        This method clears the thread-local storage, ensuring that all dependency tracking data is removed. It is useful for cleaning up after operations that may have modified the state of the tracker.
+        Returns:
+            None
         """
         if hasattr(_dependency_storage, "dependencies"):
             del _dependency_storage.dependencies