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

general_manager/cache/dependencyIndex.py

@@ -33,6 +33,22 @@ type Dependency = Tuple[general_manager_name, filter_type, str]
 
 logger = logging.getLogger(__name__)
 
+
+class DependencyLockTimeoutError(TimeoutError):
+    """Raised when the dependency index lock cannot be acquired within the timeout."""
+
+    def __init__(self, operation: str) -> None:
+        """
+        Error raised when acquiring the dependency index lock times out.
+
+        Parameters:
+            operation (str): Name or description of the operation during which lock acquisition timed out.
+        """
+        super().__init__(
+            f"Timed out acquiring dependency index lock during {operation}."
+        )
+
+
 # -----------------------------------------------------------------------------
 # CONFIG
 # -----------------------------------------------------------------------------
@@ -40,6 +56,7 @@ INDEX_KEY = "dependency_index"  # Cache key storing the complete dependency inde
 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
+ACTIONS: tuple[Literal["filter"], Literal["exclude"]] = ("filter", "exclude")
 
 
 # -----------------------------------------------------------------------------
@@ -113,23 +130,22 @@ def record_dependencies(
     ],
 ) -> None:
     """
-    Register cache keys against the filters and exclusions they depend on.
+    Register a cache key as dependent on the given manager-level filters, exclusions, or identifications.
 
     Parameters:
-        cache_key (str): Cache key produced for the cached queryset.
+        cache_key (str): The cache key to associate with the declared dependencies.
         dependencies (Iterable[tuple[str, Literal["filter", "exclude", "identification"], str]]):
-            Collection describing manager name, dependency type, and identifying data.
-
-    Returns:
-        None
+            Iterable of tuples describing each dependency as (manager_name, action, identifier).
+            - For `filter` and `exclude`, `identifier` is a string representation of a mapping of lookups to values.
+            - For `identification`, `identifier` is the identifying value (treated as a lookup on `id`).
 
     Raises:
-        TimeoutError: If the dependency lock cannot be acquired within `LOCK_TIMEOUT`.
+        DependencyLockTimeoutError: If a lock cannot be acquired within the configured timeout while updating the index.
     """
     start = time.time()
     while not acquire_lock():
         if time.time() - start > LOCK_TIMEOUT:
-            raise TimeoutError("Could not aquire lock for record_dependencies")
+            raise DependencyLockTimeoutError("record_dependencies")
         time.sleep(0.05)
 
     try:
@@ -140,7 +156,9 @@ def record_dependencies(
                 params = ast.literal_eval(identifier)
                 section = idx[action_key].setdefault(model_name, {})
                 if len(params) > 1:
-                    cache_dependencies = section.setdefault("__cache_dependencies__", {})
+                    cache_dependencies = section.setdefault(
+                        "__cache_dependencies__", {}
+                    )
                     cache_dependencies.setdefault(cache_key, set()).add(identifier)
                 for lookup, val in params.items():
                     lookup_map = section.setdefault(lookup, {})
@@ -165,27 +183,26 @@ def record_dependencies(
 # -----------------------------------------------------------------------------
 def remove_cache_key_from_index(cache_key: str) -> None:
     """
-    Remove a cache entry from all dependency mappings.
+    Remove a cache key from all dependency mappings in the stored dependency index.
 
-    Parameters:
-        cache_key (str): Cache key that should be expunged from the index.
+    Acquires the dependency lock to update and persist the index; if the lock cannot be obtained within LOCK_TIMEOUT the operation fails.
 
-    Returns:
-        None
+    Parameters:
+        cache_key (str): The cache key to expunge from all recorded filter, exclude, and identification mappings.
 
     Raises:
-        TimeoutError: If the dependency lock cannot be acquired within `LOCK_TIMEOUT`.
+        DependencyLockTimeoutError: If the dependency lock cannot be acquired within LOCK_TIMEOUT.
     """
     start = time.time()
     while not acquire_lock():
         if time.time() - start > LOCK_TIMEOUT:
-            raise TimeoutError("Could not aquire lock for remove_cache_key_from_index")
+            raise DependencyLockTimeoutError("remove_cache_key_from_index")
         time.sleep(0.05)
 
     try:
         idx = get_full_index()
-        for action in ("filter", "exclude"):
-            action_section = idx.get(action, {})
+        for action in ACTIONS:
+            action_section = idx[action]
             for mname, model_section in list(action_section.items()):
                 cache_dependencies = model_section.get("__cache_dependencies__", {})
                 for lookup, lookup_map in list(model_section.items()):
@@ -232,15 +249,10 @@ def capture_old_values(
     **kwargs: object,
 ) -> None:
     """
-    Cache the field values referenced by tracked filters before an update.
+    Record the current values of fields referenced by tracked filters on the given manager instance before it changes.
 
     Parameters:
-        sender (type[GeneralManager]): Manager class dispatching the signal.
-        instance (GeneralManager | None): Manager instance about to change.
-        **kwargs: Additional signal metadata.
-
-    Returns:
-        None
+        instance (GeneralManager | None): Manager instance about to change; if provided, this function sets instance._old_values to a mapping of lookup keys to their current values for use by post-change invalidation logic.
     """
     if instance is None:
         return
@@ -248,8 +260,8 @@ def capture_old_values(
     idx = get_full_index()
     # get all lookups for this model
     lookups = set()
-    for action in ("filter", "exclude"):
-        model_section = idx.get(action, {}).get(manager_name, {})
+    for action in ACTIONS:
+        model_section = idx[action].get(manager_name)
         if isinstance(model_section, dict):
             lookups |= {
                 lookup
@@ -270,7 +282,7 @@ def capture_old_values(
                     break
                 current = getattr(current, attr, None)
             vals[lookup] = current
-        setattr(instance, "_old_values", vals)
+        instance._old_values = vals
 
 
 @receiver(post_data_change)
@@ -281,16 +293,14 @@ def generic_cache_invalidation(
     **kwargs: object,
 ) -> None:
     """
-    Invalidate cached query results affected by a data change.
+    Invalidate cache entries whose recorded dependencies are affected by changes to a GeneralManager instance.
 
-    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.
+    Uses the dependency index to compare previously captured values against the instance's current values for tracked lookups, evaluates both simple and composite dependency conditions for "filter" and "exclude" actions, and for any dependency that warrants invalidation it deletes the corresponding cache entry and removes its references from the index.
 
-    Returns:
-        None
+    Parameters:
+        sender (type[GeneralManager]): Manager class that emitted the signal.
+        instance (GeneralManager): The manager instance that was changed.
+        old_relevant_values (dict[str, Any]): Mapping of lookup paths (joined by "__") to their values as captured before the change; used to compare old vs. new values for invalidation decisions.
     """
     manager_name = sender.__name__
     idx = get_full_index()
@@ -304,6 +314,22 @@ def generic_cache_invalidation(
         return value
 
     def _coerce_to_type(sample: Any, raw: Any) -> Any | None:
+        """
+        Coerces a raw value to match the type and semantics of a sample value.
+
+        Attempts to convert `raw` into the same type as `sample`. Handles:
+        - datetimes: parses ISO-like strings, preserves or aligns timezone info with `sample`,
+        - dates: parses ISO date strings,
+        - booleans: recognizes common textual and numeric boolean representations,
+        - other types: attempts to call the sample's type on `raw`.
+
+        Parameters:
+            sample: A value whose type and semantics should be used as the target.
+            raw: The input value to coerce.
+
+        Returns:
+            The coerced value of the same type as `sample`, or `None` if `raw` cannot be sensibly converted.
+        """
         if sample is None:
             return None
 
@@ -336,14 +362,50 @@ def generic_cache_invalidation(
                     return None
             return None
 
+        # Booleans: avoid bool("False") == True
+        if isinstance(sample, bool):
+            if isinstance(raw, bool):
+                return raw
+            if isinstance(raw, (int,)):
+                return bool(raw)
+            if isinstance(raw, str):
+                s = raw.strip().lower()
+                if s in {"true", "1", "yes", "y", "t"}:
+                    return True
+                if s in {"false", "0", "no", "n", "f"}:
+                    return False
+            return None
         try:
-            return type(sample)(raw) # type: ignore
-        except Exception:
+            return type(sample)(raw)  # type: ignore
+        except (TypeError, ValueError):
             if isinstance(raw, type(sample)):
                 return raw
             return None
 
     def matches(op: str, value: Any, val_key: Any) -> bool:
+        """
+        Evaluate whether a given value satisfies a lookup operation described by `op` and `val_key`.
+
+        Supports operators:
+        - "eq": equality; attempts to interpret `val_key` as a literal and coerce it to `value`'s type before comparing.
+        - "in": membership; expects `val_key` to be a literal iterable and checks if any coerced element equals `value`.
+        - "gt", "gte", "lt", "lte": numeric/date comparisons; `val_key` is interpreted as a literal and coerced to `value`'s type.
+        - "contains", "startswith", "endswith": string containment/prefix/suffix checks; both sides are compared as strings.
+        - "regex": treats `val_key` as a regular expression pattern and tests it against the string form of `value`.
+
+        Behavior notes:
+        - If `value` is None the function returns `False`.
+        - Literal parsing of `val_key` is attempted via AST literal evaluation; if parsing or coercion fails, the function falls back to conservative comparisons or returns `False` where appropriate.
+        - Regex patterns that fail to compile are treated as non-matching.
+
+        Parameters:
+            op (str): The lookup operator name (one of the supported operators above).
+            value (Any): The runtime value to test.
+            val_key (Any): The stored comparison key (often a string representation) to interpret for the comparison.
+
+        Returns:
+            bool: `True` if the comparison defined by `op` and `val_key` matches `value`, `False` otherwise.
+        """
         if value is None:
             return False
 
@@ -403,7 +465,9 @@ def generic_cache_invalidation(
             # regex: treat the stored key as the regex pattern
             if op == "regex":
                 try:
-                    pattern_source = literal if isinstance(literal, str) else str(literal)
+                    pattern_source = (
+                        literal if isinstance(literal, str) else str(literal)
+                    )
                     pattern = re.compile(pattern_source)
                 except re.error:
                     return False
@@ -412,6 +476,15 @@ def generic_cache_invalidation(
         return False
 
     def current_value_for_path(path: list[str]) -> Any:
+        """
+        Fetches the current value from the captured `instance` by following a sequence of attribute names.
+
+        Parameters:
+            path (list[str]): Ordered attribute names to traverse on the instance (e.g., ["user", "profile", "email"]).
+
+        Returns:
+            The value found at the end of the attribute path, or `None` if any attribute along the path is missing.
+        """
         current: object = instance
         for attr in path:
             current = getattr(current, attr, UNDEFINED)
@@ -420,8 +493,29 @@ def generic_cache_invalidation(
         return current
 
     def evaluate_composite(
-        cache_key: str, lookup_key: str, action: str
+        cache_key: str,
+        lookup_key: str,
+        action: Literal["filter", "exclude"],
+        model_section: dict[str, dict[str, set[str]]],
     ) -> bool | None:
+        """
+        Determine whether a composite dependency (multiple lookup params grouped under a single identifier)
+        for a given cache key and lookup should cause cache invalidation.
+
+        Parameters:
+            cache_key (str): The cache key being evaluated.
+            lookup_key (str): The specific lookup (operator and attribute path joined by `"__"`) that prompted evaluation.
+            action (Literal["filter", "exclude"]): The dependency action context; "filter" treats a match as cause for invalidation,
+                "exclude" treats a change in match membership as cause for invalidation.
+            model_section (dict[str, dict[str, set[str]]]): The index section for the model containing lookup maps and an
+                optional "__cache_dependencies__" mapping from cache keys to sets of identifier strings (each identifier
+                encodes multiple lookup parameters).
+
+        Returns:
+            bool | None: `True` if the composite dependency indicates the cache entry should be invalidated,
+            `False` if it indicates no invalidation is required, or `None` if there are no composite identifiers
+            registered for `cache_key`.
+        """
         cache_dependencies = model_section.get("__cache_dependencies__", {})
         identifiers = cache_dependencies.get(cache_key) if cache_dependencies else None
         if not identifiers:
@@ -468,9 +562,9 @@ def generic_cache_invalidation(
                     return True
         return False
 
-    for action in ("filter", "exclude"):
-        model_section = idx.get(action, {}).get(manager_name, {})
-        if not model_section:
+    for action in ACTIONS:
+        model_section = idx[action].get(manager_name)
+        if not isinstance(model_section, dict):
             continue
         for lookup, lookup_map in model_section.items():
             if lookup.startswith("__"):
@@ -512,7 +606,9 @@ def generic_cache_invalidation(
                 if action == "filter":
                     # Filter: invalidate if new match or old match
                     for ck in list(cache_keys):
-                        composite_decision = evaluate_composite(ck, lookup, action)
+                        composite_decision = evaluate_composite(
+                            ck, lookup, action, model_section
+                        )
                         should_invalidate = (
                             composite_decision
                             if composite_decision is not None
@@ -528,7 +624,9 @@ def generic_cache_invalidation(
                 else:  # action == 'exclude'
                     # Excludes: invalidate only if matches changed
                     for ck in list(cache_keys):
-                        composite_decision = evaluate_composite(ck, lookup, action)
+                        composite_decision = evaluate_composite(
+                            ck, lookup, action, model_section
+                        )
                         should_invalidate = (
                             composite_decision
                             if composite_decision is not None

general_manager/cache/signals.py

@@ -27,14 +27,16 @@ def dataChange(func: Callable[P, R]) -> Callable[P, R]:
     @wraps(func)
     def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         """
-        Execute the wrapped function while emitting data change signals.
+        Emit pre_data_change and post_data_change signals around the wrapped function call.
+
+        Emits a pre_data_change signal before invoking the wrapped function and a post_data_change signal afterwards. Signals are sent with `sender`, `instance`, and `action`; the post-change signal also includes `old_relevant_values`. After signaling, the wrapper removes the `_old_values` attribute from the pre-change instance if it exists.
 
         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.
+            R: The result returned by the wrapped function.
         """
         action = func.__name__
         if func.__name__ == "create":
@@ -66,6 +68,11 @@ def dataChange(func: Callable[P, R]) -> Callable[P, R]:
             old_relevant_values=old_relevant_values,
             **kwargs,
         )
+        if instance_before is not None:
+            try:
+                delattr(instance_before, "_old_values")
+            except AttributeError:
+                pass
         return result
 
     return wrapper

general_manager/factory/__init__.py

@@ -12,10 +12,19 @@ __all__ = list(FACTORY_EXPORTS)
 _MODULE_MAP = FACTORY_EXPORTS
 
 if TYPE_CHECKING:
-    from general_manager._types.factory import *  # noqa: F401,F403
+    from general_manager._types.factory import *  # noqa: F403
 
 
 def __getattr__(name: str) -> Any:
+    """
+    Dynamically resolve and return a named export from this module.
+
+    Parameters:
+        name (str): The attribute name to resolve.
+
+    Returns:
+        Any: The resolved attribute object corresponding to `name`.
+    """
     return resolve_export(
         name,
         module_all=__all__,

general_manager/factory/autoFactory.py

@@ -15,6 +15,40 @@ if TYPE_CHECKING:
 modelsModel = TypeVar("modelsModel", bound=models.Model)
 
 
+class InvalidGeneratedObjectError(TypeError):
+    """Raised when factory generation produces non-model instances."""
+
+    def __init__(self) -> None:
+        """
+        Initialize the exception indicating a generated object is not a Django model instance.
+
+        Sets a default error message explaining that the generated object is not a Django model instance.
+        """
+        super().__init__("Generated object is not a Django model instance.")
+
+
+class InvalidAutoFactoryModelError(TypeError):
+    """Raised when the factory metadata does not reference a Django model class."""
+
+    def __init__(self) -> None:
+        """
+        Raised when an AutoFactory target model is not a Django model class.
+
+        The exception carries a default message explaining that `_meta.model` must be a Django model class.
+        """
+        super().__init__("AutoFactory requires _meta.model to be a Django model class.")
+
+
+class UndefinedAdjustmentMethodError(ValueError):
+    """Raised when an adjustment method is required but not configured."""
+
+    def __init__(self) -> None:
+        """
+        Initialize the UndefinedAdjustmentMethodError with the default message indicating that a generate/adjustment function is not configured.
+        """
+        super().__init__("_adjustmentMethod is not defined.")
+
+
 class AutoFactory(DjangoModelFactory[modelsModel]):
     """Factory that auto-populates model fields based on interface metadata."""
 
@@ -28,18 +62,26 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, strategy: Literal["build", "create"], params: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Generate and populate model instances with automatically derived field values.
+        Generate and populate model instances using automatically derived field values.
 
         Parameters:
-            strategy (Literal["build", "create"]): Whether to persist the generated instances.
-            params (dict[str, Any]): Field values supplied by the caller.
+            strategy (Literal["build", "create"]): Either "build" (unsaved instance) or "create" (saved instance).
+            params (dict[str, Any]): Field values supplied by the caller; any missing non-auto fields will be populated automatically.
 
         Returns:
-            models.Model | list[models.Model]: Generated instance(s) matching the requested strategy.
+            models.Model | list[models.Model]: A generated model instance or a list of generated model instances.
+
+        Raises:
+            InvalidAutoFactoryModelError: If the factory target `_meta.model` is not a Django model class.
+            InvalidGeneratedObjectError: If an element of a generated list is not a Django model instance.
         """
         model = cls._meta.model
-        if not issubclass(model, models.Model):
-            raise ValueError("Model must be a type")
+        try:
+            is_model = isinstance(model, type) and issubclass(model, models.Model)
+        except TypeError:
+            is_model = False
+        if not is_model:
+            raise InvalidAutoFactoryModelError
         field_name_list, to_ignore_list = cls.interface.handleCustomFields(model)
 
         fields = [
@@ -71,7 +113,7 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         if isinstance(obj, list):
             for item in obj:
                 if not isinstance(item, models.Model):
-                    raise ValueError("Model must be a type")
+                    raise InvalidGeneratedObjectError()
                 cls._handleManyToManyFieldsAfterCreation(item, params)
         else:
             cls._handleManyToManyFieldsAfterCreation(obj, params)
@@ -191,21 +233,21 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, use_creation_method: bool, params: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Create or build instance(s) using the configured adjustment method.
+        Create or build model instance(s) using the configured adjustment method.
 
         Parameters:
-            use_creation_method (bool): Whether generated objects should be saved.
-            params (dict[str, Any]): Arguments forwarded to the adjustment callback.
+            use_creation_method (bool): If True, created records are validated and saved; if False, unsaved instances are returned.
+            params (dict[str, Any]): Keyword arguments forwarded to the adjustment method to produce record dict(s).
 
         Returns:
-            models.Model | list[models.Model]: Created or built instance(s).
+            models.Model | list[models.Model]: A single model instance or a list of instances — saved instances when `use_creation_method` is True, unsaved otherwise.
 
         Raises:
-            ValueError: If no adjustment method has been configured.
+            UndefinedAdjustmentMethodError: If no adjustment method has been configured on the factory.
         """
         model_cls = cls._meta.model
         if cls._adjustmentMethod is None:
-            raise ValueError("generate_func is not defined")
+            raise UndefinedAdjustmentMethodError()
         records = cls._adjustmentMethod(**params)
         if isinstance(records, dict):
             if use_creation_method: