GeneralManager 0.3.0__tar.gz → 0.3.2__tar.gz

{generalmanager-0.3.0 → generalmanager-0.3.2}/GeneralManager.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.3.0
+Version: 0.3.2
 Summary: Kurzbeschreibung deines Pakets
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: Non-Commercial MIT License

{generalmanager-0.3.0 → generalmanager-0.3.2}/GeneralManager.egg-info/SOURCES.txt

@@ -17,11 +17,11 @@ src/general_manager/auxiliary/filterParser.py
 src/general_manager/auxiliary/jsonEncoder.py
 src/general_manager/auxiliary/makeCacheKey.py
 src/general_manager/auxiliary/noneToZero.py
+src/general_manager/auxiliary/pathMapping.py
 src/general_manager/cache/cacheDecorator.py
 src/general_manager/cache/cacheTracker.py
 src/general_manager/cache/dependencyIndex.py
 src/general_manager/cache/modelDependencyCollector.py
-src/general_manager/cache/pathMapping.py
 src/general_manager/cache/signals.py
 src/general_manager/factory/__init__.py
 src/general_manager/factory/factories.py
@@ -49,14 +49,20 @@ src/general_manager/rule/handler.py
 src/general_manager/rule/rule.py
 tests/test_argsToKwargs.py
 tests/test_basePermission.py
+tests/test_cacheDecorator.py
+tests/test_cacheTracker.py
+tests/test_dependencyIndex.py
 tests/test_filterParser.py
 tests/test_graph_ql.py
 tests/test_input.py
 tests/test_jsonEncoder.py
+tests/test_makeCacheKey.py
 tests/test_managerBasedPermission.py
 tests/test_measurement.py
 tests/test_measurement_field.py
+tests/test_modelDependencyCollector.py
 tests/test_noneToZero.py
 tests/test_rule_handler.py
 tests/test_rules.py
-tests/test_settings.py
+tests/test_settings.py
+tests/test_signals.py

{generalmanager-0.3.0 → generalmanager-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.3.0
+Version: 0.3.2
 Summary: Kurzbeschreibung deines Pakets
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: Non-Commercial MIT License

{generalmanager-0.3.0 → generalmanager-0.3.2}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.3.0"
+version = "0.3.2"
 description = "Kurzbeschreibung deines Pakets"
 readme = "README.md"
 authors = [

{generalmanager-0.3.0 → generalmanager-0.3.2}/src/general_manager/auxiliary/makeCacheKey.py

@@ -6,22 +6,25 @@ from hashlib import sha256
 
 def make_cache_key(func, args, kwargs):
     """
-    Generate a deterministic cache key for a function call.
-
+    Generates a unique, deterministic cache key for a specific function call.
+    
+    The key is derived from the function's module, qualified name, and bound arguments,
+    serialized to JSON and hashed with SHA-256 to ensure uniqueness for each call signature.
+    
     Args:
-        func: The function being called
-        args: Positional arguments to the function
-        kwargs: Keyword arguments to the function
-
+        func: The target function to be identified.
+        args: Positional arguments for the function call.
+        kwargs: Keyword arguments for the function call.
+    
     Returns:
-        str: A hexadecimal SHA-256 hash that uniquely identifies this function call
+        A hexadecimal SHA-256 hash string uniquely representing the function call.
     """
     sig = inspect.signature(func)
     bound = sig.bind_partial(*args, **kwargs)
     bound.apply_defaults()
     payload = {
         "module": func.__module__,
-        "name": func.__name__,
+        "qualname": func.__qualname__,
         "args": bound.arguments,
     }
     raw = json.dumps(

{generalmanager-0.3.0/src/general_manager/cache → generalmanager-0.3.2/src/general_manager/auxiliary}/pathMapping.py

@@ -3,9 +3,8 @@ from typing import TYPE_CHECKING, cast, get_args
 from general_manager.manager.meta import GeneralManagerMeta
 from general_manager.api.property import GraphQLProperty
 
-if TYPE_CHECKING:
-    from general_manager.interface.baseInterface import Bucket
-    from general_manager.manager.generalManager import GeneralManager
+from general_manager.interface.baseInterface import Bucket
+from general_manager.manager.generalManager import GeneralManager
 
 
 type PathStart = str
@@ -25,6 +24,11 @@ class PathMap:
 
     @classmethod
     def createPathMapping(cls):
+        """
+        Builds the mapping of paths between all pairs of distinct managed classes.
+        
+        Iterates over all registered managed classes and creates a PathTracer for each unique start and destination class pair, storing them in the mapping dictionary.
+        """
         all_managed_classes = GeneralManagerMeta.all_classes
         for start_class in all_managed_classes:
             for destination_class in all_managed_classes:
@@ -34,8 +38,12 @@ class PathMap:
                     ] = PathTracer(start_class, destination_class)
 
     def __init__(self, path_start: PathStart | GeneralManager | type[GeneralManager]):
-        from general_manager.manager.generalManager import GeneralManager
 
+        """
+        Initializes a PathMap with a specified starting point.
+        
+        The starting point can be a class name (string), a GeneralManager instance, or a GeneralManager subclass. Sets internal attributes for the start instance, class, and class name based on the input.
+        """
         if isinstance(path_start, GeneralManager):
             self.start_instance = path_start
             self.start_class = path_start.__class__
@@ -99,8 +107,17 @@ class PathTracer:
     def createPath(
         self, current_manager: type[GeneralManager], path: list[str]
     ) -> list[str] | None:
-        from general_manager.manager.generalManager import GeneralManager
 
+        """
+        Recursively constructs a path of attribute names from the current manager class to the destination class.
+        
+        Args:
+            current_manager: The current GeneralManager subclass being inspected.
+            path: The list of attribute names traversed so far.
+        
+        Returns:
+            A list of attribute names representing the path to the destination class, or None if no path exists.
+        """
         current_connections = {
             attr_name: attr_value["type"]
             for attr_name, attr_value in current_manager.Interface.getAttributeTypes().items()
@@ -131,8 +148,16 @@ class PathTracer:
     def traversePath(
         self, start_instance: GeneralManager | Bucket
     ) -> GeneralManager | Bucket | None:
-        from general_manager.interface.baseInterface import Bucket
 
+        """
+        Traverses the stored path from a starting instance to reach the destination instance or bucket.
+        
+        Args:
+            start_instance: The initial GeneralManager or Bucket instance from which to begin traversal.
+        
+        Returns:
+            The resulting GeneralManager or Bucket instance at the end of the path, or None if the path is empty.
+        """
         current_instance = start_instance
         if not self.path:
             return None

generalmanager-0.3.2/src/general_manager/cache/cacheDecorator.py

@@ -0,0 +1,81 @@
+from typing import Any, Callable, Optional, Protocol, Set
+from functools import wraps
+from django.core.cache import cache as django_cache
+from general_manager.cache.cacheTracker import DependencyTracker
+from general_manager.cache.dependencyIndex import record_dependencies, Dependency
+from general_manager.cache.modelDependencyCollector import ModelDependencyCollector
+from general_manager.auxiliary.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.
+
+        Args:
+            key: The cache key to look up.
+            default: Value to return if the key is not present in the cache.
+
+        Returns:
+            The cached value if found; otherwise, the provided 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.
+
+        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.
+        """
+        ...
+
+
+RecordFn = Callable[[str, Set[Dependency]], None]
+
+_SENTINEL = object()
+
+
+def cached(
+    timeout: Optional[int] = None,
+    cache_backend: CacheBackend = django_cache,
+    record_fn: RecordFn = record_dependencies,
+) -> Callable:
+    """
+    Decorator that caches function results and tracks their dependencies.
+
+    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.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            key = make_cache_key(func, args, kwargs)
+            deps_key = f"{key}:deps"
+
+            cached_result = cache_backend.get(key, _SENTINEL)
+            if cached_result is not _SENTINEL:
+                # saved dependencies are added to the current tracker
+                cached_deps = cache_backend.get(deps_key)
+                if cached_deps:
+                    for class_name, operation, identifier in cached_deps:
+                        DependencyTracker.track(class_name, operation, identifier)
+                return cached_result
+
+            with DependencyTracker() as dependencies:
+                result = func(*args, **kwargs)
+                ModelDependencyCollector.addArgs(dependencies, args, kwargs)
+
+                cache_backend.set(key, result, timeout)
+                cache_backend.set(deps_key, dependencies, timeout)
+
+                if dependencies and timeout is None:
+                    record_fn(key, dependencies)
+
+            return result
+
+        return wrapper
+
+    return decorator

generalmanager-0.3.2/src/general_manager/cache/cacheTracker.py

@@ -0,0 +1,74 @@
+import threading
+from general_manager.cache.dependencyIndex import (
+    general_manager_name,
+    Dependency,
+    filter_type,
+)
+
+# Thread-lokale Variable zur Speicherung der Abhängigkeiten
+_dependency_storage = threading.local()
+
+
+class DependencyTracker:
+    def __enter__(
+        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.
+
+        Returns:
+            The set used to collect dependencies for the current context level.
+        """
+        if not hasattr(_dependency_storage, "dependencies"):
+            _dependency_storage._depth = 0
+            _dependency_storage.dependencies = list()
+        else:
+            _dependency_storage._depth += 1
+        _dependency_storage.dependencies.append(set())
+        return _dependency_storage.dependencies[_dependency_storage._depth]
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Exits the dependency tracking context, managing cleanup for nested scopes.
+
+        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.
+        """
+        if hasattr(_dependency_storage, "dependencies"):
+            if _dependency_storage._depth == 0:
+                self.reset_thread_local_storage()
+
+            else:
+                # Ansonsten reduzieren wir nur die Tiefe
+                _dependency_storage._depth -= 1
+                _dependency_storage.dependencies.pop()
+
+    @staticmethod
+    def track(
+        class_name: general_manager_name,
+        operation: filter_type,
+        identifier: str,
+    ) -> None:
+        """
+        Records a dependency in all active dependency tracking contexts.
+
+        Adds the specified dependency tuple to each set in the current stack of dependency tracking scopes, ensuring it is tracked at all nested levels.
+        """
+        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.
+
+        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.
+        """
+        if hasattr(_dependency_storage, "dependencies"):
+            del _dependency_storage.dependencies
+            del _dependency_storage._depth

{generalmanager-0.3.0 → generalmanager-0.3.2}/src/general_manager/cache/dependencyIndex.py

@@ -33,18 +33,19 @@ type Dependency = Tuple[general_manager_name, filter_type, str]
 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
 
 
 # -----------------------------------------------------------------------------
 # LOCKING HELPERS
 # -----------------------------------------------------------------------------
 def acquire_lock(timeout: int = LOCK_TIMEOUT) -> bool:
-    """Atomar: legt den LOCK_KEY an, wenn noch frei."""
+    """Atomar: create Lock key if it doesn't exist."""
     return cache.add(LOCK_KEY, "1", timeout)
 
 
 def release_lock() -> None:
-    """Gibt den Lock frei."""
+    """Release Lock key."""
     cache.delete(LOCK_KEY)
 
 
@@ -52,7 +53,7 @@ def release_lock() -> None:
 # INDEX ACCESS
 # -----------------------------------------------------------------------------
 def get_full_index() -> dependency_index:
-    """Lädt oder initialisiert den kompletten Index."""
+    """Load or initialize the full index."""
     idx = cache.get(INDEX_KEY, None)
     if idx is None:
         idx: dependency_index = {"filter": {}, "exclude": {}}
@@ -61,7 +62,7 @@ def get_full_index() -> dependency_index:
 
 
 def set_full_index(idx: dependency_index) -> None:
-    """Schreibt den kompletten Index zurück in den Cache."""
+    """Write the complete index back to the cache."""
     cache.set(INDEX_KEY, idx, None)
 
 
@@ -78,15 +79,6 @@ def record_dependencies(
         ]
     ],
 ) -> None:
-    """
-    Speichert die Abhängigkeiten eines Cache Eintrags.
-    :param cache_key:   der Key unter dem das Ergebnis im cache steht
-    :param dependencies: Iterable von Tuplen (model_name, action, identifier)
-                         action ∈ {'filter','exclude'} oder sonstige → 'id'
-                         identifier = für filter/exclude: Dict String,
-                                      sonst: Primärschlüssel als String
-    """
-    # 1) Lock holen (Spin‑Lock mit Timeout)
     start = time.time()
     while not acquire_lock():
         if time.time() - start > LOCK_TIMEOUT:
@@ -105,7 +97,7 @@ def record_dependencies(
                     lookup_map.setdefault(val_key, set()).add(cache_key)
 
             else:
-                # Direkter ID‑Lookup als simpler filter auf 'id'
+                # director ID Lookup as simple filter on 'id'
                 section = idx["filter"].setdefault(model_name, {})
                 lookup_map = section.setdefault("identification", {})
                 val_key = identifier
@@ -120,15 +112,12 @@ def record_dependencies(
 # -----------------------------------------------------------------------------
 # INDEX CLEANUP
 # -----------------------------------------------------------------------------
-def remove_cache_key_from_index(cache_key: str) -> bool:
-    """
-    Entfernt einen cache_key aus allen Einträgen in filter/​exclude.
-    Nützlich, sobald Du den Cache gelöscht hast.
-    """
+def remove_cache_key_from_index(cache_key: str) -> None:
+    """Remove a cache key from the index."""
     start = time.time()
     while not acquire_lock():
         if time.time() - start > LOCK_TIMEOUT:
-            return False
+            raise TimeoutError("Could not aquire lock for remove_cache_key_from_index")
         time.sleep(0.05)
 
     try:
@@ -149,14 +138,12 @@ def remove_cache_key_from_index(cache_key: str) -> bool:
         set_full_index(idx)
     finally:
         release_lock()
-    return True
 
 
 # -----------------------------------------------------------------------------
 # CACHE INVALIDATION
 # -----------------------------------------------------------------------------
 def invalidate_cache_key(cache_key: str) -> None:
-    """Löscht den CacheEintrag – hier nutzt du deinen CacheBackend."""
     cache.delete(cache_key)
 
 
@@ -165,33 +152,28 @@ def capture_old_values(
     sender: Type[GeneralManager], instance: GeneralManager | None, **kwargs
 ) -> None:
     if instance is None:
-        # Wenn es kein Modell ist, gibt es nichts zu tun
         return
     manager_name = sender.__name__
     idx = get_full_index()
-    # Welche Lookups interessieren uns für diesen Model?
+    # get all lookups for this model
     lookups = set()
     for action in ("filter", "exclude"):
         lookups |= set(idx.get(action, {}).get(manager_name, {}))
     if lookups and instance.identification:
-        # Speichere alle relevanten Attribute für später
+        # save old values for later comparison
         vals = {}
         for lookup in lookups:
             attr_path = lookup.split("__")
             obj = instance
-            for attr in attr_path:
-                obj = getattr(obj, attr, None)
-                if obj is None:
+            for i, attr in enumerate(attr_path):
+                if getattr(obj, attr, UNDEFINED) is UNDEFINED:
+                    lookup = "__".join(attr_path[:i])
                     break
+                obj = getattr(obj, attr, None)
             vals[lookup] = obj
         setattr(instance, "_old_values", vals)
 
 
-# -----------------------------------------------------------------------------
-# GENERIC CACHE INVALIDATION: vergleicht alt vs. neu und invalidiert nur bei Übergang
-# -----------------------------------------------------------------------------
-
-
 @receiver(post_data_change)
 def generic_cache_invalidation(
     sender: type[GeneralManager],
@@ -236,18 +218,32 @@ def generic_cache_invalidation(
         # wildcard / regex
         if op in ("contains", "startswith", "endswith", "regex"):
             try:
-                pattern = re.compile(val_key)
-            except:
-                return False
-            text = value or ""
-            return bool(pattern.search(text))
+                literal = ast.literal_eval(val_key)
+            except Exception:
+                literal = val_key
+
+            # ensure we always work with strings to avoid TypeErrors
+            text = "" if value is None else str(value)
+            if op == "contains":
+                return literal in text
+            if op == "startswith":
+                return text.startswith(literal)
+            if op == "endswith":
+                return text.endswith(literal)
+            # regex: val_key selbst als Pattern benutzen
+            if op == "regex":
+                try:
+                    pattern = re.compile(val_key)
+                except re.error:
+                    return False
+                return bool(pattern.search(text))
 
         return False
 
     for action in ("filter", "exclude"):
         model_section = idx.get(action, {}).get(manager_name, {})
         for lookup, lookup_map in model_section.items():
-            # 1) Operator und Attributpfad ermitteln
+            # 1) get operator and attribute path
             parts = lookup.split("__")
             if parts[-1] in (
                 "gt",
@@ -266,8 +262,8 @@ def generic_cache_invalidation(
                 op = "eq"
                 attr_path = parts
 
-            # 2) Alten und neuen Wert holen
-            old_val = old_relevant_values.get(lookup)
+            # 2) get old & new value
+            old_val = old_relevant_values.get("__".join(attr_path))
 
             obj = instance
             for attr in attr_path:
@@ -276,14 +272,14 @@ def generic_cache_invalidation(
                     break
             new_val = obj
 
-            # 3) Für jedes val_key prüfen
+            # 3) check against all cache_keys
             for val_key, cache_keys in list(lookup_map.items()):
                 old_match = matches(op, old_val, val_key)
                 new_match = matches(op, new_val, val_key)
 
                 if action == "filter":
-                    # Direkte & alle Filter-Abhängigkeiten: immer invalidieren, wenn neu matcht
-                    if new_match:
+                    # Filter: invalidate if new match or old match
+                    if new_match or old_match:
                         print(
                             f"Invalidate cache key {cache_keys} for filter {lookup} with value {val_key}"
                         )
@@ -292,7 +288,7 @@ def generic_cache_invalidation(
                             remove_cache_key_from_index(ck)
 
                 else:  # action == 'exclude'
-                    # Excludes: nur invalidieren, wenn sich der Match-Status ändert
+                    # Excludes: invalidate only if matches changed
                     if old_match != new_match:
                         print(
                             f"Invalidate cache key {cache_keys} for exclude {lookup} with value {val_key}"

{generalmanager-0.3.0 → generalmanager-0.3.2}/src/general_manager/cache/modelDependencyCollector.py

@@ -9,15 +9,23 @@ from general_manager.cache.dependencyIndex import (
 
 class ModelDependencyCollector:
 
-    def __init__(self, dependencies: set[Dependency]):
-        """
-        Initialize the ModelDependencyCollector with a set of dependencies.
-        """
-        self.dependencies = dependencies
-
     @staticmethod
     def collect(obj) -> Generator[tuple[general_manager_name, filter_type, str]]:
-        """Recursively find Django model instances in the object."""
+        """
+        Recursively yields dependency information from objects related to Django models.
+        
+        Traverses the input object and its nested structures to identify instances of
+        GeneralManager and Bucket, yielding tuples that describe their dependencies.
+        Yields a tuple of (manager class name, dependency type, dependency value) for
+        each dependency found.
+        
+        Args:
+            obj: The object or collection to inspect for model dependencies.
+        
+        Yields:
+            Tuples containing the manager class name, dependency type ("identification",
+            "filter", or "exclude"), and the string representation of the dependency value.
+        """
         if isinstance(obj, GeneralManager):
             yield (
                 obj.__class__.__name__,