GeneralManager 0.80.1__tar.gz → 0.80.2__tar.gz

{generalmanager-0.80.1/src/GeneralManager.egg-info → generalmanager-0.80.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.80.1
+Version: 0.80.2
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: MIT License

{generalmanager-0.80.1 → generalmanager-0.80.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.80.1"
+version = "0.80.2"
 description = "Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching."
 readme = "README.md"
 authors = [{ name = "Tim Kleindick", email = "tkleindick@yahoo.de" }]

{generalmanager-0.80.1 → generalmanager-0.80.2/src/GeneralManager.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.80.1
+Version: 0.80.2
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License: MIT License

{generalmanager-0.80.1 → generalmanager-0.80.2}/src/GeneralManager.egg-info/SOURCES.txt

@@ -67,6 +67,7 @@ src/general_manager/bucket/indexing.py
 src/general_manager/bucket/projection.py
 src/general_manager/bucket/request_bucket.py
 src/general_manager/cache/__init__.py
+src/general_manager/cache/_dependency_graph.py
 src/general_manager/cache/cache_decorator.py
 src/general_manager/cache/cache_tracker.py
 src/general_manager/cache/data_change_context.py

generalmanager-0.80.2/src/general_manager/cache/_dependency_graph.py

@@ -0,0 +1,116 @@
+"""Private immutable dependency snapshots shared by cache computations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import cast
+
+from general_manager.cache.dependency_index import Dependency
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class _DependencyBlock:
+    """One immutable collection of directly observed dependency tuples.
+
+    Equality deliberately remains identity based.  A block can be referenced by
+    several snapshot leaves (notably prefetched dependency-cache hits), and a
+    materialization must visit that shared block only once.
+    """
+
+    dependencies: tuple[Dependency, ...] | frozenset[Dependency]
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class DependencySnapshot:
+    """An immutable node containing direct dependencies and child snapshots."""
+
+    block: _DependencyBlock | None
+    children: tuple["DependencySnapshot", ...]
+
+
+_EMPTY_SNAPSHOT = DependencySnapshot(block=None, children=())
+
+
+def empty_dependency_snapshot() -> DependencySnapshot:
+    """Return the shared empty dependency root."""
+    return _EMPTY_SNAPSHOT
+
+
+def snapshot_from_dependencies(
+    dependencies: Iterable[Dependency],
+) -> DependencySnapshot:
+    """Freeze direct dependencies at a boundary into a standalone leaf."""
+    # Hits already own an immutable dependency container.  Retaining that
+    # container by identity is what lets independent leaf wrappers share its
+    # storage (and lets materialization/accounting charge it once).  Mutable
+    # inputs must still be copied at this boundary.
+    if type(dependencies) in (tuple, frozenset):
+        frozen_dependencies = cast(
+            tuple[Dependency, ...] | frozenset[Dependency], dependencies
+        )
+    else:
+        frozen_dependencies = tuple(dependencies)
+    if not frozen_dependencies:
+        return _EMPTY_SNAPSHOT
+    return DependencySnapshot(_DependencyBlock(frozen_dependencies), ())
+
+
+class DependencyCapture:
+    """Mutable builder used only while one cache calculation is executing."""
+
+    __slots__ = ("_child_ids", "_children", "_dependencies")
+
+    def __init__(self) -> None:
+        """Start an empty per-calculation builder."""
+        self._dependencies: set[Dependency] = set()
+        self._children: list[DependencySnapshot] = []
+        self._child_ids: set[int] = set()
+
+    def add(self, dependency: Dependency) -> None:
+        """Record one direct dependency in this calculation frame."""
+        self._dependencies.add(dependency)
+
+    def attach(self, snapshot: DependencySnapshot) -> None:
+        """Attach a child snapshot once, using node identity for deduplication."""
+        if snapshot is _EMPTY_SNAPSHOT:
+            return
+        snapshot_id = id(snapshot)
+        if snapshot_id not in self._child_ids:
+            self._child_ids.add(snapshot_id)
+            self._children.append(snapshot)
+
+    def freeze(self) -> DependencySnapshot:
+        """Build the immutable root, reusing simple child-only snapshots."""
+        if not self._dependencies:
+            if not self._children:
+                return _EMPTY_SNAPSHOT
+            if len(self._children) == 1:
+                return self._children[0]
+            return DependencySnapshot(None, tuple(self._children))
+        return DependencySnapshot(
+            _DependencyBlock(tuple(self._dependencies)),
+            tuple(self._children),
+        )
+
+
+def materialize_dependencies(snapshot: DependencySnapshot) -> set[Dependency]:
+    """Iteratively flatten a graph, visiting nodes and direct blocks by identity."""
+    dependencies: set[Dependency] = set()
+    pending = [snapshot]
+    seen_nodes: set[int] = set()
+    seen_dependency_containers: set[int] = set()
+    while pending:
+        node = pending.pop()
+        node_id = id(node)
+        if node_id in seen_nodes:
+            continue
+        seen_nodes.add(node_id)
+        block = node.block
+        if block is not None:
+            dependency_container_id = id(block.dependencies)
+            if dependency_container_id not in seen_dependency_containers:
+                seen_dependency_containers.add(dependency_container_id)
+                dependencies.update(block.dependencies)
+        pending.extend(node.children)
+    return dependencies

{generalmanager-0.80.1 → generalmanager-0.80.2}/src/general_manager/cache/cache_decorator.py

@@ -1,6 +1,6 @@
 """Helpers for caching GeneralManager computations with dependency tracking."""
 
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Iterable, Mapping
 from functools import partial, wraps
 from hashlib import sha256
 import inspect
@@ -8,7 +8,10 @@ from typing import Literal, ParamSpec, Protocol, TypeVar, cast, overload
 
 from django.core.cache import cache as django_cache
 
-from general_manager.cache.cache_tracker import DependencyTracker
+from general_manager.cache.cache_tracker import (
+    DependencyTracker,
+    _DependencyCaptureScope,
+)
 from general_manager.cache.dependency_cache import (
     DependencyCacheHit,
     dependency_cache_prefetch_bundle_key,
@@ -170,7 +173,26 @@ def _reject_awaitable_cache_result(result: object) -> None:
 
 def _replay_run_cache_entry_dependencies(entry: _RunCacheEntry) -> None:
     """Replay a decorated run-cache entry into every active dependency tracker."""
-    for class_name, operation, identifier in entry.dependencies:
+    DependencyTracker._attach_snapshot(entry.dependency_root)
+
+
+def _track_model_arguments(
+    args: tuple[object, ...],
+    kwargs: Mapping[str, object],
+    capture: _DependencyCaptureScope,
+) -> None:
+    """Track model argument dependencies as they are discovered.
+
+    Collector iteration can raise while serializing a later argument.  Recording
+    each earlier value immediately preserves the same partial-dependency
+    behavior as ordinary source reads.
+    """
+    for class_name, operation, identifier in ModelDependencyCollector._iter_args(
+        args, kwargs
+    ):
+        dependency = (class_name, operation, identifier)
+        if capture._record_argument_dependency(dependency):
+            continue
         DependencyTracker._track_validated(class_name, operation, identifier)
 
 
@@ -418,15 +440,16 @@ def cached(
                             _replay_run_cache_entry_dependencies(cached_run_value)
                             return cast(R, cached_run_value.value)
                         return cast(R, cached_run_value)
-                    with DependencyTracker() as dependencies:
+                    with DependencyTracker._capture() as capture:
                         result = decorated_func(*args, **kwargs)
-                        ModelDependencyCollector.add_args(dependencies, args, kwargs)
+                        _track_model_arguments(args, kwargs, capture)
                     _reject_awaitable_cache_result(result)
+                    assert capture.snapshot is not None
                     active_context.set(
                         key,
                         _RunCacheEntry(
                             value=result,
-                            dependencies=frozenset(dependencies),
+                            dependency_root=capture.snapshot,
                         ),
                     )
                     return result
@@ -437,15 +460,16 @@ def cached(
                             _replay_run_cache_entry_dependencies(cached_run_value)
                             return cast(R, cached_run_value.value)
                         return cast(R, cached_run_value)
-                    with DependencyTracker() as dependencies:
+                    with DependencyTracker._capture() as capture:
                         result = decorated_func(*args, **kwargs)
-                        ModelDependencyCollector.add_args(dependencies, args, kwargs)
+                        _track_model_arguments(args, kwargs, capture)
                     _reject_awaitable_cache_result(result)
+                    assert capture.snapshot is not None
                     context.set(
                         key,
                         _RunCacheEntry(
                             value=result,
-                            dependencies=frozenset(dependencies),
+                            dependency_root=capture.snapshot,
                         ),
                     )
                     return result
@@ -566,10 +590,12 @@ def cached(
                     return return_cached_hit(cached_hit, "cache hit")
 
                 started_generation = get_dependency_generation()
-                with DependencyTracker() as dependencies:
+                with DependencyTracker._capture() as capture:
                     result = decorated_func(*args, **kwargs)
-                    ModelDependencyCollector.add_args(dependencies, args, kwargs)
+                    _track_model_arguments(args, kwargs, capture)
                 _reject_awaitable_cache_result(result)
+                assert capture.snapshot is not None
+                dependencies = DependencyTracker._materialize_snapshot(capture.snapshot)
 
                 def record_many(
                     entries: Iterable[tuple[str, Iterable[Dependency]]],

{generalmanager-0.80.1 → generalmanager-0.80.2}/src/general_manager/cache/cache_tracker.py

@@ -1,6 +1,8 @@
 """Context manager utilities for tracking cache dependencies per thread."""
 
-from collections.abc import Collection, Iterable
+from __future__ import annotations
+
+from collections.abc import Iterable
 import threading
 from types import TracebackType
 
@@ -9,6 +11,12 @@ from general_manager.cache.dependency_index import (
     filter_type,
     general_manager_name,
 )
+from general_manager.cache._dependency_graph import (
+    DependencyCapture,
+    DependencySnapshot,
+    materialize_dependencies,
+    snapshot_from_dependencies,
+)
 
 _SUPPORTED_OPERATIONS: frozenset[filter_type] = frozenset(
     {"filter", "exclude", "identification", "request_query", "all"}
@@ -35,13 +43,18 @@ class _TrackedDependencySet(set[Dependency]):
     """Dependency set returned by DependencyTracker for framework-captured deps."""
 
 
+class _CapturedDependencySet(_TrackedDependencySet):
+    """Private materialization of a trusted immutable dependency graph."""
+
+
 class _DependencyStorage(threading.local):
     """Thread-local dependency tracking stack."""
 
     def __init__(self) -> None:
         """Initialize an inactive dependency stack for one thread."""
         self.dependencies: list[_TrackedDependencySet] = []
-        self.depth = -1
+        self.captures: list[DependencyCapture] = []
+        self.generation = 0
         self.stack_version = 0
         self.last_dependency: Dependency | None = None
         self.last_dependency_stack_version = -1
@@ -50,8 +63,12 @@ class _DependencyStorage(threading.local):
 
     def reset(self) -> None:
         """Clear all active dependency scopes for the current thread."""
+        # Capture scopes retain direct references to their old parent builders.
+        # Detaching this stack therefore prevents later ordinary reads from
+        # reaching it while still allowing each scope to finalize its own result.
         self.dependencies.clear()
-        self.depth = -1
+        self.captures.clear()
+        self.generation += 1
         self.stack_version += 1
         self.last_dependency = None
         self.last_dependency_stack_version = -1
@@ -62,6 +79,79 @@ class _DependencyStorage(threading.local):
 _dependency_storage = _DependencyStorage()
 
 
+def _clear_duplicate_state(storage: _DependencyStorage) -> None:
+    """Release duplicate-suppression references after the final scope exits."""
+    storage.last_dependency = None
+    storage.last_dependency_stack_version = -1
+    storage.seen_dependencies.clear()
+    storage.seen_dependencies_stack_version = -1
+
+
+class _DependencyCaptureScope:
+    """Private compact dependency capture for one decorated computation."""
+
+    def __init__(self) -> None:
+        """Create an unentered capture scope."""
+        self._capture: DependencyCapture | None = None
+        self._parent_capture: DependencyCapture | None = None
+        self._generation = -1
+        self.snapshot: DependencySnapshot | None = None
+
+    def __enter__(self) -> "_DependencyCaptureScope":
+        storage = _dependency_storage
+        self._generation = storage.generation
+        self.snapshot = None
+        capture = DependencyCapture()
+        self._capture = capture
+        self._parent_capture = storage.captures[-1] if storage.captures else None
+        storage.captures.append(capture)
+        storage.stack_version += 1
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        del exc_type, exc_val, exc_tb
+        storage = _dependency_storage
+        capture = self._capture
+        if capture is None:
+            return
+        parent_capture = self._parent_capture
+        self._capture = None
+        self._parent_capture = None
+        snapshot = capture.freeze()
+        self.snapshot = snapshot
+        if (
+            storage.generation == self._generation
+            and storage.captures
+            and storage.captures[-1] is capture
+        ):
+            storage.captures.pop()
+            storage.stack_version += 1
+            storage.last_dependency = None
+            storage.last_dependency_stack_version = -1
+            if not storage.dependencies and not storage.captures:
+                _clear_duplicate_state(storage)
+        if parent_capture is not None:
+            parent_capture.attach(snapshot)
+
+    def _record_argument_dependency(self, dependency: Dependency) -> bool:
+        """Record a decorator-derived argument after this scope was detached."""
+        capture = self._capture
+        storage = _dependency_storage
+        if capture is not None and (
+            storage.generation != self._generation
+            or not storage.captures
+            or storage.captures[-1] is not capture
+        ):
+            capture.add(dependency)
+            return True
+        return False
+
+
 class DependencyTracker:
     """Capture dependencies touched inside a read or cache-computation scope.
 
@@ -69,6 +159,10 @@ class DependencyTracker:
     tracker state if their execution is interleaved inside one active context.
     """
 
+    def __init__(self) -> None:
+        """Create per-thread scope storage before the tracker can be shared."""
+        self._scope_storage = threading.local()
+
     def __enter__(
         self,
     ) -> set[Dependency]:
@@ -83,10 +177,17 @@ class DependencyTracker:
             remains a usable snapshot after the context exits; clearing
             thread-local storage does not mutate sets that were already returned.
         """
-        _dependency_storage.depth += 1
-        _dependency_storage.dependencies.append(_TrackedDependencySet())
-        _dependency_storage.stack_version += 1
-        return _dependency_storage.dependencies[_dependency_storage.depth]
+        storage = _dependency_storage
+        scope_storage = self._scope_storage
+        if not hasattr(scope_storage, "scopes"):
+            scope_storage.scopes = []
+        scopes: list[tuple[int, _TrackedDependencySet]] = scope_storage.scopes
+        generation = storage.generation
+        collector = _TrackedDependencySet()
+        scopes.append((generation, collector))
+        storage.dependencies.append(collector)
+        storage.stack_version += 1
+        return collector
 
     def __exit__(
         self,
@@ -107,16 +208,24 @@ class DependencyTracker:
         `reset_thread_local_storage()` or otherwise without an active context is
         a no-op.
         """
-        if _dependency_storage.depth < 0:
+        storage = _dependency_storage
+        scope_storage = getattr(self, "_scope_storage", None)
+        scopes = getattr(scope_storage, "scopes", None)
+        if not scopes:
             return
-        if _dependency_storage.depth == 0:
-            self.reset_thread_local_storage()
+        generation, collector = scopes.pop()
+        if (
+            generation != storage.generation
+            or not storage.dependencies
+            or storage.dependencies[-1] is not collector
+        ):
             return
-        _dependency_storage.dependencies.pop()
-        _dependency_storage.depth -= 1
-        _dependency_storage.stack_version += 1
-        _dependency_storage.last_dependency = None
-        _dependency_storage.last_dependency_stack_version = -1
+        storage.dependencies.pop()
+        storage.stack_version += 1
+        storage.last_dependency = None
+        storage.last_dependency_stack_version = -1
+        if not storage.dependencies and not storage.captures:
+            _clear_duplicate_state(storage)
 
     @staticmethod
     def track(
@@ -164,7 +273,7 @@ class DependencyTracker:
     ) -> None:
         """Record an already-validated dependency tuple in active collectors."""
         storage = _dependency_storage
-        if storage.depth < 0:
+        if not storage.dependencies and not storage.captures:
             return
         if storage.last_dependency_stack_version == storage.stack_version:
             last_dependency = storage.last_dependency
@@ -181,11 +290,10 @@ class DependencyTracker:
             storage.seen_dependencies_stack_version = storage.stack_version
         elif dependency in storage.seen_dependencies:
             return
-        if storage.depth == 0:
-            storage.dependencies[0].add(dependency)
-        else:
-            for dep_set in storage.dependencies:
-                dep_set.add(dependency)
+        for dep_set in storage.dependencies:
+            dep_set.add(dependency)
+        if storage.captures:
+            storage.captures[-1].add(dependency)
         storage.last_dependency = dependency
         storage.last_dependency_stack_version = storage.stack_version
         storage.seen_dependencies.add(dependency)
@@ -193,15 +301,42 @@ class DependencyTracker:
     @staticmethod
     def _track_many_validated(dependencies: Iterable[Dependency]) -> None:
         """Record already-validated dependency tuples in active collectors."""
-        if _dependency_storage.depth < 0:
+        storage = _dependency_storage
+        if not storage.dependencies and not storage.captures:
+            return
+        if type(dependencies) in (tuple, frozenset):
+            if storage.dependencies:
+                for dep_set in storage.dependencies:
+                    dep_set.update(dependencies)
+            if storage.captures:
+                storage.captures[-1].attach(snapshot_from_dependencies(dependencies))
             return
-        reusable_dependencies: Collection[Dependency]
-        if isinstance(dependencies, Collection):
-            reusable_dependencies = dependencies
-        else:
-            reusable_dependencies = tuple(dependencies)
-        for dep_set in _dependency_storage.dependencies:
-            dep_set.update(reusable_dependencies)
+        frozen_dependencies = tuple(dependencies)
+        for dep_set in storage.dependencies:
+            dep_set.update(frozen_dependencies)
+        if storage.captures:
+            storage.captures[-1].attach(snapshot_from_dependencies(frozen_dependencies))
+
+    @staticmethod
+    def _capture() -> _DependencyCaptureScope:
+        """Create a private graph capture scope for cache implementations."""
+        return _DependencyCaptureScope()
+
+    @staticmethod
+    def _attach_snapshot(snapshot: DependencySnapshot) -> None:
+        """Attach cached graph metadata without flattening private parents."""
+        storage = _dependency_storage
+        if storage.captures:
+            storage.captures[-1].attach(snapshot)
+        if storage.dependencies:
+            dependencies = materialize_dependencies(snapshot)
+            for dep_set in storage.dependencies:
+                dep_set.update(dependencies)
+
+    @staticmethod
+    def _materialize_snapshot(snapshot: DependencySnapshot) -> set[Dependency]:
+        """Expose one trusted mutable publication set for a snapshot boundary."""
+        return _CapturedDependencySet(materialize_dependencies(snapshot))
 
     @staticmethod
     def _dependencies_are_tracker_captured(dependencies: object) -> bool:
@@ -211,7 +346,7 @@ class DependencyTracker:
     @staticmethod
     def is_active() -> bool:
         """Return whether dependency tracking is active for this execution context."""
-        return _dependency_storage.depth >= 0
+        return bool(_dependency_storage.dependencies or _dependency_storage.captures)
 
     @staticmethod
     def reset_thread_local_storage() -> None:

{generalmanager-0.80.1 → generalmanager-0.80.2}/src/general_manager/cache/dependency_cache.py

@@ -3,11 +3,16 @@
 from __future__ import annotations
 
 from collections.abc import Iterable, Mapping
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from hashlib import sha256
 from typing import Protocol, TypeGuard, cast
 
 from general_manager.cache.cache_tracker import DependencyTracker
+from general_manager.cache._dependency_graph import (
+    DependencySnapshot,
+    empty_dependency_snapshot,
+    snapshot_from_dependencies,
+)
 from general_manager.cache.dependency_index import Dependency
 
 DEPENDENCY_CACHE_ENTRY_VERSION = 2
@@ -131,11 +136,41 @@ class DependencyCacheHit:
 
     value: object
     dependencies: frozenset[Dependency]
+    _dependency_root: DependencySnapshot | None = field(
+        init=False,
+        repr=False,
+        compare=False,
+    )
+
+    def __post_init__(self) -> None:
+        """Freeze caller-supplied metadata before retaining a graph leaf."""
+        dependencies = frozenset(self.dependencies)
+        object.__setattr__(self, "dependencies", dependencies)
+        object.__setattr__(
+            self,
+            "_dependency_root",
+            snapshot_from_dependencies(dependencies) if dependencies else None,
+        )
+
+    @property
+    def dependency_root(self) -> DependencySnapshot:
+        """Return this hit's immutable dependency leaf."""
+        return self._dependency_root or empty_dependency_snapshot()
 
 
 class _TrustedDependencyCacheHit(DependencyCacheHit):
     """Cache hit whose dependencies were captured by DependencyTracker."""
 
+    __slots__ = ()
+
+
+def _trusted_dependency_cache_hit(
+    value: object,
+    dependencies: frozenset[Dependency],
+) -> DependencyCacheHit:
+    """Build an in-process hit whose frozen graph may be attached directly."""
+    return _TrustedDependencyCacheHit(value=value, dependencies=dependencies)
+
 
 class DependencyCacheBackend(Protocol):
     """Minimal cache backend shape for dependency-cache reads and writes."""
@@ -482,7 +517,7 @@ def replay_dependency_cache_hit(hit: DependencyCacheHit) -> None:
             tuple uses an unsupported operation.
     """
     if isinstance(hit, _TrustedDependencyCacheHit):
-        DependencyTracker._track_many_validated(hit.dependencies)
+        DependencyTracker._attach_snapshot(hit.dependency_root)
         return
     for class_name, operation, identifier in hit.dependencies:
         DependencyTracker.track(class_name, operation, identifier)

{generalmanager-0.80.1 → generalmanager-0.80.2}/src/general_manager/cache/model_dependency_collector.py

@@ -158,13 +158,17 @@ class ModelDependencyCollector:
         Returns:
             None
         """
-        if args and isinstance(args[0], GeneralManager):
-            inner_self = args[0]
-            for attr_val in inner_self.__dict__.values():
-                for dependency_tuple in ModelDependencyCollector.collect(attr_val):
-                    dependencies.add(dependency_tuple)
+        for dependency in ModelDependencyCollector._iter_args(args, kwargs):
+            dependencies.add(dependency)
 
-        for dependency_tuple in ModelDependencyCollector.collect(args):
-            dependencies.add(dependency_tuple)
-        for dependency_tuple in ModelDependencyCollector.collect(kwargs):
-            dependencies.add(dependency_tuple)
+    @staticmethod
+    def _iter_args(
+        args: tuple[object, ...],
+        kwargs: Mapping[str, object],
+    ) -> Iterator[Dependency]:
+        """Yield argument dependencies using the public ``add_args`` order."""
+        if args and isinstance(args[0], GeneralManager):
+            for attr_val in args[0].__dict__.values():
+                yield from ModelDependencyCollector.collect(attr_val)
+        yield from ModelDependencyCollector.collect(args)
+        yield from ModelDependencyCollector.collect(kwargs)