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

general_manager/cache/dependencyIndex.py

@@ -1,3 +1,5 @@
+"""Dependency index management for cached GeneralManager query results."""
+
 from __future__ import annotations
 import time
 import ast
@@ -7,7 +9,7 @@ import logging
 from django.core.cache import cache
 from general_manager.cache.signals import post_data_change, pre_data_change
 from django.dispatch import receiver
-from typing import Literal, Any, Iterable, TYPE_CHECKING, Type, Tuple
+from typing import Literal, Any, Iterable, TYPE_CHECKING, Type, Tuple, cast
 
 if TYPE_CHECKING:
     from general_manager.manager.generalManager import GeneralManager
@@ -33,22 +35,35 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 # CONFIG
 # -----------------------------------------------------------------------------
-INDEX_KEY = "dependency_index"  # Key unter dem der gesamte Index liegt
-LOCK_KEY = "dependency_index_lock"  # Key für das Sperr‑Mutex
-LOCK_TIMEOUT = 5  # Sekunden TTL für den Lock
-UNDEFINED = object()  # Dummy für nicht definierte Werte
+INDEX_KEY = "dependency_index"  # Cache key storing the complete dependency index
+LOCK_KEY = "dependency_index_lock"  # Cache key used for the dependency lock
+LOCK_TIMEOUT = 5  # Lock TTL in seconds
+UNDEFINED = object()  # Sentinel for undefined values
 
 
 # -----------------------------------------------------------------------------
 # LOCKING HELPERS
 # -----------------------------------------------------------------------------
 def acquire_lock(timeout: int = LOCK_TIMEOUT) -> bool:
-    """Atomar: create Lock key if it doesn't exist."""
+    """
+    Attempt to acquire the cache-backed lock guarding dependency writes.
+
+    Parameters:
+        timeout (int): Expiration time for the lock entry in seconds.
+
+    Returns:
+        bool: True if the lock was acquired; otherwise, False.
+    """
     return cache.add(LOCK_KEY, "1", timeout)
 
 
 def release_lock() -> None:
-    """Release Lock key."""
+    """
+    Release the cache-backed lock guarding dependency writes.
+
+    Returns:
+        None
+    """
     cache.delete(LOCK_KEY)
 
 
@@ -56,16 +71,30 @@ def release_lock() -> None:
 # INDEX ACCESS
 # -----------------------------------------------------------------------------
 def get_full_index() -> dependency_index:
-    """Load or initialize the full index."""
-    idx = cache.get(INDEX_KEY, None)
-    if idx is None:
+    """
+    Fetch the dependency index from cache, initialising it on first access.
+
+    Returns:
+        dependency_index: Mapping of tracked filters and excludes keyed by manager name.
+    """
+    cached_index = cache.get(INDEX_KEY, None)
+    if cached_index is None:
         idx: dependency_index = {"filter": {}, "exclude": {}}
         cache.set(INDEX_KEY, idx, None)
-    return idx
+        return idx
+    return cast(dependency_index, cached_index)
 
 
 def set_full_index(idx: dependency_index) -> None:
-    """Write the complete index back to the cache."""
+    """
+    Persist the dependency index to cache.
+
+    Parameters:
+        idx (dependency_index): Updated index that should replace the cached value.
+
+    Returns:
+        None
+    """
     cache.set(INDEX_KEY, idx, None)
 
 
@@ -82,6 +111,20 @@ def record_dependencies(
         ]
     ],
 ) -> None:
+    """
+    Register cache keys against the filters and exclusions they depend on.
+
+    Parameters:
+        cache_key (str): Cache key produced for the cached queryset.
+        dependencies (Iterable[tuple[str, Literal["filter", "exclude", "identification"], str]]):
+            Collection describing manager name, dependency type, and identifying data.
+
+    Returns:
+        None
+
+    Raises:
+        TimeoutError: If the dependency lock cannot be acquired within `LOCK_TIMEOUT`.
+    """
     start = time.time()
     while not acquire_lock():
         if time.time() - start > LOCK_TIMEOUT:
@@ -92,15 +135,16 @@ def record_dependencies(
         idx = get_full_index()
         for model_name, action, identifier in dependencies:
             if action in ("filter", "exclude"):
+                action_key = cast(Literal["filter", "exclude"], action)
                 params = ast.literal_eval(identifier)
-                section = idx[action].setdefault(model_name, {})
+                section = idx[action_key].setdefault(model_name, {})
                 for lookup, val in params.items():
                     lookup_map = section.setdefault(lookup, {})
                     val_key = repr(val)
                     lookup_map.setdefault(val_key, set()).add(cache_key)
 
             else:
-                # director ID Lookup as simple filter on 'id'
+                # Treat identification lookups as a simple filter on `id`
                 section = idx["filter"].setdefault(model_name, {})
                 lookup_map = section.setdefault("identification", {})
                 val_key = identifier
@@ -116,7 +160,18 @@ def record_dependencies(
 # INDEX CLEANUP
 # -----------------------------------------------------------------------------
 def remove_cache_key_from_index(cache_key: str) -> None:
-    """Remove a cache key from the index."""
+    """
+    Remove a cache entry from all dependency mappings.
+
+    Parameters:
+        cache_key (str): Cache key that should be expunged from the index.
+
+    Returns:
+        None
+
+    Raises:
+        TimeoutError: If the dependency lock cannot be acquired within `LOCK_TIMEOUT`.
+    """
     start = time.time()
     while not acquire_lock():
         if time.time() - start > LOCK_TIMEOUT:
@@ -147,13 +202,35 @@ def remove_cache_key_from_index(cache_key: str) -> None:
 # CACHE INVALIDATION
 # -----------------------------------------------------------------------------
 def invalidate_cache_key(cache_key: str) -> None:
+    """
+    Delete the cached result associated with the provided key.
+
+    Parameters:
+        cache_key (str): Key referencing the cached queryset.
+
+    Returns:
+        None
+    """
     cache.delete(cache_key)
 
 
 @receiver(pre_data_change)
 def capture_old_values(
-    sender: Type[GeneralManager], instance: GeneralManager | None, **kwargs
+    sender: Type[GeneralManager],
+    instance: GeneralManager | None,
+    **kwargs: object,
 ) -> None:
+    """
+    Cache the field values referenced by tracked filters before an update.
+
+    Parameters:
+        sender (type[GeneralManager]): Manager class dispatching the signal.
+        instance (GeneralManager | None): Manager instance about to change.
+        **kwargs: Additional signal metadata.
+
+    Returns:
+        None
+    """
     if instance is None:
         return
     manager_name = sender.__name__
@@ -164,16 +241,16 @@ def capture_old_values(
         lookups |= set(idx.get(action, {}).get(manager_name, {}))
     if lookups and instance.identification:
         # save old values for later comparison
-        vals = {}
+        vals: dict[str, object] = {}
         for lookup in lookups:
             attr_path = lookup.split("__")
-            obj = instance
+            current: object = instance
             for i, attr in enumerate(attr_path):
-                if getattr(obj, attr, UNDEFINED) is UNDEFINED:
+                if getattr(current, attr, UNDEFINED) is UNDEFINED:
                     lookup = "__".join(attr_path[:i])
                     break
-                obj = getattr(obj, attr, None)
-            vals[lookup] = obj
+                current = getattr(current, attr, None)
+            vals[lookup] = current
         setattr(instance, "_old_values", vals)
 
 
@@ -182,12 +259,19 @@ def generic_cache_invalidation(
     sender: type[GeneralManager],
     instance: GeneralManager,
     old_relevant_values: dict[str, Any],
-    **kwargs,
-):
+    **kwargs: object,
+) -> None:
     """
-    Invalidates cached query results related to a model instance when its data changes.
-    
-    This function is intended to be used as a Django signal handler. It compares old and new values of relevant fields on a model instance against registered cache dependencies (filters and excludes). If a change affects any cached queryset result, the corresponding cache keys are invalidated and removed from the dependency index.
+    Invalidate cached query results affected by a data change.
+
+    Parameters:
+        sender (type[GeneralManager]): Manager class that triggered the signal.
+        instance (GeneralManager): Updated manager instance.
+        old_relevant_values (dict[str, Any]): Previously captured values for tracked lookups.
+        **kwargs: Additional signal metadata.
+
+    Returns:
+        None
     """
     manager_name = sender.__name__
     idx = get_full_index()
@@ -208,7 +292,7 @@ def generic_cache_invalidation(
             except:
                 return False
 
-        # range
+        # range comparisons
         if op in ("gt", "gte", "lt", "lte"):
             try:
                 thr = type(value)(ast.literal_eval(val_key))
@@ -223,7 +307,7 @@ def generic_cache_invalidation(
             if op == "lte":
                 return value <= thr
 
-        # wildcard / regex
+        # wildcard / regex comparisons
         if op in ("contains", "startswith", "endswith", "regex"):
             try:
                 literal = ast.literal_eval(val_key)
@@ -238,7 +322,7 @@ def generic_cache_invalidation(
                 return text.startswith(literal)
             if op == "endswith":
                 return text.endswith(literal)
-            # regex: val_key selbst als Pattern benutzen
+            # regex: treat the stored key as the regex pattern
             if op == "regex":
                 try:
                     pattern = re.compile(val_key)
@@ -273,12 +357,12 @@ def generic_cache_invalidation(
             # 2) get old & new value
             old_val = old_relevant_values.get("__".join(attr_path))
 
-            obj = instance
+            current: object = instance
             for attr in attr_path:
-                obj = getattr(obj, attr, None)
-                if obj is None:
+                current = getattr(current, attr, None)
+                if current is None:
                     break
-            new_val = obj
+            new_val = current
 
             # 3) check against all cache_keys
             for val_key, cache_keys in list(lookup_map.items()):

general_manager/cache/modelDependencyCollector.py

@@ -1,3 +1,5 @@
+"""Helpers that derive cache dependency metadata from GeneralManager objects."""
+
 from typing import Generator
 from general_manager.manager.generalManager import GeneralManager
 from general_manager.bucket.baseBucket import Bucket
@@ -9,21 +11,20 @@ from general_manager.cache.dependencyIndex import (
 
 
 class ModelDependencyCollector:
+    """Collect dependency tuples from cached arguments."""
 
     @staticmethod
     def collect(
-        obj,
+        obj: object,
     ) -> Generator[tuple[general_manager_name, filter_type, str], None, None]:
         """
-        Recursively extracts dependency information from Django model-related objects.
-
-        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.
+        Traverse arbitrary objects and yield cache dependency tuples.
 
-        Args:
-            obj: The object or collection to inspect for model dependencies.
+        Parameters:
+            obj (object): Object that may contain GeneralManager instances, buckets, or nested collections.
 
         Yields:
-            Tuples of (manager class name, dependency type, dependency value) for each dependency discovered.
+            tuple[str, filter_type, str]: Dependency descriptors combining manager name, dependency type, and lookup data.
         """
         if isinstance(obj, GeneralManager):
             yield (
@@ -44,7 +45,15 @@ class ModelDependencyCollector:
     @staticmethod
     def addArgs(dependencies: set[Dependency], args: tuple, kwargs: dict) -> None:
         """
-        Add dependencies to the dependency set.
+        Enrich the dependency set with values discovered in positional and keyword arguments.
+
+        Parameters:
+            dependencies (set[Dependency]): Target collection that accumulates dependency tuples.
+            args (tuple): Positional arguments from the cached function.
+            kwargs (dict): Keyword arguments from the cached function.
+
+        Returns:
+            None
         """
         if args and isinstance(args[0], GeneralManager):
             inner_self = args[0]

general_manager/cache/signals.py

@@ -1,3 +1,5 @@
+"""Signals and decorators for tracking GeneralManager data changes."""
+
 from django.dispatch import Signal
 from typing import Callable, TypeVar, ParamSpec, cast
 
@@ -13,17 +15,26 @@ R = TypeVar("R")
 
 def dataChange(func: Callable[P, R]) -> Callable[P, R]:
     """
-    Decorator that emits pre- and post-data change signals around the execution of the decorated function.
-    
-    Sends the `pre_data_change` signal before the wrapped function is called and the `post_data_change` signal after it completes. The signals include information about the sender, action, and relevant instance state before and after the change. Handles both regular functions and classmethods. Intended for use with functions that modify data to enable signal-based hooks for data change events.
+    Wrap a data-modifying function with pre- and post-change signal dispatching.
+
+    Parameters:
+        func (Callable[P, R]): Function that performs a data mutation.
+
+    Returns:
+        Callable[P, R]: Wrapped function that sends `pre_data_change` and `post_data_change` signals.
     """
 
     @wraps(func)
     def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         """
-        Wraps a function to emit pre- and post-data change signals around its execution.
-        
-        Sends the `pre_data_change` signal before the wrapped function is called and the `post_data_change` signal after, providing context such as the sender, action name, and relevant instance data. Handles both regular functions and classmethods, and distinguishes the "create" action by omitting a pre-existing instance.
+        Execute the wrapped function while emitting data change signals.
+
+        Parameters:
+            *args: Positional arguments forwarded to the wrapped function.
+            **kwargs: Keyword arguments forwarded to the wrapped function.
+
+        Returns:
+            R: Result produced by the wrapped function.
         """
         action = func.__name__
         if func.__name__ == "create":

general_manager/factory/__init__.py

@@ -1,5 +1,34 @@
-from .factoryMethods import (
-    LazyMeasurement,
-    LazyDeltaDate,
-    LazyProjectName,
-)
+"""Factory helpers for generating GeneralManager test data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from general_manager.utils.public_api import build_module_dir, resolve_export
+
+__all__ = [
+    "AutoFactory",
+    "LazyMeasurement",
+    "LazyDeltaDate",
+    "LazyProjectName",
+]
+
+_MODULE_MAP = {
+    "AutoFactory": ("general_manager.factory.autoFactory", "AutoFactory"),
+    "LazyMeasurement": ("general_manager.factory.factoryMethods", "LazyMeasurement"),
+    "LazyDeltaDate": ("general_manager.factory.factoryMethods", "LazyDeltaDate"),
+    "LazyProjectName": ("general_manager.factory.factoryMethods", "LazyProjectName"),
+}
+
+
+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/factory/autoFactory.py

@@ -1,3 +1,5 @@
+"""Auto-generating factory utilities for GeneralManager models."""
+
 from __future__ import annotations
 from typing import TYPE_CHECKING, Type, Callable, Union, Any, TypeVar, Literal
 from django.db import models
@@ -14,10 +16,7 @@ modelsModel = TypeVar("modelsModel", bound=models.Model)
 
 
 class AutoFactory(DjangoModelFactory[modelsModel]):
-    """
-    A factory class that automatically generates values for model fields,
-    including handling of unique fields and constraints.
-    """
+    """Factory that auto-populates model fields based on interface metadata."""
 
     interface: Type[DBBasedInterface]
     _adjustmentMethod: (
@@ -29,18 +28,15 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, strategy: Literal["build", "create"], params: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Generates and populates one or more Django model instances with automatic field value assignment.
-        
-        Automatically fills unset model fields, excluding generic foreign keys and auto-created fields, and handles custom and special fields as defined by the interface. After instance creation or building, processes many-to-many relationships. Raises a ValueError if the model is not a subclass of Django's Model.
-        
+        Generate and populate model instances with automatically derived field values.
+
         Parameters:
-            strategy (Literal["build", "create"]): Determines whether to build (unsaved) or create (saved) the instance(s).
-            params (dict[str, Any]): Field values to use for instance generation; missing fields are auto-filled.
-        
+            strategy (Literal["build", "create"]): Whether to persist the generated instances.
+            params (dict[str, Any]): Field values supplied by the caller.
+
         Returns:
-            models.Model or list[models.Model]: The generated model instance or list of instances.
+            models.Model | list[models.Model]: Generated instance(s) matching the requested strategy.
         """
-        cls._original_params = params
         model = cls._meta.model
         if not issubclass(model, models.Model):
             raise ValueError("Model must be a type")
@@ -86,9 +82,11 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, obj: models.Model, attrs: dict[str, Any]
     ) -> None:
         """
-        Assigns related objects to all many-to-many fields of a Django model instance after it has been created.
-        
-        For each many-to-many field, sets the related objects from the provided attributes if available; otherwise, generates related objects automatically. Uses the Django ORM's `set` method to establish the relationships.
+        Assign related objects to many-to-many fields after creation/building.
+
+        Parameters:
+            obj (models.Model): Instance whose many-to-many relations should be populated.
+            attrs (dict[str, Any]): Original attributes passed to the factory.
         """
         for field in obj._meta.many_to_many:
             if field.name in attrs:
@@ -99,13 +97,15 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
                 getattr(obj, field.name).set(m2m_values)
 
     @classmethod
-    def _adjust_kwargs(cls, **kwargs: dict[str, Any]) -> dict[str, Any]:
-        # Remove ManyToMany fields from kwargs before object creation
+    def _adjust_kwargs(cls, **kwargs: Any) -> dict[str, Any]:
         """
-        Removes many-to-many fields from the provided keyword arguments before creating or building a model instance.
-        
+        Remove many-to-many keys from kwargs prior to model instantiation.
+
+        Parameters:
+            **kwargs (dict[str, Any]): Field values supplied by the caller.
+
         Returns:
-            dict[str, Any]: The keyword arguments with any many-to-many fields excluded.
+            dict[str, Any]: Keyword arguments with many-to-many entries stripped.
         """
         model: Type[models.Model] = cls._meta.model
         m2m_fields = {field.name for field in model._meta.many_to_many}
@@ -115,15 +115,18 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
 
     @classmethod
     def _create(
-        cls, model_class: Type[models.Model], *args: list[Any], **kwargs: dict[str, Any]
+        cls, model_class: Type[models.Model], *args: Any, **kwargs: Any
     ) -> models.Model | list[models.Model]:
         """
-        Create and save a Django model instance or multiple instances, optionally applying custom adjustment logic to field values.
-        
-        If an adjustment method is defined, it is used to generate or modify field values before instance creation. Otherwise, the model is instantiated and saved with the provided attributes.
-        
+        Create and save model instance(s), applying adjustment hooks when defined.
+
+        Parameters:
+            model_class (type[models.Model]): Django model class to instantiate.
+            *args: Unused positional arguments (required by factory_boy).
+            **kwargs (dict[str, Any]): Field values supplied by the caller.
+
         Returns:
-            A saved model instance or a list of saved instances.
+            models.Model | list[models.Model]: Saved instance(s).
         """
         kwargs = cls._adjust_kwargs(**kwargs)
         if cls._adjustmentMethod is not None:
@@ -132,15 +135,18 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
 
     @classmethod
     def _build(
-        cls, model_class: Type[models.Model], *args: list[Any], **kwargs: dict[str, Any]
+        cls, model_class: Type[models.Model], *args: Any, **kwargs: Any
     ) -> models.Model | list[models.Model]:
         """
-        Builds an unsaved instance or list of instances of the specified Django model class.
-        
-        If an adjustment method is defined, it is used to generate or modify field values before building. Many-to-many fields are excluded from the keyword arguments prior to instantiation.
-        
+        Build (without saving) model instance(s), applying adjustment hooks when defined.
+
+        Parameters:
+            model_class (type[models.Model]): Django model class to instantiate.
+            *args: Unused positional arguments (required by factory_boy).
+            **kwargs (dict[str, Any]): Field values supplied by the caller.
+
         Returns:
-            models.Model or list[models.Model]: The unsaved model instance or list of instances.
+            models.Model | list[models.Model]: Unsaved instance(s).
         """
         kwargs = cls._adjust_kwargs(**kwargs)
         if cls._adjustmentMethod is not None:
@@ -151,15 +157,17 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
 
     @classmethod
     def _modelCreation(
-        cls, model_class: Type[models.Model], **kwargs: dict[str, Any]
+        cls, model_class: Type[models.Model], **kwargs: Any
     ) -> models.Model:
         """
-        Create, validate, and save a Django model instance with the specified field values.
-        
-        Initializes the model, assigns attributes from keyword arguments, performs validation with `full_clean()`, and saves the instance to the database.
-        
+        Instantiate, validate, and save a model instance.
+
+        Parameters:
+            model_class (type[models.Model]): Model class to instantiate.
+            **kwargs (dict[str, Any]): Field assignments applied prior to saving.
+
         Returns:
-            The saved Django model instance.
+            models.Model: Saved instance.
         """
         obj = model_class()
         for field, value in kwargs.items():
@@ -170,18 +178,9 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
 
     @classmethod
     def _modelBuilding(
-        cls, model_class: Type[models.Model], **kwargs: dict[str, Any]
+        cls, model_class: Type[models.Model], **kwargs: Any
     ) -> models.Model:
-        """
-        Constructs an unsaved Django model instance with the specified field values.
-        
-        Parameters:
-            model_class (Type[models.Model]): The Django model class to instantiate.
-            **kwargs: Field values to assign to the model instance.
-        
-        Returns:
-            models.Model: An unsaved instance of the specified model with attributes set from kwargs.
-        """
+        """Construct an unsaved model instance with the provided field values."""
         obj = model_class()
         for field, value in kwargs.items():
             setattr(obj, field, value)
@@ -192,19 +191,17 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, use_creation_method: bool, params: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Creates or builds one or more model instances using the adjustment method to generate field values.
-        
-        If the adjustment method returns a single dictionary, a single instance is created or built. If it returns a list of dictionaries, multiple instances are created or built accordingly.
-        
+        Create or build instance(s) using the configured adjustment method.
+
         Parameters:
-            use_creation_method (bool): If True, instances are saved to the database; if False, instances are built but not saved.
-            params (dict[str, Any]): Arguments passed to the adjustment method for generating field values.
-        
+            use_creation_method (bool): Whether generated objects should be saved.
+            params (dict[str, Any]): Arguments forwarded to the adjustment callback.
+
         Returns:
-            models.Model or list[models.Model]: The created or built model instance(s).
-        
+            models.Model | list[models.Model]: Created or built instance(s).
+
         Raises:
-            ValueError: If the adjustment method is not defined.
+            ValueError: If no adjustment method has been configured.
         """
         model_cls = cls._meta.model
         if cls._adjustmentMethod is None: