GeneralManager 0.42.2__tar.gz → 0.43.0__tar.gz

{generalmanager-0.42.2/src/GeneralManager.egg-info → generalmanager-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.42.2
+Version: 0.43.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.42.2 → generalmanager-0.43.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.42.2
+Version: 0.43.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.42.2 → generalmanager-0.43.0}/src/general_manager/bucket/database_bucket.py

@@ -689,10 +689,12 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
 
         self._track_effective_dependencies()
         if isinstance(item, GeneralManager):
-            return item.identification.get("id", None) in self._data.values_list(
-                "pk", flat=True
-            )
-        return item.pk in self._data.values_list("pk", flat=True)
+            pk = item.identification.get("id", None)
+        else:
+            pk = item.pk
+        if pk is None:
+            return False
+        return self._data.filter(pk=pk).exists()
 
     def sort(
         self,

{generalmanager-0.42.2 → generalmanager-0.43.0}/src/general_manager/cache/cache_decorator.py

@@ -44,7 +44,7 @@ class CacheBackend(Protocol):
 
 RecordFn = Callable[[str, Set[Dependency]], None]
 FuncT = TypeVar("FuncT", bound=Callable[..., object])
-CacheScope = Literal["dependency", "run", "none"]
+CacheScope = Literal["dependency", "run", "timeout", "none"]
 
 _SENTINEL = object()
 logger = get_logger("cache.decorator")
@@ -57,31 +57,67 @@ class UnsupportedCacheScopeError(ValueError):
         super().__init__(f"Unsupported cache scope: {scope}")
 
 
+class CacheTimeoutConfigurationError(ValueError):
+    """Raised when timeout is used with an incompatible cache scope."""
+
+    @classmethod
+    def missing_timeout(cls) -> "CacheTimeoutConfigurationError":
+        return cls('scope="timeout" requires timeout')
+
+    @classmethod
+    def unexpected_timeout(cls) -> "CacheTimeoutConfigurationError":
+        return cls('timeout is only supported with scope="timeout"')
+
+
 def cached(
     timeout: Optional[int] = None,
     cache_backend: CacheBackend = django_cache,
     record_fn: RecordFn = record_dependencies,
     *,
-    scope: CacheScope = "dependency",
+    scope: CacheScope = "run",
 ) -> Callable[[FuncT], FuncT]:
     """
-    Cache a function call while registering its data dependencies.
+    Decorator factory 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
+    in ``cache_backend`` and use ``record_fn`` to persist dependency metadata
+    for invalidation. Use ``scope="timeout"`` with ``timeout`` set for
+    cache-backend storage with time-based expiry; dependency recording is
+    ignored for timeout-scoped values.
 
     Parameters:
-        timeout (int | None): Expiration in seconds for cached values; `None` stores results until invalidated.
+        timeout (int | None): Expiration in seconds for timeout-scoped cached values.
+            Required when ``scope`` 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 no timeout is
-            defined.  Defaults to :func:`~general_manager.cache.dependency_index.record_dependencies`.
+        record_fn (RecordFn): Callback invoked to persist dependency metadata when
+            ``scope`` is ``"dependency"``. Defaults to
+            :func:`~general_manager.cache.dependency_index.record_dependencies`.
+        scope (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.
 
     Raises:
+        ValueError: Raised for invalid ``scope``/``timeout`` combinations, including
+            unsupported ``CacheScope`` values, missing ``timeout`` for
+            ``scope="timeout"``, and ``timeout`` supplied for non-timeout scopes.
         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
             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:
+        raise CacheTimeoutConfigurationError.missing_timeout()
+    if timeout is not None and scope != "timeout":
+        raise CacheTimeoutConfigurationError.unexpected_timeout()
 
     def decorator(func: FuncT) -> FuncT:
         @wraps(func)
@@ -94,10 +130,34 @@ def cached(
                 with ensure_calculation_run_context() as context:
                     return context.get_or_set(key, lambda: func(*args, **kwargs))
 
-            if scope != "dependency":
-                raise UnsupportedCacheScopeError(scope)
-
             key = make_cache_key(func, args, kwargs)
+
+            if scope == "timeout":
+                cached_result = cache_backend.get(key, _SENTINEL)
+                if cached_result is not _SENTINEL:
+                    logger.debug(
+                        "cache hit",
+                        context={
+                            "function": func.__qualname__,
+                            "key": key,
+                            "scope": scope,
+                        },
+                    )
+                    return cached_result
+
+                result = func(*args, **kwargs)
+                cache_backend.set(key, result, timeout)
+                logger.debug(
+                    "cache miss stored",
+                    context={
+                        "function": func.__qualname__,
+                        "key": key,
+                        "timeout": timeout,
+                        "scope": scope,
+                    },
+                )
+                return result
+
             deps_key = f"{key}:deps"
 
             cached_result = cache_backend.get(key, _SENTINEL)

{generalmanager-0.42.2 → generalmanager-0.43.0}/src/general_manager/cache/run_context.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections import defaultdict
 from collections.abc import Callable, Hashable, Iterable
 from contextvars import ContextVar, Token
 from types import TracebackType
@@ -44,6 +45,22 @@ class CalculationRunContext:
             self._values[key] = loader()
         return self._values[key]  # type: ignore[return-value]
 
+    def get(self, key: Hashable, default: object = None) -> object:
+        """Return the stored value for key, or default when key is absent."""
+        return self._values.get(key, default)
+
+    def set(self, key: Hashable, value: object) -> None:
+        """Store a value for the active run."""
+        self._values[key] = value
+
+    def has(self, key: Hashable) -> bool:
+        """Return whether key has a value in the active run."""
+        return key in self._values
+
+    def __contains__(self, key: Hashable) -> bool:
+        """Return whether key has a value in the active run."""
+        return self.has(key)
+
     def index(
         self,
         *,
@@ -57,6 +74,33 @@ class CalculationRunContext:
             lambda: {index_by(row): row for row in loader()},
         )
 
+    def group_by(
+        self,
+        *,
+        key: Hashable,
+        loader: Callable[[], Iterable[T]],
+        group_by: Callable[[T], K],
+    ) -> dict[K, list[T]]:
+        """Load a working set once and group it by the supplied key function."""
+
+        def load_groups() -> dict[K, list[T]]:
+            grouped: defaultdict[K, list[T]] = defaultdict(list)
+            for row in loader():
+                grouped[group_by(row)].append(row)
+            return dict(grouped)
+
+        return self.get_or_set(("group_by", key), load_groups)
+
+    def index_many(
+        self,
+        *,
+        key: Hashable,
+        loader: Callable[[], Iterable[T]],
+        index_by: Callable[[T], K],
+    ) -> dict[K, list[T]]:
+        """Load a working set once and group rows sharing the same index key."""
+        return self.group_by(key=key, loader=loader, group_by=index_by)
+
 
 def current_calculation_run_context() -> CalculationRunContext | None:
     """Return the active calculation run context, if any."""

{generalmanager-0.42.2 → generalmanager-0.43.0}/src/general_manager/interface/capabilities/calculation/lifecycle.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 from typing import Any, TYPE_CHECKING, ClassVar
 
 from general_manager.bucket.calculation_bucket import CalculationBucket
+from general_manager.cache.cache_tracker import DependencyTracker
+from general_manager.cache.dependency_index import serialize_dependency_identifier
 from general_manager.manager.general_manager import GeneralManager
 from general_manager.manager.input import Input
 
@@ -18,6 +20,15 @@ if TYPE_CHECKING:  # pragma: no cover
     )
 
 
+def _track_cached_manager(value: Any) -> None:
+    if isinstance(value, GeneralManager):
+        DependencyTracker.track(
+            value.__class__.__name__,
+            "identification",
+            serialize_dependency_identifier(value.identification),
+        )
+
+
 class CalculationReadCapability(BaseCapability):
     """Calculations expose inputs only and never persist data."""
 
@@ -88,8 +99,8 @@ class CalculationReadCapability(BaseCapability):
             input_field = interface_cls.input_fields[field_name]
             if field_name in resolved_values:
                 cached_value = resolved_values[field_name]
-                if not isinstance(cached_value, GeneralManager):
-                    return cached_value
+                _track_cached_manager(cached_value)
+                return cached_value
 
             input_field = interface_cls.input_fields[field_name]
             dependency_values = {
@@ -103,8 +114,7 @@ class CalculationReadCapability(BaseCapability):
                 interface_instance.identification.get(field_name),
                 dependency_values,
             )
-            if not isinstance(value, GeneralManager):
-                resolved_values[field_name] = value
+            resolved_values[field_name] = value
             return value
 
         return {

{generalmanager-0.42.2 → generalmanager-0.43.0}/src/general_manager/interface/capabilities/orm/support.py

@@ -328,9 +328,28 @@ class OrmReadCapability(BaseCapability):
             field_name (str): Name of the field on the model.
 
         Returns:
-            type: The class used to represent the field's values: the related model's `_general_manager_class` when the field is a relation to a model that exposes that attribute, otherwise the Python type of the field object.
-        """
-        field = interface_cls._model._meta.get_field(field_name)
+            type: The Django field class for stored model fields, the related
+            model's `_general_manager_class` for managed relations, or descriptor
+            metadata for synthetic interface fields.
+        """
+        try:
+            field = interface_cls._model._meta.get_field(field_name)
+        except FieldDoesNotExist:
+            descriptors = get_support_capability(interface_cls).get_field_descriptors(
+                interface_cls
+            )
+            descriptor = descriptors.get(field_name)
+            if descriptor is not None:
+                return descriptor.metadata["type"]
+            raise
+        if getattr(field, "name", field_name) != field_name:
+            descriptor = (
+                get_support_capability(interface_cls)
+                .get_field_descriptors(interface_cls)
+                .get(field_name)
+            )
+            if descriptor is not None:
+                return descriptor.metadata["type"]
         if (
             field.is_relation
             and field.related_model

{generalmanager-0.42.2 → generalmanager-0.43.0}/src/general_manager/interface/capabilities/orm_utils/field_descriptors.py

@@ -227,6 +227,20 @@ class _FieldDescriptorBuilder:
                 relation_kind="direct",
                 filter_lookup=field.name,
             )
+            raw_id_name = getattr(field, "attname", f"{field.name}_id")
+            if raw_id_name not in self._descriptors:
+                target_field = getattr(field, "target_field", None)
+                raw_id_type = type(target_field) if target_field is not None else int
+                self._register(
+                    attribute_name=raw_id_name,
+                    raw_type=raw_id_type,
+                    is_required=not field.null,
+                    is_editable=False,
+                    default=default,
+                    is_derived=False,
+                    accessor=_instance_attribute_accessor(raw_id_name),
+                    filter_lookup=raw_id_name,
+                )
 
     def _add_reverse_one_to_one_relations(self) -> None:
         """Register snake_case aliases for reverse one-to-one relation accessors."""

{generalmanager-0.42.2 → generalmanager-0.43.0}/src/general_manager/manager/input.py

@@ -661,10 +661,18 @@ class Input(Generic[INPUT_TYPE]):
 
         if value is None:
             return None
-        possible_values = self.resolve_possible_values(identification)
+        possible_values = (
+            self.possible_values
+            if isinstance(self.possible_values, InputDomain)
+            else None
+        )
         if isinstance(possible_values, InputDomain):
             value = possible_values.normalize(value)
         if self.normalizer is not None:
+            if possible_values is None:
+                possible_values = self.resolve_possible_values(identification)
+                if isinstance(possible_values, InputDomain):
+                    value = possible_values.normalize(value)
             dependency_values = self._build_dependency_values(identification)
             return _invoke_callable(
                 self.normalizer,

{generalmanager-0.42.2 → generalmanager-0.43.0}/src/general_manager/permission/base_permission.py

@@ -437,7 +437,10 @@ class BasePermission(ABC):
         """
         Resolve a user identifier or user-like object to a Django User or AnonymousUser instance.
 
-        If the input is already an AbstractBaseUser or AnonymousUser, it is returned unchanged. If the input is a primary key (or other value used to look up a User by id), the corresponding User is returned; if no such User exists, an AnonymousUser is returned.
+        If the input is already an AbstractBaseUser, AnonymousUser, or configured
+        user-model instance, it is returned unchanged. If the input is a primary
+        key (or other value used to look up a User by id), the corresponding User
+        is returned; if no such User exists, an AnonymousUser is returned.
 
         Parameters:
             user (Any | UserLike): A user object or a value to look up a User by primary key.
@@ -454,7 +457,7 @@ class BasePermission(ABC):
             user = lazy_user._wrapped
 
         User = get_user_model()
-        if isinstance(user, (AbstractBaseUser, AnonymousUser)):
+        if isinstance(user, (AbstractBaseUser, AnonymousUser, User)):
             return user
         try:
             return User.objects.get(pk=user)