GeneralManager 0.46.0__tar.gz → 0.47.0__tar.gz

{generalmanager-0.46.0/src/GeneralManager.egg-info → generalmanager-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.46.0
+Version: 0.47.0
 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.46.0 → generalmanager-0.47.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.46.0"
+version = "0.47.0"
 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.46.0 → generalmanager-0.47.0/src/GeneralManager.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.46.0
+Version: 0.47.0
 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.46.0 → generalmanager-0.47.0}/src/GeneralManager.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ src/general_manager/api/__init__.py
 src/general_manager/api/graphql.py
 src/general_manager/api/graphql_errors.py
 src/general_manager/api/graphql_mutations.py
+src/general_manager/api/graphql_prefetch.py
 src/general_manager/api/graphql_resolvers.py
 src/general_manager/api/graphql_search.py
 src/general_manager/api/graphql_subscription_consumer.py
@@ -51,6 +52,7 @@ src/general_manager/bucket/request_bucket.py
 src/general_manager/cache/__init__.py
 src/general_manager/cache/cache_decorator.py
 src/general_manager/cache/cache_tracker.py
+src/general_manager/cache/dependency_cache.py
 src/general_manager/cache/dependency_index.py
 src/general_manager/cache/dependency_publish.py
 src/general_manager/cache/model_dependency_collector.py

generalmanager-0.47.0/src/general_manager/api/graphql_prefetch.py

@@ -0,0 +1,182 @@
+"""Internal GraphQL helpers for dependency-cache prefetch planning."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+import re
+from typing import Any
+
+from django.core.cache import cache as django_cache
+from graphql import GraphQLResolveInfo
+from graphql.language.ast import (
+    FieldNode,
+    FragmentSpreadNode,
+    InlineFragmentNode,
+    SelectionSetNode,
+)
+
+from general_manager.api.property import GraphQLProperty
+from general_manager.cache.dependency_cache import (
+    DependencyCacheBackend,
+    DependencyCacheHit,
+    read_many_dependency_cache_hits,
+)
+from general_manager.cache.run_context import current_calculation_run_context
+from general_manager.manager.general_manager import GeneralManager
+from general_manager.utils.make_cache_key import make_cache_key
+
+
+def normalize_graphql_name(name: str) -> str:
+    """Convert a GraphQL field name to the Python attribute name."""
+    if "_" in name:
+        return name
+    snake = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
+    snake = re.sub("([a-z0-9])([A-Z])", r"\1_\2", snake)
+    return snake.lower()
+
+
+def collect_selected_graphql_property_names(
+    info: GraphQLResolveInfo,
+    manager_class: type[Any],
+    *,
+    root_field: str,
+    normalize_name: Callable[[str], str] = normalize_graphql_name,
+) -> set[str]:
+    """Return GraphQLProperty names selected directly under root_field."""
+    interface_cls = getattr(manager_class, "Interface", None)
+    if interface_cls is None:
+        return set()
+    available_properties = set(interface_cls.get_graph_ql_properties().keys())
+    if not available_properties:
+        return set()
+
+    property_names: set[str] = set()
+
+    def collect_direct_fields(
+        selection_set: SelectionSetNode | None,
+        visited: frozenset[str],
+    ) -> None:
+        if selection_set is None:
+            return
+        for selection in selection_set.selections:
+            if isinstance(selection, FieldNode):
+                normalized = normalize_name(selection.name.value)
+                if normalized in available_properties:
+                    property_names.add(normalized)
+            elif isinstance(selection, InlineFragmentNode):
+                collect_direct_fields(selection.selection_set, visited)
+            elif isinstance(selection, FragmentSpreadNode):
+                fragment_name = selection.name.value
+                if fragment_name in visited:
+                    continue
+                fragment = info.fragments.get(fragment_name)
+                if fragment is not None:
+                    collect_direct_fields(
+                        fragment.selection_set,
+                        visited | frozenset((fragment_name,)),
+                    )
+
+    def inspect_for_root(
+        selection_set: SelectionSetNode | None,
+        visited: frozenset[str],
+    ) -> None:
+        if selection_set is None:
+            return
+        for selection in selection_set.selections:
+            if isinstance(selection, FieldNode):
+                if selection.name.value == root_field:
+                    collect_direct_fields(selection.selection_set, visited)
+                else:
+                    inspect_for_root(selection.selection_set, visited)
+            elif isinstance(selection, InlineFragmentNode):
+                inspect_for_root(selection.selection_set, visited)
+            elif isinstance(selection, FragmentSpreadNode):
+                fragment_name = selection.name.value
+                if fragment_name in visited:
+                    continue
+                fragment = info.fragments.get(fragment_name)
+                if fragment is not None:
+                    inspect_for_root(
+                        fragment.selection_set,
+                        visited | frozenset((fragment_name,)),
+                    )
+
+    for field_node in getattr(info, "field_nodes", ()):
+        inspect_for_root(field_node.selection_set, frozenset())
+    return property_names
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyCachePrefetchPlan:
+    """A dependency-cache key planned for one GraphQL list item field."""
+
+    cache_key: str
+    instance: GeneralManager
+    property_name: str
+
+
+def plan_dependency_cache_prefetches(
+    instances: Iterable[GeneralManager],
+    manager_class: type[Any],
+    property_names: Iterable[str],
+    *,
+    can_read_field: Callable[[GeneralManager, str], bool],
+) -> dict[str, DependencyCachePrefetchPlan]:
+    """Build dependency-cache key plans for selected readable properties."""
+    interface_cls = getattr(manager_class, "Interface", None)
+    if interface_cls is None:
+        return {}
+
+    available_properties = interface_cls.get_graph_ql_properties()
+    instance_list = list(instances)
+    selected = set(property_names)
+    plans: dict[str, DependencyCachePrefetchPlan] = {}
+
+    for property_name in selected:
+        prop = available_properties.get(property_name)
+        if not isinstance(prop, GraphQLProperty):
+            continue
+        if prop.cache != "dependency":
+            continue
+
+        cached_getter = prop._get_cached_fget()
+        for instance in instance_list:
+            if not can_read_field(instance, property_name):
+                continue
+            cache_key = make_cache_key(cached_getter, (instance,), {})
+            plans.setdefault(
+                cache_key,
+                DependencyCachePrefetchPlan(
+                    cache_key=cache_key,
+                    instance=instance,
+                    property_name=property_name,
+                ),
+            )
+    return plans
+
+
+DependencyCacheBulkReader = Callable[
+    [DependencyCacheBackend, Iterable[str]],
+    dict[str, DependencyCacheHit],
+]
+
+
+def prefetch_dependency_cache_hits(
+    plans: Mapping[str, DependencyCachePrefetchPlan],
+    *,
+    cache_backend: DependencyCacheBackend = django_cache,
+    reader: DependencyCacheBulkReader | None = None,
+) -> dict[str, DependencyCacheHit]:
+    """Bulk-read planned dependency-cache hits into the active run context."""
+    context = current_calculation_run_context()
+    if context is None or not plans:
+        return {}
+
+    if reader is None:
+        reader = read_many_dependency_cache_hits
+    cache_keys = tuple(plans.keys())
+    hits = reader(cache_backend, cache_keys)
+    if hits:
+        context.set_dependency_cache_hits(hits)
+    return hits

{generalmanager-0.46.0 → generalmanager-0.47.0}/src/general_manager/api/graphql_resolvers.py

@@ -21,6 +21,11 @@ from general_manager.bucket.base_bucket import Bucket
 from general_manager.manager.general_manager import GeneralManager
 from general_manager.measurement.measurement import Measurement
 from general_manager.api.graphql_errors import get_read_permission_filter
+from general_manager.api.graphql_prefetch import (
+    collect_selected_graphql_property_names,
+    plan_dependency_cache_prefetches,
+    prefetch_dependency_cache_hits,
+)
 from general_manager.permission.graphql_capabilities import (
     get_capability_context,
     get_graphql_capabilities,
@@ -543,6 +548,26 @@ def create_list_resolver(
         qs_paginated: Any = apply_pagination(qs_grouped, page, page_size)
         if not hasattr(qs_paginated, "groups"):
             qs_paginated = list(qs_paginated)
+        if isinstance(qs_paginated, list):
+            selected_property_names = collect_selected_graphql_property_names(
+                info,
+                manager_class,
+                root_field="items",
+            )
+            if selected_property_names:
+                prefetch_plans = plan_dependency_cache_prefetches(
+                    qs_paginated,
+                    manager_class,
+                    selected_property_names,
+                    can_read_field=lambda instance, property_name: (
+                        check_read_permission(
+                            instance,
+                            info,
+                            property_name,
+                        )
+                    ),
+                )
+                prefetch_dependency_cache_hits(prefetch_plans)
         if isinstance(qs_paginated, list) and selection_includes_path(
             info, ("items", "capabilities")
         ):

{generalmanager-0.46.0 → generalmanager-0.47.0}/src/general_manager/api/graphql_subscriptions.py

@@ -16,19 +16,15 @@ from typing import Any, Callable, Iterable, TYPE_CHECKING, cast
 
 from channels.layers import BaseChannelLayer, get_channel_layer  # type: ignore[import]
 
-from graphql.language.ast import (
-    FieldNode,
-    FragmentSpreadNode,
-    InlineFragmentNode,
-    SelectionSetNode,
-)
-
 from general_manager.cache.cache_tracker import DependencyTracker
 from general_manager.cache.dependency_index import (
     Dependency,
     parse_dependency_identifier,
     serialize_dependency_identifier,
 )
+from general_manager.api.graphql_prefetch import (
+    collect_selected_graphql_property_names,
+)
 from general_manager.logging import get_logger
 from general_manager.manager.general_manager import GeneralManager
 from general_manager.api.graphql_errors import MissingChannelLayerError
@@ -334,50 +330,12 @@ def subscription_property_names(
     Returns:
         Set of selected ``GraphQLProperty`` names; empty set if none found.
     """
-    interface_cls = getattr(manager_class, "Interface", None)
-    if interface_cls is None:
-        return set()
-    available_properties = set(interface_cls.get_graph_ql_properties().keys())
-    if not available_properties:
-        return set()
-
-    property_names: set[str] = set()
-
-    def collect_from_selection(selection_set: SelectionSetNode | None) -> None:
-        if selection_set is None:
-            return
-        for selection in selection_set.selections:
-            if isinstance(selection, FieldNode):
-                name = selection.name.value
-                normalized = normalize_graphql_name(name)
-                if normalized in available_properties:
-                    property_names.add(normalized)
-            elif isinstance(selection, FragmentSpreadNode):
-                fragment = info.fragments.get(selection.name.value)
-                if fragment is not None:
-                    collect_from_selection(fragment.selection_set)
-            elif isinstance(selection, InlineFragmentNode):
-                collect_from_selection(selection.selection_set)
-
-    def inspect_selection_set(selection_set: SelectionSetNode | None) -> None:
-        if selection_set is None:
-            return
-        for selection in selection_set.selections:
-            if isinstance(selection, FieldNode):
-                if selection.name.value == "item":
-                    collect_from_selection(selection.selection_set)
-                else:
-                    inspect_selection_set(selection.selection_set)
-            elif isinstance(selection, FragmentSpreadNode):
-                fragment = info.fragments.get(selection.name.value)
-                if fragment is not None:
-                    inspect_selection_set(fragment.selection_set)
-            elif isinstance(selection, InlineFragmentNode):
-                inspect_selection_set(selection.selection_set)
-
-    for node in info.field_nodes:
-        inspect_selection_set(node.selection_set)
-    return property_names
+    return collect_selected_graphql_property_names(
+        info,
+        manager_class,
+        root_field="item",
+        normalize_name=normalize_graphql_name,
+    )
 
 
 # ---------------------------------------------------------------------------

{generalmanager-0.46.0 → generalmanager-0.47.0}/src/general_manager/cache/cache_decorator.py

@@ -16,6 +16,11 @@ from typing import (
 from django.core.cache import cache as django_cache
 
 from general_manager.cache.cache_tracker import DependencyTracker
+from general_manager.cache.dependency_cache import (
+    DependencyCacheHit,
+    read_dependency_cache_hit,
+    replay_dependency_cache_hit,
+)
 from general_manager.cache.dependency_index import (
     Dependency,
     get_dependency_generation,
@@ -26,9 +31,12 @@ from general_manager.cache.dependency_publish import (
     acquire_compute_lease,
     publish_dependency_cache_entry,
     release_compute_lease,
-    wait_for_cached_dependency_value,
+    wait_for_cached_dependency_hit,
+)
+from general_manager.cache.run_context import (
+    current_calculation_run_context,
+    ensure_calculation_run_context,
 )
-from general_manager.cache.run_context import ensure_calculation_run_context
 from general_manager.cache.model_dependency_collector import ModelDependencyCollector
 from general_manager.logging import get_logger
 from general_manager.utils.make_cache_key import make_cache_key
@@ -179,52 +187,59 @@ def cached(
                 )
                 return result
 
-            deps_key = f"{key}:deps"
-
-            def track_cached_dependencies() -> None:
-                cached_deps = cache_backend.get(deps_key)
-                if cached_deps:
-                    for class_name, operation, identifier in cached_deps:
-                        DependencyTracker.track(class_name, operation, identifier)
-
-            cached_result = cache_backend.get(key, _SENTINEL)
-            if cached_result is not _SENTINEL:
-                track_cached_dependencies()
+            def return_cached_hit(hit: DependencyCacheHit, message: str) -> object:
+                replay_dependency_cache_hit(hit)
                 logger.debug(
-                    "cache hit",
+                    message,
                     context={
                         "function": func.__qualname__,
                         "key": key,
                         "scope": scope,
                     },
                 )
-                return cached_result
+                return hit.value
+
+            prefetch_context = current_calculation_run_context()
+            if prefetch_context is not None:
+                prefetched_hit = prefetch_context.get_dependency_cache_hit(
+                    key, _SENTINEL
+                )
+                if isinstance(prefetched_hit, DependencyCacheHit):
+                    return return_cached_hit(
+                        prefetched_hit,
+                        "cache hit from dependency prefetch",
+                    )
+
+            cached_hit = read_dependency_cache_hit(
+                cache_backend,
+                key,
+                sentinel=_SENTINEL,
+            )
+            if cached_hit is not _SENTINEL:
+                return return_cached_hit(cached_hit, "cache hit")
 
             lease = acquire_compute_lease(key)
             while lease is None:
-                cached_result = wait_for_cached_dependency_value(
+                cached_hit = wait_for_cached_dependency_hit(
                     cache_backend,
                     key,
                     sentinel=_SENTINEL,
                 )
-                if cached_result is not _SENTINEL:
-                    track_cached_dependencies()
-                    logger.debug(
+                if cached_hit is not _SENTINEL:
+                    return return_cached_hit(
+                        cached_hit,
                         "cache hit after waiting for dependency publish",
-                        context={
-                            "function": func.__qualname__,
-                            "key": key,
-                            "scope": scope,
-                        },
                     )
-                    return cached_result
                 lease = acquire_compute_lease(key)
 
             try:
-                cached_result = cache_backend.get(key, _SENTINEL)
-                if cached_result is not _SENTINEL:
-                    track_cached_dependencies()
-                    return cached_result
+                cached_hit = read_dependency_cache_hit(
+                    cache_backend,
+                    key,
+                    sentinel=_SENTINEL,
+                )
+                if cached_hit is not _SENTINEL:
+                    return return_cached_hit(cached_hit, "cache hit")
 
                 started_generation = get_dependency_generation()
                 with DependencyTracker() as dependencies:
@@ -240,7 +255,6 @@ def cached(
                 try:
                     publish_dependency_cache_entry(
                         cache_key=key,
-                        deps_key=deps_key,
                         result=result,
                         dependencies=dependencies,
                         cache_backend=cache_backend,

generalmanager-0.47.0/src/general_manager/cache/dependency_cache.py

@@ -0,0 +1,154 @@
+"""Internal helpers for dependency-scoped cache entry reads."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable, Mapping, Protocol, TypeGuard
+
+from general_manager.cache.cache_tracker import DependencyTracker
+from general_manager.cache.dependency_index import Dependency
+
+DEPENDENCY_CACHE_ENTRY_VERSION = 1
+_MISSING = object()
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyCacheEntry:
+    """Persisted dependency-cache payload stored at the main cache key."""
+
+    version: int
+    value: Any
+    dependencies: frozenset[Dependency]
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyCacheHit:
+    """In-memory representation of a dependency-cache hit."""
+
+    value: Any
+    dependencies: frozenset[Dependency]
+
+
+class DependencyCacheBackend(Protocol):
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return a cached value or *default* when absent."""
+        ...
+
+    def set(self, key: str, value: Any, timeout: int | None = None) -> None:
+        """Store a cached value."""
+        ...
+
+
+class DependencyCacheGetManyBackend(DependencyCacheBackend, Protocol):
+    def get_many(self, keys: Iterable[str]) -> Mapping[str, Any]:
+        """Return cached values for all found keys."""
+        ...
+
+
+def make_dependency_cache_entry(
+    value: Any,
+    dependencies: Iterable[Dependency],
+) -> DependencyCacheEntry:
+    """Build the current persisted dependency-cache payload."""
+    return DependencyCacheEntry(
+        version=DEPENDENCY_CACHE_ENTRY_VERSION,
+        value=value,
+        dependencies=frozenset(dependencies),
+    )
+
+
+def read_dependency_cache_hit(
+    cache_backend: DependencyCacheBackend,
+    cache_key: str,
+    *,
+    sentinel: Any = _MISSING,
+) -> DependencyCacheHit | Any:
+    """Read one dependency-cache entry, including legacy split entries."""
+    payload = cache_backend.get(cache_key, sentinel)
+    if payload is sentinel:
+        return sentinel
+    combined_hit = _combined_payload_to_hit(payload)
+    if combined_hit is _MISSING:
+        return sentinel
+    if combined_hit is not None:
+        return combined_hit
+    dependency_payload = cache_backend.get(_legacy_deps_key(cache_key), ())
+    return DependencyCacheHit(
+        value=payload,
+        dependencies=frozenset(dependency_payload or ()),
+    )
+
+
+def read_many_dependency_cache_hits(
+    cache_backend: DependencyCacheBackend,
+    cache_keys: Iterable[str],
+) -> dict[str, DependencyCacheHit]:
+    """Bulk-read dependency-cache hits for known keys."""
+    keys = tuple(dict.fromkeys(cache_keys))
+    if not keys:
+        return {}
+    if not _supports_get_many(cache_backend):
+        return _read_many_without_get_many(cache_backend, keys)
+
+    payloads = cache_backend.get_many(keys)
+    hits: dict[str, DependencyCacheHit] = {}
+    legacy_keys: list[str] = []
+    for key in keys:
+        if key not in payloads:
+            continue
+        combined_hit = _combined_payload_to_hit(payloads[key])
+        if combined_hit is _MISSING:
+            continue
+        if isinstance(combined_hit, DependencyCacheHit):
+            hits[key] = combined_hit
+            continue
+        legacy_keys.append(key)
+
+    if legacy_keys:
+        deps_keys = {_legacy_deps_key(key): key for key in legacy_keys}
+        legacy_deps = cache_backend.get_many(deps_keys.keys())
+        for deps_key, key in deps_keys.items():
+            hits[key] = DependencyCacheHit(
+                value=payloads[key],
+                dependencies=frozenset(legacy_deps.get(deps_key, ()) or ()),
+            )
+    return hits
+
+
+def replay_dependency_cache_hit(hit: DependencyCacheHit) -> None:
+    """Replay cached dependencies into active dependency tracking scopes."""
+    for class_name, operation, identifier in hit.dependencies:
+        DependencyTracker.track(class_name, operation, identifier)
+
+
+def _legacy_deps_key(cache_key: str) -> str:
+    return f"{cache_key}:deps"
+
+
+def _combined_payload_to_hit(payload: Any) -> DependencyCacheHit | None | object:
+    if not isinstance(payload, DependencyCacheEntry):
+        return None
+    if payload.version != DEPENDENCY_CACHE_ENTRY_VERSION:
+        return _MISSING
+    return DependencyCacheHit(
+        value=payload.value,
+        dependencies=payload.dependencies,
+    )
+
+
+def _supports_get_many(
+    cache_backend: DependencyCacheBackend,
+) -> TypeGuard[DependencyCacheGetManyBackend]:
+    return callable(getattr(cache_backend, "get_many", None))
+
+
+def _read_many_without_get_many(
+    cache_backend: DependencyCacheBackend,
+    cache_keys: tuple[str, ...],
+) -> dict[str, DependencyCacheHit]:
+    hits: dict[str, DependencyCacheHit] = {}
+    for key in cache_keys:
+        hit = read_dependency_cache_hit(cache_backend, key, sentinel=_MISSING)
+        if hit is not _MISSING:
+            hits[key] = hit
+    return hits