GeneralManager 0.48.0__tar.gz → 0.50.0__tar.gz

{generalmanager-0.48.0/src/GeneralManager.egg-info → generalmanager-0.50.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.48.0
+Version: 0.50.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.48.0 → generalmanager-0.50.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.48.0
+Version: 0.50.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.48.0 → generalmanager-0.50.0}/src/general_manager/api/property.py

@@ -95,7 +95,7 @@ class GraphQLProperty(property):
         selected_cache = self.cache
         if selected_cache == "none":
             return self._raw_fget
-        return cached(scope=cast(Literal["dependency", "run"], selected_cache))(
+        return cached(cache=cast(Literal["dependency", "run"], selected_cache))(
             self._raw_fget
         )
 

{generalmanager-0.48.0 → generalmanager-0.50.0}/src/general_manager/cache/cache_decorator.py

@@ -11,6 +11,7 @@ from typing import (
     Set,
     TypeVar,
     cast,
+    overload,
 )
 
 from django.core.cache import cache as django_cache
@@ -28,6 +29,7 @@ from general_manager.cache.dependency_index import (
 )
 from general_manager.cache.dependency_publish import (
     CachePublishAborted,
+    PendingDependencyCachePublication,
     acquire_compute_lease,
     publish_dependency_cache_entry,
     release_compute_lease,
@@ -87,102 +89,122 @@ class UnsupportedCacheScopeError(ValueError):
 
 
 class CacheTimeoutConfigurationError(ValueError):
-    """Raised when timeout is used with an incompatible cache scope."""
+    """Raised when timeout is used with an incompatible cache setting."""
 
     @classmethod
     def missing_timeout(cls) -> "CacheTimeoutConfigurationError":
-        return cls('scope="timeout" requires timeout')
+        return cls('cache="timeout" requires timeout')
 
     @classmethod
     def unexpected_timeout(cls) -> "CacheTimeoutConfigurationError":
-        return cls('timeout is only supported with scope="timeout"')
+        return cls('timeout is only supported with cache="timeout"')
 
 
+@overload
+def cached(func: FuncT) -> FuncT: ...
+@overload
 def cached(
+    func: None = None,
     timeout: Optional[int] = None,
     cache_backend: CacheBackend = django_cache,
     record_fn: RecordFn = record_dependencies,
     *,
-    scope: CacheScope = "run",
-) -> Callable[[FuncT], FuncT]:
+    cache: CacheScope = "run",
+) -> Callable[[FuncT], FuncT]: ...
+
+
+def cached(
+    func: FuncT | None = None,
+    timeout: Optional[int] = None,
+    cache_backend: CacheBackend = django_cache,
+    record_fn: RecordFn = record_dependencies,
+    *,
+    cache: CacheScope = "run",
+) -> FuncT | Callable[[FuncT], FuncT]:
     """
-    Decorator factory for caching a function call.
+    Decorator for caching a function call.
 
     By default, cached values are scoped to the active
     :class:`~general_manager.cache.run_context.CalculationRunContext` and are
-    discarded when that run ends. Use ``scope="dependency"`` to persist values
+    discarded when that run ends. Use ``cache="dependency"`` to persist values
     in ``cache_backend`` and use ``record_fn`` to persist dependency metadata
-    for invalidation. Use ``scope="timeout"`` with ``timeout`` set for
+    for invalidation. Use ``cache="timeout"`` with ``timeout`` set for
     cache-backend storage with time-based expiry; dependency recording is
-    ignored for timeout-scoped values.
+    ignored for timeout-cached values.
 
     Parameters:
-        timeout (int | None): Expiration in seconds for timeout-scoped cached values.
-            Required when ``scope`` is ``"timeout"`` and invalid with any other
+        func (Callable[..., object] | None): Function being decorated when used
+            as ``@cached``. Leave unset when using ``@cached(...)``.
+        timeout (int | None): Expiration in seconds for timeout-cached values.
+            Required when ``cache`` is ``"timeout"`` and invalid with any other
             ``CacheScope``.
         cache_backend (CacheBackend): Backend used to read and write cached results.
         record_fn (RecordFn): Callback invoked to persist dependency metadata when
-            ``scope`` is ``"dependency"``. Defaults to
+            ``cache`` is ``"dependency"``. Defaults to
             :func:`~general_manager.cache.dependency_index.record_dependencies`.
-        scope (CacheScope): Cache storage strategy. ``"run"`` memoizes for the active run,
+        cache (CacheScope): Cache storage strategy. ``"run"`` memoizes for the active run,
             ``"dependency"`` stores in ``cache_backend`` with dependency tracking,
             ``"timeout"`` stores in ``cache_backend`` with time-based expiry, and
             ``"none"`` disables caching.
 
     Returns:
-        Callable: Decorator that wraps the target function with caching behaviour.
+        Callable: Decorated function or decorator that wraps the target function
+            with caching behaviour.
 
     Raises:
-        ValueError: Raised for invalid ``scope``/``timeout`` combinations, including
+        ValueError: Raised for invalid ``cache``/``timeout`` combinations, including
             unsupported ``CacheScope`` values, missing ``timeout`` for
-            ``scope="timeout"``, and ``timeout`` supplied for non-timeout scopes.
+            ``cache="timeout"``, and ``timeout`` supplied for non-timeout cache modes.
         DependencyLockTimeoutError: Propagated from ``record_fn`` (i.e.
             :func:`~general_manager.cache.dependency_index.record_dependencies`) when the
-            dependency-index lock cannot be acquired within the configured timeout.  The cached
+            dependency-index lock cannot be acquired within the configured timeout. The cached
             value has already been stored at that point; only the dependency metadata is lost.
     """
-    if scope not in {"dependency", "run", "timeout", "none"}:
-        raise UnsupportedCacheScopeError(scope)
-    if scope == "timeout" and timeout is None:
+    if cache not in {"dependency", "run", "timeout", "none"}:
+        raise UnsupportedCacheScopeError(cache)
+    if cache == "timeout" and timeout is None:
         raise CacheTimeoutConfigurationError.missing_timeout()
-    if timeout is not None and scope != "timeout":
+    if timeout is not None and cache != "timeout":
         raise CacheTimeoutConfigurationError.unexpected_timeout()
 
-    def decorator(func: FuncT) -> FuncT:
-        @wraps(func)
+    def decorator(decorated_func: FuncT) -> FuncT:
+        @wraps(decorated_func)
         def wrapper(*args: object, **kwargs: object) -> object:
-            if scope == "none":
-                return func(*args, **kwargs)
+            if cache == "none":
+                return decorated_func(*args, **kwargs)
 
-            if scope == "run":
-                key = make_cache_key(func, args, kwargs)
+            if cache == "run":
+                key = make_cache_key(decorated_func, args, kwargs)
                 with ensure_calculation_run_context() as context:
-                    return context.get_or_set(key, lambda: func(*args, **kwargs))
+                    return context.get_or_set(
+                        key,
+                        lambda: decorated_func(*args, **kwargs),
+                    )
 
-            key = make_cache_key(func, args, kwargs)
+            key = make_cache_key(decorated_func, args, kwargs)
 
-            if scope == "timeout":
+            if cache == "timeout":
                 cached_result = cache_backend.get(key, _SENTINEL)
                 if cached_result is not _SENTINEL:
                     logger.debug(
                         "cache hit",
                         context={
-                            "function": func.__qualname__,
+                            "function": decorated_func.__qualname__,
                             "key": key,
-                            "scope": scope,
+                            "cache": cache,
                         },
                     )
                     return cached_result
 
-                result = func(*args, **kwargs)
+                result = decorated_func(*args, **kwargs)
                 cache_backend.set(key, result, timeout)
                 logger.debug(
                     "cache miss stored",
                     context={
-                        "function": func.__qualname__,
+                        "function": decorated_func.__qualname__,
                         "key": key,
                         "timeout": timeout,
-                        "scope": scope,
+                        "cache": cache,
                     },
                 )
                 return result
@@ -192,9 +214,9 @@ def cached(
                 logger.debug(
                     message,
                     context={
-                        "function": func.__qualname__,
+                        "function": decorated_func.__qualname__,
                         "key": key,
-                        "scope": scope,
+                        "cache": cache,
                     },
                 )
                 return hit.value
@@ -232,6 +254,7 @@ def cached(
                     )
                 lease = acquire_compute_lease(key)
 
+            lease_transferred_to_context = False
             try:
                 cached_hit = read_dependency_cache_hit(
                     cache_backend,
@@ -243,7 +266,7 @@ def cached(
 
                 started_generation = get_dependency_generation()
                 with DependencyTracker() as dependencies:
-                    result = func(*args, **kwargs)
+                    result = decorated_func(*args, **kwargs)
                     ModelDependencyCollector.add_args(dependencies, args, kwargs)
 
                 def record_many(
@@ -252,34 +275,52 @@ def cached(
                     for entry_key, entry_dependencies in entries:
                         record_fn(entry_key, set(entry_dependencies))
 
-                try:
-                    publish_dependency_cache_entry(
-                        cache_key=key,
-                        result=result,
-                        dependencies=dependencies,
-                        cache_backend=cache_backend,
-                        timeout=timeout,
-                        started_generation=started_generation,
-                        record_many_fn=(
-                            None if record_fn is record_dependencies else record_many
-                        ),
-                    )
-                except CachePublishAborted:
-                    logger.debug(
-                        "dependency cache publish aborted",
-                        context={
-                            "function": func.__qualname__,
-                            "key": key,
-                            "scope": scope,
-                        },
+                publish_context = current_calculation_run_context()
+                if publish_context is not None and record_fn is record_dependencies:
+                    publish_context.buffer_dependency_cache_publication(
+                        PendingDependencyCachePublication(
+                            cache_key=key,
+                            result=result,
+                            dependencies=frozenset(dependencies),
+                            cache_backend=cache_backend,
+                            timeout=timeout,
+                            started_generation=started_generation,
+                            lease=lease,
+                        )
                     )
+                    lease_transferred_to_context = True
+                else:
+                    try:
+                        publish_dependency_cache_entry(
+                            cache_key=key,
+                            result=result,
+                            dependencies=dependencies,
+                            cache_backend=cache_backend,
+                            timeout=timeout,
+                            started_generation=started_generation,
+                            record_many_fn=(
+                                None
+                                if record_fn is record_dependencies
+                                else record_many
+                            ),
+                        )
+                    except CachePublishAborted:
+                        logger.debug(
+                            "dependency cache publish aborted",
+                            context={
+                                "function": decorated_func.__qualname__,
+                                "key": key,
+                                "cache": cache,
+                            },
+                        )
             finally:
-                release_compute_lease(lease)
+                if not lease_transferred_to_context:
+                    release_compute_lease(lease)
 
             logger.debug(
                 "cache miss recorded",
                 context={
-                    "function": func.__qualname__,
+                    "function": decorated_func.__qualname__,
                     "key": key,
                     "dependency_count": len(dependencies),
                     "timeout": timeout,
@@ -288,8 +329,10 @@ def cached(
             return result
 
         # fix for python 3.14:
-        wrapper.__annotations__ = func.__annotations__
+        wrapper.__annotations__ = decorated_func.__annotations__
 
         return cast(FuncT, wrapper)
 
-    return decorator
+    if func is None:
+        return decorator
+    return decorator(func)

{generalmanager-0.48.0 → generalmanager-0.50.0}/src/general_manager/cache/dependency_cache.py

@@ -45,6 +45,16 @@ class DependencyCacheGetManyBackend(DependencyCacheBackend, Protocol):
         ...
 
 
+class DependencyCacheSetManyBackend(DependencyCacheBackend, Protocol):
+    def set_many(
+        self,
+        data: Mapping[str, Any],
+        timeout: int | None = None,
+    ) -> Any:
+        """Store cached values for many keys."""
+        ...
+
+
 def make_dependency_cache_entry(
     value: Any,
     dependencies: Iterable[Dependency],

{generalmanager-0.48.0 → generalmanager-0.50.0}/src/general_manager/cache/dependency_index.py

@@ -124,6 +124,14 @@ def _set_dependency_data_change_count(count: int) -> int:
     return count
 
 
+def _discard_active_context_dependency_cache_state() -> None:
+    from general_manager.cache.run_context import current_calculation_run_context
+
+    context = current_calculation_run_context()
+    if context is not None:
+        context.discard_dependency_cache_state()
+
+
 def begin_dependency_data_change() -> int:
     """
     Mark a data change as active and bump the dependency generation.
@@ -136,9 +144,17 @@ def begin_dependency_data_change() -> int:
         generation = _set_dependency_generation(get_dependency_generation() + 1)
         _set_dependency_data_change_count(_get_dependency_data_change_count() + 1)
         cache.set(DATA_CHANGE_LOCK_KEY, "1", None)
-        return generation
     finally:
         release_lock()
+    try:
+        _discard_active_context_dependency_cache_state()
+    except Exception:
+        try:
+            end_dependency_data_change()
+        except Exception:
+            logger.exception("dependency data-change cleanup rollback failed")
+        raise
+    return generation
 
 
 def end_dependency_data_change() -> None:

{generalmanager-0.48.0 → generalmanager-0.50.0}/src/general_manager/cache/dependency_publish.py

@@ -4,13 +4,15 @@ from __future__ import annotations
 
 import time
 import uuid
+from collections import defaultdict
 from dataclasses import dataclass
-from typing import Any, Callable, Iterable
+from typing import Any, Callable, Iterable, TypeGuard
 
 from django.core.cache import cache as coordination_cache
 
 from general_manager.cache.dependency_cache import (
     DependencyCacheBackend,
+    DependencyCacheSetManyBackend,
     make_dependency_cache_entry,
     read_dependency_cache_hit,
 )
@@ -39,6 +41,19 @@ class CacheComputeLease:
     token: str
 
 
+@dataclass(frozen=True)
+class PendingDependencyCachePublication:
+    """A dependency-cache miss waiting for guarded publication."""
+
+    cache_key: str
+    result: Any
+    dependencies: frozenset[Dependency]
+    cache_backend: DependencyCacheBackend
+    timeout: int | None
+    started_generation: int
+    lease: CacheComputeLease
+
+
 RecordManyDependenciesFn = Callable[[Iterable[tuple[str, Iterable[Dependency]]]], None]
 
 COMPUTE_LOCK_PREFIX = "dependency_cache_compute_lock"
@@ -111,6 +126,81 @@ def _ensure_publish_current(started_generation: int) -> None:
         raise CachePublishAborted()
 
 
+def _supports_set_many(
+    cache_backend: DependencyCacheBackend,
+) -> TypeGuard[DependencyCacheSetManyBackend]:
+    return callable(getattr(cache_backend, "set_many", None))
+
+
+def _set_dependency_cache_entries(
+    entries: Iterable[PendingDependencyCachePublication],
+) -> None:
+    grouped: dict[
+        tuple[int, int | None],
+        list[PendingDependencyCachePublication],
+    ] = defaultdict(list)
+    for entry in entries:
+        grouped[(id(entry.cache_backend), entry.timeout)].append(entry)
+
+    for group_entries in grouped.values():
+        cache_backend = group_entries[0].cache_backend
+        timeout = group_entries[0].timeout
+        payloads = {
+            entry.cache_key: make_dependency_cache_entry(
+                entry.result,
+                entry.dependencies,
+            )
+            for entry in group_entries
+        }
+        if _supports_set_many(cache_backend):
+            failed_keys = cache_backend.set_many(payloads, timeout) or ()
+            for key in failed_keys:
+                if key in payloads:
+                    cache_backend.set(key, payloads[key], timeout)
+            continue
+        for key, payload in payloads.items():
+            cache_backend.set(key, payload, timeout)
+
+
+def publish_dependency_cache_entries(
+    entries: Iterable[PendingDependencyCachePublication],
+) -> None:
+    """Publish dependency metadata and values for current entries in one batch."""
+    pending_entries = tuple(entries)
+    if not pending_entries:
+        return
+
+    acquire_lock_with_retry("publish_dependency_cache_entries")
+    try:
+        if is_dependency_data_change_active():
+            raise CachePublishAborted()
+
+        current_generation = get_dependency_generation()
+        publishable_entries = tuple(
+            entry
+            for entry in pending_entries
+            if entry.started_generation == current_generation
+        )
+        if not publishable_entries:
+            return
+
+        idx = get_full_index()
+        for entry in publishable_entries:
+            if entry.dependencies:
+                _record_dependencies_locked(
+                    idx,
+                    entry.cache_key,
+                    entry.dependencies,
+                )
+
+        _ensure_publish_current(current_generation)
+        set_full_index(idx)
+        _ensure_publish_current(current_generation)
+        _set_dependency_cache_entries(publishable_entries)
+    finally:
+        release_lock()
+
+
 def publish_dependency_cache_entry(
     *,
     cache_key: str,

{generalmanager-0.48.0 → generalmanager-0.50.0}/src/general_manager/cache/run_context.py

@@ -8,8 +8,13 @@ from contextvars import ContextVar, Token
 from types import TracebackType
 from typing import TYPE_CHECKING, Optional, TypeVar
 
+from general_manager.logging import get_logger
+
 if TYPE_CHECKING:
     from general_manager.cache.dependency_cache import DependencyCacheHit
+    from general_manager.cache.dependency_publish import (
+        PendingDependencyCachePublication,
+    )
 
 K = TypeVar("K", bound=Hashable)
 T = TypeVar("T")
@@ -19,14 +24,27 @@ _active_context: ContextVar["CalculationRunContext | None"] = ContextVar(
     default=None,
 )
 ORM_BUCKET_RESULT_PREFIX = "orm_bucket_result"
+DEFAULT_DEPENDENCY_CACHE_PUBLISH_BATCH_SIZE = 1000
+logger = get_logger("cache.run_context")
 
 
 class CalculationRunContext:
     """Cache calculation work for one request, graph, bulk operation, or task."""
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        *,
+        dependency_cache_publish_batch_size: int = (
+            DEFAULT_DEPENDENCY_CACHE_PUBLISH_BATCH_SIZE
+        ),
+    ) -> None:
         self._values: dict[Hashable, object] = {}
         self._dependency_cache_hits: dict[str, DependencyCacheHit] = {}
+        self._dependency_cache_pending_publications: dict[
+            str,
+            PendingDependencyCachePublication,
+        ] = {}
+        self._dependency_cache_publish_batch_size = dependency_cache_publish_batch_size
         self._token: Token[CalculationRunContext | None] | None = None
 
     def __enter__(self) -> "CalculationRunContext":
@@ -39,11 +57,18 @@ class CalculationRunContext:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
-        if self._token is not None:
-            _active_context.reset(self._token)
-            self._token = None
-        self._values.clear()
-        self._dependency_cache_hits.clear()
+        try:
+            if exc_type is None:
+                self.flush_dependency_cache_publications()
+            else:
+                self.discard_dependency_cache_publications()
+        finally:
+            if self._token is not None:
+                _active_context.reset(self._token)
+                self._token = None
+            self._values.clear()
+            self._dependency_cache_hits.clear()
+            self._dependency_cache_pending_publications.clear()
 
     def get_or_set(self, key: Hashable, loader: Callable[[], T]) -> T:
         """Return a cached value for key, loading it once per active context."""
@@ -74,6 +99,73 @@ class CalculationRunContext:
         """Return a prefetched dependency-cache hit, or default when absent."""
         return self._dependency_cache_hits.get(key, default)
 
+    def buffer_dependency_cache_publication(
+        self,
+        entry: PendingDependencyCachePublication,
+    ) -> None:
+        """Buffer a dependency-cache miss for guarded batch publication."""
+        from general_manager.cache.dependency_cache import DependencyCacheHit
+        from general_manager.cache.dependency_publish import release_compute_lease
+
+        previous_entry = self._dependency_cache_pending_publications.get(
+            entry.cache_key
+        )
+        if previous_entry is not None and previous_entry.lease != entry.lease:
+            release_compute_lease(previous_entry.lease)
+        self._dependency_cache_pending_publications[entry.cache_key] = entry
+        self._dependency_cache_hits[entry.cache_key] = DependencyCacheHit(
+            value=entry.result,
+            dependencies=entry.dependencies,
+        )
+        if (
+            len(self._dependency_cache_pending_publications)
+            >= self._dependency_cache_publish_batch_size
+        ):
+            self.flush_dependency_cache_publications()
+
+    def flush_dependency_cache_publications(self) -> None:
+        """Publish buffered dependency-cache misses and release their leases."""
+        entries = tuple(self._dependency_cache_pending_publications.values())
+        if not entries:
+            return
+        self._dependency_cache_pending_publications.clear()
+
+        from general_manager.cache.dependency_publish import (
+            CachePublishAborted,
+            publish_dependency_cache_entries,
+            release_compute_lease,
+        )
+
+        try:
+            publish_dependency_cache_entries(entries)
+        except CachePublishAborted:
+            logger.debug(
+                "dependency cache batch publish aborted",
+                context={"entry_count": len(entries)},
+            )
+        finally:
+            for entry in entries:
+                release_compute_lease(entry.lease)
+
+    def discard_dependency_cache_publications(self) -> None:
+        """Drop buffered dependency-cache misses and release their leases."""
+        entries = tuple(self._dependency_cache_pending_publications.values())
+        if not entries:
+            return
+        self._dependency_cache_pending_publications.clear()
+
+        from general_manager.cache.dependency_publish import release_compute_lease
+
+        for entry in entries:
+            release_compute_lease(entry.lease)
+
+    def discard_dependency_cache_state(self) -> None:
+        """Drop dependency-cache hits and buffered publications for this run."""
+        try:
+            self.discard_dependency_cache_publications()
+        finally:
+            self._dependency_cache_hits.clear()
+
     def discard_prefix(self, prefix: tuple[Hashable, ...]) -> None:
         """Discard tuple keys that start with the supplied prefix."""
         for key in list(self._values):