GeneralManager 0.52.2__tar.gz → 0.53.0__tar.gz

{generalmanager-0.52.2/src/GeneralManager.egg-info → generalmanager-0.53.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.52.2
+Version: 0.53.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.52.2 → generalmanager-0.53.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.52.2
+Version: 0.53.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.52.2 → generalmanager-0.53.0}/src/general_manager/bucket/database_bucket.py

@@ -257,11 +257,44 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             ),
         )
 
-    def _build_manager(self, pk: Any) -> GeneralManagerType:
+    def _build_manager_from_primary_key(self, pk: Any) -> GeneralManagerType:
         if self._search_date is None:
             return self._manager_class(pk)
         return self._manager_class(pk, search_date=self._search_date)
 
+    def _can_trust_orm_instance(self, instance: models.Model) -> bool:
+        interface_model = getattr(self._manager_class.Interface, "_model", None)
+        if isinstance(interface_model, type) and issubclass(
+            interface_model, models.Model
+        ):
+            if not isinstance(instance, interface_model):
+                return False
+        get_deferred_fields = getattr(instance, "get_deferred_fields", None)
+        if callable(get_deferred_fields) and get_deferred_fields():
+            return False
+        if self._search_date is not None and not (
+            hasattr(instance, "_history") or hasattr(instance, "history_date")
+        ):
+            return False
+        return True
+
+    def _build_manager_from_instance(
+        self,
+        instance: models.Model,
+    ) -> GeneralManagerType:
+        interface_hydrate = getattr(
+            self._manager_class.Interface, "_from_trusted_orm_instance", None
+        )
+        manager_hydrate = self._manager_class._from_trusted_orm_instance
+        if callable(interface_hydrate) and self._can_trust_orm_instance(instance):
+            return manager_hydrate(instance, search_date=self._search_date)
+        return self._build_manager_from_primary_key(instance.pk)
+
+    def _build_manager(self, value: Any) -> GeneralManagerType:
+        if isinstance(value, models.Model):
+            return self._build_manager_from_instance(value)
+        return self._build_manager_from_primary_key(value)
+
     @staticmethod
     def _copy_filter_definitions(
         definitions: dict[str, Any] | None,
@@ -314,6 +347,11 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             return None
         if query.distinct:
             return None
+        if getattr(self._data, "_prefetch_related_lookups", ()):
+            return None
+        deferred_loading = getattr(query, "deferred_loading", None)
+        if isinstance(deferred_loading, tuple) and deferred_loading[0]:
+            return None
         try:
             sql, params = self._data.query.sql_with_params()
         except (EmptyResultSet, FieldError, TypeError, ValueError):
@@ -370,6 +408,28 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         context.set_orm_bucket_result(signature, primary_keys)
         return primary_keys
 
+    def _get_run_scoped_rows(self) -> tuple[models.Model, ...] | None:
+        """
+        Load or reuse a bounded model-row snapshot for trusted hydration.
+        """
+        context = current_calculation_run_context()
+        if context is None:
+            return None
+        signature = self._query_signature()
+        if signature is None:
+            return None
+        cached = context.get_orm_bucket_rows(signature)
+        if cached is not None:
+            return cached  # type: ignore[return-value]
+
+        rows = tuple(self._data[: MAX_RUN_SCOPED_BUCKET_RESULT_ROWS + 1])
+        if len(rows) > MAX_RUN_SCOPED_BUCKET_RESULT_ROWS:
+            return None
+        primary_keys = tuple(row.pk for row in rows)
+        context.set_orm_bucket_rows(signature, rows)
+        context.set_orm_bucket_result(signature, primary_keys)
+        return rows
+
     def _peek_run_scoped_primary_keys(self) -> tuple[Any, ...] | None:
         """
         Return an already cached primary-key snapshot without evaluating the ORM.
@@ -393,6 +453,19 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             return None
         return cached  # type: ignore[return-value]
 
+    def _peek_run_scoped_rows(self) -> tuple[models.Model, ...] | None:
+        """Return cached model rows without evaluating the ORM."""
+        context = current_calculation_run_context()
+        if context is None:
+            return None
+        signature = self._query_signature()
+        if signature is None:
+            return None
+        cached = context.get_orm_bucket_rows(signature)
+        if cached is None:
+            return None
+        return cached  # type: ignore[return-value]
+
     @staticmethod
     def _snapshot_get_primary_key(kwargs: dict[str, Any]) -> Any | None:
         """
@@ -458,13 +531,18 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             GeneralManagerType: Manager instance for each primary key in the queryset.
         """
         self._track_effective_dependencies()
-        primary_keys = self._get_run_scoped_primary_keys()
+        rows = self._get_run_scoped_rows()
+        if rows is not None:
+            for row in rows:
+                yield self._build_manager_from_instance(row)
+            return
+        primary_keys = self._peek_run_scoped_primary_keys()
         if primary_keys is not None:
             for primary_key in primary_keys:
-                yield self._build_manager(primary_key)
+                yield self._build_manager_from_primary_key(primary_key)
             return
         for item in self._data:
-            yield self._build_manager(item.pk)
+            yield self._build_manager_from_instance(item)
 
     def __or__(
         self,
@@ -585,7 +663,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         """
         ids: list[int] = []
         for obj in query_set:
-            inst = self._build_manager(obj.pk)
+            inst = self._build_manager_from_instance(obj)
             keep = True
             for k, val, root in python_filters:
                 lookup = k.split("__", 1)[1] if "__" in k else ""
@@ -704,15 +782,20 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             GeneralManagerType | None: First manager instance if available.
         """
         self._track_effective_dependencies()
+        rows = self._peek_run_scoped_rows()
+        if rows is not None:
+            if not rows:
+                return None
+            return self._build_manager_from_instance(rows[0])
         primary_keys = self._peek_run_scoped_primary_keys()
         if primary_keys is not None:
             if not primary_keys:
                 return None
-            return self._build_manager(primary_keys[0])
+            return self._build_manager_from_primary_key(primary_keys[0])
         first_element = self._data.first()
         if first_element is None:
             return None
-        return self._build_manager(first_element.pk)
+        return self._build_manager_from_instance(first_element)
 
     def last(self) -> GeneralManagerType | None:
         """
@@ -722,15 +805,20 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             GeneralManagerType | None: Last manager instance if available.
         """
         self._track_effective_dependencies()
+        rows = self._peek_run_scoped_rows()
+        if rows is not None:
+            if not rows:
+                return None
+            return self._build_manager_from_instance(rows[-1])
         primary_keys = self._peek_run_scoped_primary_keys()
         if primary_keys is not None:
             if not primary_keys:
                 return None
-            return self._build_manager(primary_keys[-1])
+            return self._build_manager_from_primary_key(primary_keys[-1])
         first_element = self._data.last()
         if first_element is None:
             return None
-        return self._build_manager(first_element.pk)
+        return self._build_manager_from_instance(first_element)
 
     def count(self) -> int:
         """
@@ -778,18 +866,28 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             models.MultipleObjectsReturned: Propagated when multiple rows satisfy the lookup.
         """
         self._track_effective_dependencies()
+        rows = self._peek_run_scoped_rows()
+        if rows is not None:
+            requested_primary_key = self._snapshot_get_primary_key(kwargs)
+            if requested_primary_key is not None:
+                matches = [row for row in rows if row.pk == requested_primary_key]
+                if len(matches) == 1:
+                    return self._build_manager_from_instance(matches[0])
+                if len(matches) > 1:
+                    raise self._data.model.MultipleObjectsReturned
+                raise self._data.model.DoesNotExist
         primary_keys = self._peek_run_scoped_primary_keys()
         if primary_keys is not None:
             requested_primary_key = self._snapshot_get_primary_key(kwargs)
             if requested_primary_key is not None:
                 match_count = primary_keys.count(requested_primary_key)
                 if match_count == 1:
-                    return self._build_manager(requested_primary_key)
+                    return self._build_manager_from_primary_key(requested_primary_key)
                 if match_count > 1:
                     raise self._data.model.MultipleObjectsReturned
                 raise self._data.model.DoesNotExist
         element = self._data.get(**kwargs)
-        return self._build_manager(element.pk)
+        return self._build_manager_from_instance(element)
 
     def __getitem__(
         self, item: int | slice
@@ -815,12 +913,17 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
                 run_scoped_cacheable=self._run_scoped_cacheable,
             )
         self._track_effective_dependencies()
+        rows = self._peek_run_scoped_rows()
+        if rows is not None:
+            if item < 0:
+                raise ValueError
+            return self._build_manager_from_instance(rows[item])
         primary_keys = self._peek_run_scoped_primary_keys()
         if primary_keys is not None:
             if item < 0:
                 raise ValueError
-            return self._build_manager(primary_keys[item])
-        return self._build_manager(self._data[item].pk)
+            return self._build_manager_from_primary_key(primary_keys[item])
+        return self._build_manager_from_instance(self._data[item])
 
     def __len__(self) -> int:
         """
@@ -926,7 +1029,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             objs = list(qs)
 
             def key_func(obj: models.Model) -> tuple[object, ...]:
-                inst = self._build_manager(obj.pk)
+                inst = self._build_manager_from_instance(obj)
                 values = []
                 for k in key:
                     if k in properties:

{generalmanager-0.52.2 → generalmanager-0.53.0}/src/general_manager/cache/run_context.py

@@ -26,6 +26,7 @@ _active_context: ContextVar["CalculationRunContext | None"] = ContextVar(
     default=None,
 )
 ORM_BUCKET_RESULT_PREFIX = "orm_bucket_result"
+ORM_BUCKET_ROW_RESULT_PREFIX = "orm_bucket_row_result"
 BUCKET_INDEX_PREFIX = "bucket_index"
 DEFAULT_DEPENDENCY_CACHE_PUBLISH_BATCH_SIZE = 1000
 logger = get_logger("cache.run_context")
@@ -191,9 +192,18 @@ class CalculationRunContext:
         """Store an ORM bucket result for the active run."""
         self.set((ORM_BUCKET_RESULT_PREFIX, key), value)
 
+    def get_orm_bucket_rows(self, key: Hashable) -> object:
+        """Return cached ORM bucket rows for key, or None when absent."""
+        return self.get((ORM_BUCKET_ROW_RESULT_PREFIX, key))
+
+    def set_orm_bucket_rows(self, key: Hashable, value: object) -> None:
+        """Store ORM bucket rows for the active run."""
+        self.set((ORM_BUCKET_ROW_RESULT_PREFIX, key), value)
+
     def clear_orm_bucket_results(self) -> None:
         """Discard all run-scoped ORM bucket result entries."""
         self.discard_prefix((ORM_BUCKET_RESULT_PREFIX,))
+        self.discard_prefix((ORM_BUCKET_ROW_RESULT_PREFIX,))
 
     def _bucket_index_cache_key(
         self,

{generalmanager-0.52.2 → generalmanager-0.53.0}/src/general_manager/interface/orm_interface.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import ClassVar, Generic, Type, TypeVar, cast
+from typing import Any, ClassVar, Generic, Type, TypeVar, cast
 
 from django.db import models
 from django.utils import timezone
@@ -60,6 +60,34 @@ class OrmInterfaceBase(InterfaceBase, Generic[HistoryModelT]):
         self._search_date = self.normalize_search_date(search_date)
         self._instance: HistoryModelT = self.get_data()
 
+    @classmethod
+    def _from_trusted_orm_instance(
+        cls,
+        instance: HistoryModelT,
+        *,
+        search_date: datetime | None = None,
+    ) -> "OrmInterfaceBase[HistoryModelT]":
+        """
+        Build an interface from an ORM-loaded row without public input validation.
+
+        This is an internal trusted path. Callers must only pass model or
+        historical rows that came from Django ORM querysets owned by this
+        interface. External/API/user payloads must continue through __init__.
+        """
+        pk = cast(Any, instance).pk
+        if cls.__init__ is not OrmInterfaceBase.__init__:
+            if search_date is None:
+                return cls(pk)
+            return cls(pk, search_date=search_date)
+
+        interface = cls.__new__(cls)
+        identification = {"id": pk}
+        interface.identification = identification
+        interface.pk = pk
+        interface._search_date = cls.normalize_search_date(search_date)
+        interface._instance = instance
+        return interface
+
     @staticmethod
     def normalize_search_date(search_date: datetime | None) -> datetime | None:
         """

{generalmanager-0.52.2 → generalmanager-0.53.0}/src/general_manager/manager/general_manager.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 from collections.abc import Mapping
-from typing import TYPE_CHECKING, Any, Iterator, Self, Type
+from typing import TYPE_CHECKING, Any, Iterator, Self, Type, cast
 
 from general_manager.api.property import GraphQLProperty
 from general_manager.bucket.base_bucket import Bucket
@@ -24,6 +24,13 @@ class UnsupportedUnionOperandError(TypeError):
         super().__init__(f"Unsupported type for union: {operand_type}.")
 
 
+class TrustedOrmHydrationNotSupportedError(TypeError):
+    """Raised when trusted ORM hydration is requested for a non-ORM interface."""
+
+    def __init__(self, interface_name: str) -> None:
+        super().__init__(f"{interface_name} does not support trusted ORM hydration.")
+
+
 if TYPE_CHECKING:
     from general_manager.permission.base_permission import BasePermission
     from general_manager.interface.base_interface import InterfaceBase
@@ -65,6 +72,49 @@ class GeneralManager(metaclass=GeneralManagerMeta):
             },
         )
 
+    @classmethod
+    def _from_trusted_orm_instance(
+        cls,
+        instance: Any,
+        *,
+        search_date: Any = None,
+    ) -> Self:
+        """
+        Build a manager around an ORM-loaded row without public input validation.
+
+        This private path is only for framework-owned Django ORM rows. It must
+        not be used for GraphQL, mutation, import, factory, or other external
+        payloads because it bypasses Interface input validation.
+        """
+        hydrate = getattr(cls.Interface, "_from_trusted_orm_instance", None)
+        if not callable(hydrate):
+            raise TrustedOrmHydrationNotSupportedError(cls.Interface.__name__)
+
+        if cls.__init__ is not GeneralManager.__init__:
+            pk = instance.pk
+            if search_date is None:
+                return cls(pk)
+            return cls(pk, search_date=search_date)
+
+        manager = cls.__new__(cls)
+        manager._interface = hydrate(instance, search_date=search_date)
+        manager.__id = manager._interface.identification
+        manager._manager_state_valid = True
+        manager._manager_state_reason = None
+        DependencyTracker.track(
+            cls.__name__,
+            "identification",
+            serialize_dependency_identifier(manager.__id),
+        )
+        logger.debug(
+            "trusted orm manager hydrated",
+            context={
+                "manager": cls.__name__,
+                "identification": manager.__id,
+            },
+        )
+        return cast(Self, manager)
+
     def __str__(self) -> str:
         """Return a user-friendly representation showing the identification."""
         return f"{self.__class__.__name__}(**{self.__id})"