GeneralManager 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

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(

general_manager/{cache → 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

general_manager/cache/cacheDecorator.py

@@ -8,35 +8,71 @@ from general_manager.auxiliary.makeCacheKey import make_cache_key
 
 
 class CacheBackend(Protocol):
-    def get(self, key: str) -> Any: ...
-    def set(self, key: str, value: Any, timeout: Optional[int] = None) -> None: ...
+    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"
 
-            result = cache_backend.get(key)
-            if result is not None:
-                return result
+            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(key, result, timeout)
+                cache_backend.set(deps_key, dependencies, timeout)
 
-            if dependencies and timeout is None:
-                record_fn(key, dependencies)
+                if dependencies and timeout is None:
+                    record_fn(key, dependencies)
 
             return result
 

general_manager/cache/cacheTracker.py

@@ -13,12 +13,36 @@ class DependencyTracker:
     def __enter__(
         self,
     ) -> set[Dependency]:
-        _dependency_storage.dependencies = set()
-        return _dependency_storage.dependencies
+        """
+        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"):
-            del _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(
@@ -27,8 +51,24 @@ class DependencyTracker:
         identifier: str,
     ) -> None:
         """
-        Adds a dependency to the dependency storage.
+        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"):
-            dependencies: set[Dependency] = _dependency_storage.dependencies
-            dependencies.add((class_name, operation, identifier))
+            del _dependency_storage.dependencies
+            del _dependency_storage._depth

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__,

{generalmanager-0.3.0.dist-info → generalmanager-0.3.1.dist-info}/METADATA

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

{generalmanager-0.3.0.dist-info → generalmanager-0.3.1.dist-info}/RECORD

@@ -7,13 +7,13 @@ general_manager/auxiliary/__init__.py,sha256=4IwKJzsNxGduF-Ej0u1BNHVaMhkql8PjHbV
 general_manager/auxiliary/argsToKwargs.py,sha256=kmp1xonpQp4X_y8ZJG6c5uOW7zQwo0HtPqsHWVzXRSM,921
 general_manager/auxiliary/filterParser.py,sha256=wmR4YzsnYgjI2Co5eyvCFROldotAraHx_GiCDJo79IY,5410
 general_manager/auxiliary/jsonEncoder.py,sha256=TDsgFQvheITHZgdmn-m8tk1_QCzpT0XwEHo7bY3Qe-M,638
-general_manager/auxiliary/makeCacheKey.py,sha256=o2ZPe5ZjiZhHxYgSESBSMnOmQutkTxw5DLeJM7tOw84,881
+general_manager/auxiliary/makeCacheKey.py,sha256=lczutqxlofLSUnheKRi8nazhOyPa04TZOFNxNn5vDu4,1126
 general_manager/auxiliary/noneToZero.py,sha256=KfQtMQnrT6vsYST0K7lv6pVujkDcK3XL8czHYOhgqKQ,539
-general_manager/cache/cacheDecorator.py,sha256=7DbPMw-2Xm1-5eCMVWyjUl_jdVtTJUKNpLW2WNJEhI0,1471
-general_manager/cache/cacheTracker.py,sha256=RmUWwAXMS5LQT8-w7IiG67FTBSxF1V0w4IDH1WzgmuM,998
+general_manager/auxiliary/pathMapping.py,sha256=nrz5owQg2a69Yig1eCXorR9U0NSw7NmBAk5OkeoHTdA,6842
+general_manager/cache/cacheDecorator.py,sha256=DK2ANIJgPpMxazfMSiFrI9OuVE_7K9zlIZQRrgaC2Lw,3268
+general_manager/cache/cacheTracker.py,sha256=rRw3OhBDf86hTC2Xbt1ocRgZqwu8_kXk4lczamcADFg,2955
 general_manager/cache/dependencyIndex.py,sha256=iuOjthmH5ehHCkWiM9iLbgzGlo4Cf2wRKkm-QhIQ024,10813
-general_manager/cache/modelDependencyCollector.py,sha256=Lt8mNpnp-AJaPCYrTu_UB1m_Hj1prfEXaPrxRwk3Qqs,1983
-general_manager/cache/pathMapping.py,sha256=WtECIek9fI-2_nqIYI4Ux9Lan6g8P9TMO_AfthkznX8,5656
+general_manager/cache/modelDependencyCollector.py,sha256=wS2edbZsQ1aTfRlHj02lhuasZHCc2ucRGob-E7ejuoY,2433
 general_manager/cache/signals.py,sha256=ZHeXKFMN7tj9t0J-vSqf_05_NhGqEF2sZtbZO3vaRqI,1234
 general_manager/factory/__init__.py,sha256=DLSQbpSBpujPtDSZcruPc43OLWzKCCtf20gbalCDYRU,91
 general_manager/factory/factories.py,sha256=31NyVw2Ju5ZDPJ6sax6_seyZesCU5UrviNbk-2PaKnA,11559
@@ -39,8 +39,8 @@ general_manager/permission/permissionDataManager.py,sha256=Ji7fsnuaKTa6M8yzCGyzr
 general_manager/rule/__init__.py,sha256=4Har5cfPD1fmOsilTDod-ZUz3Com-tkl58jz7yY4fD0,23
 general_manager/rule/handler.py,sha256=z8SFHTIZ0LbLh3fV56Mud0V4_OvWkqJjlHvFqau7Qfk,7334
 general_manager/rule/rule.py,sha256=3FVCKGL7BTVoStdgOTdWQwuoVRIxAIAilV4VOzouDpc,10759
-generalmanager-0.3.0.dist-info/licenses/LICENSE,sha256=YGFm0ieb4KpkMRRt2qnWue6uFh0cUMtobwEBkHwajhc,1450
-generalmanager-0.3.0.dist-info/METADATA,sha256=sKfEf7wuzdUhszsnlCJ49iydcFKidlwV58863yosGlw,8188
-generalmanager-0.3.0.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
-generalmanager-0.3.0.dist-info/top_level.txt,sha256=sTDtExP9ga-YP3h3h42yivUY-A2Q23C2nw6LNKOho4I,16
-generalmanager-0.3.0.dist-info/RECORD,,
+generalmanager-0.3.1.dist-info/licenses/LICENSE,sha256=YGFm0ieb4KpkMRRt2qnWue6uFh0cUMtobwEBkHwajhc,1450
+generalmanager-0.3.1.dist-info/METADATA,sha256=uintWwJEHfXzzHYW1Gwi1BQwqycnwdQI_oQW-XUWLiM,8188
+generalmanager-0.3.1.dist-info/WHEEL,sha256=Nw36Djuh_5VDukK0H78QzOX-_FQEo6V37m3nkm96gtU,91
+generalmanager-0.3.1.dist-info/top_level.txt,sha256=sTDtExP9ga-YP3h3h42yivUY-A2Q23C2nw6LNKOho4I,16
+generalmanager-0.3.1.dist-info/RECORD,,