GeneralManager 0.87.2__tar.gz → 0.87.3__tar.gz

{generalmanager-0.87.2/src/GeneralManager.egg-info → generalmanager-0.87.3}/PKG-INFO

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

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

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

@@ -216,6 +216,7 @@ src/general_manager/interface/capabilities/orm/_compat.py
 src/general_manager/interface/capabilities/orm/bulk.py
 src/general_manager/interface/capabilities/orm/create_many.py
 src/general_manager/interface/capabilities/orm/history.py
+src/general_manager/interface/capabilities/orm/history_query.py
 src/general_manager/interface/capabilities/orm/lifecycle.py
 src/general_manager/interface/capabilities/orm/mutations.py
 src/general_manager/interface/capabilities/orm/support.py

{generalmanager-0.87.2 → generalmanager-0.87.3}/src/general_manager/api/property.py

@@ -11,6 +11,12 @@ from functools import wraps
 import sys
 from typing import Callable, Literal, TypeVar, cast, get_type_hints, overload
 
+from general_manager.as_of import (
+    _bind_property_result,
+    _ensure_property_supported,
+    _property_as_of,
+)
+
 T = TypeVar("T", bound=Callable[..., object])
 GraphQLPropertyCache = Literal["dependency", "run", "timeout", "none"]
 _TYPE_HINT_UNRESOLVED = object()
@@ -148,15 +154,12 @@ class GraphQLProperty(property):
         @wraps(fget)
         def resolver(instance: object) -> object:
             """Resolve the property through the selected cached wrapper."""
-            ensure_as_of_compatible = getattr(
-                instance, "_ensure_as_of_compatible", None
-            )
-            if callable(ensure_as_of_compatible):
-                ensure_as_of_compatible()
-            cached_fget = self._cached_fget
-            if cached_fget is None:
-                cached_fget = self._get_cached_fget()
-            return cached_fget(instance)
+            with _property_as_of(instance) as snapshot:
+                _ensure_property_supported(self._raw_fget, snapshot)
+                cached_fget = self._cached_fget
+                if cached_fget is None:
+                    cached_fget = self._get_cached_fget()
+                return _bind_property_result(cached_fget(instance), snapshot)
 
         super().__init__(resolver, doc=doc)
         self.is_graphql_resolver = True

{generalmanager-0.87.2 → generalmanager-0.87.3}/src/general_manager/as_of.py

@@ -2,10 +2,18 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterator
+from collections.abc import (
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Iterator,
+    Mapping,
+)
 from contextlib import contextmanager
 from contextvars import ContextVar
 from datetime import UTC, date, datetime, time
+from inspect import isasyncgenfunction, isawaitable, isgeneratorfunction, unwrap
+from typing import cast
 
 from django.utils import timezone
 
@@ -94,11 +102,16 @@ def as_of_cache_fingerprint() -> str | None:
     return None if active is None else search_date_cache_fingerprint(active)
 
 
-def reject_historical_mutation() -> None:
-    """Reject mutations while an operation-scoped historical date is active."""
+def reject_historical_mutation(bound: object | None = None) -> None:
+    """Reject mutations in a historical operation or through a dated object."""
     active = current_as_of_date()
     if active is not None:
         raise HistoricalMutationError(active)
+    state = getattr(bound, "__dict__", None)
+    if isinstance(state, Mapping):
+        snapshot = state.get("_effective_search_date", state.get("_search_date"))
+        if isinstance(snapshot, datetime):
+            raise HistoricalMutationError(snapshot)
 
 
 def ensure_as_of_read_supported(interface_cls: type[object]) -> None:
@@ -128,6 +141,50 @@ def resolve_search_date(explicit: SearchDateInput | None) -> datetime | None:
     return normalized
 
 
+@contextmanager
+def _property_as_of(instance: object) -> Iterator[datetime | None]:
+    """Evaluate a manager property and its cache under the bound snapshot."""
+    ensure = getattr(instance, "_ensure_as_of_compatible", None)
+    if callable(ensure):
+        ensure()
+    state = getattr(instance, "__dict__", {})
+    snapshot = state.get("_effective_search_date")
+    if isinstance(snapshot, datetime):
+        with as_of(snapshot):
+            yield snapshot
+    else:
+        yield current_as_of_date()
+
+
+def _bind_property_result(value: object, snapshot: datetime | None) -> object:
+    """Bind awaitables and reject iterator bodies that can escape the scope."""
+    if snapshot is None:
+        return value
+    if isinstance(value, (Iterator, AsyncIterator)):
+        close = getattr(value, "close", None)
+        if callable(close):
+            close()
+        raise HistoricalReadNotSupportedError()
+    if isawaitable(value):
+        return _await_as_of(cast(Awaitable[object], value), snapshot)
+    return value
+
+
+def _ensure_property_supported(
+    getter: Callable[..., object], snapshot: datetime | None
+) -> None:
+    """Reject generator properties before constructing deferred bodies."""
+    if snapshot is not None and (
+        isgeneratorfunction(unwrap(getter)) or isasyncgenfunction(unwrap(getter))
+    ):
+        raise HistoricalReadNotSupportedError()
+
+
+async def _await_as_of(value: Awaitable[object], snapshot: datetime) -> object:
+    with as_of(snapshot):
+        return _bind_property_result(await value, snapshot)
+
+
 @contextmanager
 def as_of(search_date: SearchDateInput) -> Iterator[datetime]:
     """Run an operation with a normalized historical date."""

{generalmanager-0.87.2 → generalmanager-0.87.3}/src/general_manager/cache/signals.py

@@ -119,7 +119,7 @@ def data_change(
         Returns:
             R: The result returned by the wrapped function.
         """
-        reject_historical_mutation()
+        reject_historical_mutation(args[0] if args else None)
 
         from general_manager.cache.dependency_index import (
             begin_dependency_data_change,

{generalmanager-0.87.2 → generalmanager-0.87.3}/src/general_manager/interface/base_interface.py

@@ -105,7 +105,8 @@ def _guard_mutation_callable(
 
         @wraps(mutation)
         async def async_guarded(*args: object, **kwargs: object) -> object:
-            reject_historical_mutation()
+            """Reject historical writes before invoking the async mutation."""
+            reject_historical_mutation(args[0] if args else None)
             awaitable = cast(Awaitable[object], mutation(*args, **kwargs))
             return await awaitable
 
@@ -114,7 +115,8 @@ def _guard_mutation_callable(
 
     @wraps(mutation)
     def sync_guarded(*args: object, **kwargs: object) -> object:
-        reject_historical_mutation()
+        """Reject historical writes before invoking the synchronous mutation."""
+        reject_historical_mutation(args[0] if args else None)
         return mutation(*args, **kwargs)
 
     setattr(sync_guarded, _HISTORICAL_MUTATION_GUARD_MARKER, True)
@@ -1266,7 +1268,7 @@ class InterfaceBase(ABC):
         Raises:
             NotImplementedError: If this interface does not provide an update capability.
         """
-        reject_historical_mutation()
+        reject_historical_mutation(self)
         observer = self.get_capability_handler("observability")
 
         def _invoke() -> object:
@@ -1311,7 +1313,7 @@ class InterfaceBase(ABC):
         Raises:
             NotImplementedError: If the interface does not provide a delete capability.
         """
-        reject_historical_mutation()
+        reject_historical_mutation(self)
         observer = self.get_capability_handler("observability")
 
         def _invoke() -> object:

{generalmanager-0.87.2 → generalmanager-0.87.3}/src/general_manager/interface/capabilities/orm/history.py

@@ -16,9 +16,11 @@ from general_manager.interface.utils.database_interface_protocols import (
 )
 
 from .support import get_support_capability
+from .history_query import ManagerHistoryQuery
 
 if TYPE_CHECKING:  # pragma: no cover
     from general_manager.interface.orm_interface import OrmInterfaceBase
+    from general_manager.manager.general_manager import GeneralManager
 
 
 class HistoryNotSupportedError(RuntimeError):
@@ -175,6 +177,8 @@ class OrmHistoryCapability(BaseCapability):
         pk_filter: dict[str, object] | None
         if isinstance(instance, SupportsHistory):
             history_manager = instance.history
+            if isinstance(history_manager, ManagerHistoryQuery):
+                history_manager = cast(SupportsHistoryQuery, history_manager.raw)
             pk_filter = self._get_instance_pk_filter(instance)
         else:
             pk_filter = self._get_model_pk_filter(interface_cls, instance)
@@ -198,36 +202,52 @@ class OrmHistoryCapability(BaseCapability):
         self,
         interface_cls: type["OrmInterfaceBase[models.Model]"],
         manager: object,
-    ) -> models.QuerySet[models.Model]:
+    ) -> ManagerHistoryQuery[GeneralManager]:
         """
-        Return the history queryset scoped to the manager instance's primary key.
+        Return manager-valued history scoped to the original object's key.
 
-        The target identifier is derived from ``manager.pk``, then
-        ``manager.id``, then mapping-like ``manager.identification["id"]``. The
+        The target identifier prefers mapping-like ``manager.identification["id"]``,
+        then falls back to ``manager.pk`` or ``manager.id``. The
         lookup key defaults to ``"id"`` and uses the interface model primary-key
         field name when it is available as a string. A configured database alias
-        is applied before the filtered queryset is returned.
+        is applied before the query is wrapped. Object results are the original
+        manager class at a fixed snapshot; ``.raw`` retains audit rows.
 
         Parameters:
             interface_cls: ORM interface whose underlying model provides the history manager.
             manager: Manager-like object exposing ``pk``, ``id``, or ``identification["id"]`` for the target row.
 
         Returns:
-            History queryset limited to records for the target object.
+            Manager-valued history with raw audit access for the target object.
 
         Raises:
             HistoryNotSupportedError: If the interface does not expose a history manager or the manager cannot be scoped to a primary key.
         """
         if not hasattr(interface_cls._model, "history"):
             raise HistoryNotSupportedError(interface_cls.__name__)
-        pk_filter = self._get_model_pk_filter(interface_cls, manager)
+        from general_manager.manager.general_manager import GeneralManager
+
+        identification = getattr(manager, "identification", None)
+        pk_filter: dict[str, object] | None
+        if isinstance(identification, Mapping) and identification.get("id") is not None:
+            pk_field = interface_cls._model._meta.pk
+            pk_filter = {pk_field.name if pk_field else "id": identification["id"]}
+        else:
+            pk_filter = self._get_model_pk_filter(interface_cls, manager)
         if pk_filter is None:
             raise HistoryNotSupportedError(interface_cls.__name__)
         history_manager = cast(SupportsHistory, interface_cls._model).history
         history_manager = self._apply_database_alias(interface_cls, history_manager)
-        return cast(
-            models.QuerySet[models.Model],
-            history_manager.filter(**pk_filter),
+        manager_class = (
+            type(manager)
+            if isinstance(manager, GeneralManager)
+            else interface_cls._parent_class
+        )
+        snapshot = getattr(manager, "_effective_search_date", None)
+        return ManagerHistoryQuery(
+            cast(models.QuerySet[models.Model], history_manager.filter(**pk_filter)),
+            manager_class,
+            search_date=snapshot if isinstance(snapshot, datetime) else None,
         )
 
     def get_historical_queryset(

generalmanager-0.87.3/src/general_manager/interface/capabilities/orm/history_query.py

@@ -0,0 +1,178 @@
+"""Manager-valued selection over an object's raw audit history."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast, overload
+
+from django.db import models
+from django.utils import timezone
+
+from general_manager.as_of import (
+    HistoricalContextConflictError,
+    as_of,
+    resolve_search_date,
+)
+
+if TYPE_CHECKING:
+    from general_manager.manager.general_manager import GeneralManager
+
+ManagerT = TypeVar("ManagerT", bound="GeneralManager")
+
+
+class ManagerHistoryQuery(Generic[ManagerT]):
+    """Select original managers while retaining explicit raw audit access.
+
+    Query shaping and scalar projections use Django's history queryset. Object
+    selection binds each version to its closing snapshot, or to the exact
+    explicit/ambient date. ``raw`` is the unchanged audit queryset, including
+    tombstones and zero-duration versions, and is intentionally not a dated
+    entity read. Less common Django audit operations belong on that queryset.
+    """
+
+    def __init__(
+        self,
+        raw: models.QuerySet[models.Model],
+        manager_class: type[ManagerT],
+        *,
+        search_date: datetime | None = None,
+        timeline: models.QuerySet[models.Model] | None = None,
+    ) -> None:
+        """Capture the query's date and keep its unfiltered entity timeline."""
+        self.raw = raw
+        self._manager_class = manager_class
+        self._search_date = resolve_search_date(search_date)
+        self._timeline = raw if timeline is None else timeline
+
+    def _clone(
+        self, raw: models.QuerySet[models.Model]
+    ) -> ManagerHistoryQuery[ManagerT]:
+        return type(self)(
+            raw,
+            self._manager_class,
+            search_date=self._search_date,
+            timeline=self._timeline,
+        )
+
+    def _dated_query(self) -> models.QuerySet[models.Model]:
+        """Limit candidate audit rows to the resolved explicit or ambient date."""
+        snapshot = resolve_search_date(self._search_date)
+        if snapshot is None:
+            return self.raw
+        return self.raw.filter(history_date__lte=snapshot)
+
+    def _materialize(self, row: models.Model) -> ManagerT:
+        """Resolve a real version interval and construct under its snapshot.
+
+        Tombstones are audit-only. A datetime cannot select a zero-duration
+        interval, and an explicit date must fall inside the selected version.
+        """
+        audit = cast(Any, row)
+        model = cast(Any, self._manager_class.Interface)._model
+        if audit.history_type == "-":
+            raise model.DoesNotExist
+        successor = (
+            self._timeline.filter(
+                models.Q(history_date__gt=audit.history_date)
+                | models.Q(
+                    history_date=audit.history_date, history_id__gt=audit.history_id
+                )
+            )
+            .order_by("history_date", "history_id")
+            .first()
+        )
+        start = cast(datetime, audit.history_date).astimezone(UTC)
+        end = (
+            cast(datetime, cast(Any, successor).history_date).astimezone(UTC)
+            if successor is not None
+            else None
+        )
+        snapshot = resolve_search_date(self._search_date)
+        if snapshot is None:
+            snapshot = (
+                end - timedelta(microseconds=1) if end is not None else timezone.now()
+            )
+        instant = snapshot.astimezone(UTC)
+        if instant < start or (end is not None and instant >= end):
+            raise HistoricalContextConflictError
+        # A historical row's pk is its history_id, not the original entity id.
+        original_pk = getattr(row, model._meta.pk.attname)
+        with as_of(snapshot):
+            return self._manager_class(original_pk)
+
+    def all(self) -> ManagerHistoryQuery[ManagerT]:
+        return self._clone(self.raw.all())
+
+    def filter(self, *args: Any, **kwargs: Any) -> ManagerHistoryQuery[ManagerT]:
+        return self._clone(self.raw.filter(*args, **kwargs))
+
+    def exclude(self, *args: Any, **kwargs: Any) -> ManagerHistoryQuery[ManagerT]:
+        return self._clone(self.raw.exclude(*args, **kwargs))
+
+    def order_by(self, *fields: str) -> ManagerHistoryQuery[ManagerT]:
+        return self._clone(self.raw.order_by(*fields))
+
+    def reverse(self) -> ManagerHistoryQuery[ManagerT]:
+        return self._clone(self.raw.reverse())
+
+    def first(self) -> ManagerT | None:
+        """Return the first selected version as a manager, or None."""
+        row = self._dated_query().first()
+        return None if row is None else self._materialize(row)
+
+    def last(self) -> ManagerT | None:
+        """Return the last selected version as a manager, or None."""
+        row = self._dated_query().last()
+        return None if row is None else self._materialize(row)
+
+    def get(self, *args: Any, **kwargs: Any) -> ManagerT:
+        return self._materialize(self._dated_query().get(*args, **kwargs))
+
+    def latest(self, *fields: str) -> ManagerT:
+        return self._materialize(self._dated_query().latest(*fields))
+
+    def earliest(self, *fields: str) -> ManagerT:
+        return self._materialize(self._dated_query().earliest(*fields))
+
+    def count(self) -> int:
+        return self._dated_query().count()
+
+    def exists(self) -> bool:
+        return self._dated_query().exists()
+
+    def values(self, *fields: str, **expressions: Any) -> models.QuerySet[Any]:
+        return cast(
+            models.QuerySet[Any], self._dated_query().values(*fields, **expressions)
+        )
+
+    def values_list(self, *fields: str, **kwargs: Any) -> models.QuerySet[Any]:
+        return cast(
+            models.QuerySet[Any], self._dated_query().values_list(*fields, **kwargs)
+        )
+
+    def __iter__(self) -> Iterator[ManagerT]:
+        """Materialize each selected audit version with its effective snapshot."""
+        for row in self._dated_query():
+            yield self._materialize(row)
+
+    def __len__(self) -> int:
+        return self.count()
+
+    def __bool__(self) -> bool:
+        return self.exists()
+
+    @overload
+    def __getitem__(self, key: int) -> ManagerT: ...
+
+    @overload
+    def __getitem__(self, key: slice) -> list[ManagerT]: ...
+
+    def __getitem__(self, key: int | slice) -> ManagerT | list[ManagerT]:
+        """Materialize an indexed version or an eager list for a slice."""
+        if isinstance(key, int):
+            return self._materialize(self._dated_query()[key])
+        return [self._materialize(row) for row in self._dated_query()[key]]
+
+    def __repr__(self) -> str:
+        return f"ManagerHistoryQuery({self._manager_class.__name__})"

{generalmanager-0.87.2 → generalmanager-0.87.3}/src/general_manager/interface/capabilities/orm/support.py

@@ -330,6 +330,7 @@ class OrmReadCapability(BaseCapability):
         _ensure_ambient_history_supported(interface_cls, search_date)
 
         def _perform() -> models.Model:
+            """Load live or dated detail, rejecting absent and deleted versions."""
             model_cls = interface_cls._model
             support = get_support_capability(interface_cls)
             only_active = not is_soft_delete_enabled(interface_cls)
@@ -387,6 +388,8 @@ class OrmReadCapability(BaseCapability):
                         ) from error
                     raise
                 if historical is not None:
+                    if getattr(historical, "history_type", None) == "-":
+                        raise model_cls.DoesNotExist
                     return historical
                 if missing_error is not None:
                     raise missing_error

{generalmanager-0.87.2 → generalmanager-0.87.3}/src/general_manager/interface/capabilities/orm_utils/field_descriptors.py

@@ -337,6 +337,11 @@ class _FieldDescriptorBuilder:
                         if target_field is not None and target_field.primary_key
                         else None
                     ),
+                    historical_lookup=(
+                        (target_field.name, raw_id_name)
+                        if target_field is not None and not target_field.primary_key
+                        else None
+                    ),
                 )
                 relation_type = cast(type[object], general_manager_class)
             else:
@@ -389,7 +394,12 @@ class _FieldDescriptorBuilder:
             )
             if general_manager_class:
                 accessor = _general_manager_accessor(
-                    accessor_name, general_manager_class
+                    accessor_name,
+                    general_manager_class,
+                    historical_lookup=(
+                        relation.field.attname,
+                        relation.field.target_field.attname,
+                    ),
                 )
                 relation_type = cast(type[object], general_manager_class)
             else:
@@ -853,6 +863,7 @@ def _general_manager_accessor(
     manager_class: type[object],
     *,
     raw_id_name: str | None = None,
+    historical_lookup: tuple[str, str] | None = None,
 ) -> DescriptorAccessor:
     """
     Create an accessor that resolves a related object's manager from an interface.
@@ -867,6 +878,8 @@ def _general_manager_accessor(
         field_name (str): Name of the attribute on the underlying model that holds the related object.
         manager_class (type): Class used to hydrate or construct the related manager.
         raw_id_name (str | None): Optional raw foreign-key attribute name used to avoid loading the relation.
+        historical_lookup: Target filter lookup and source attribute used to
+            resolve dated relations without consulting live Django relations.
 
     Returns:
         DescriptorAccessor: A callable that, given a OrmInterfaceBase, returns the manager instance for the related object, or `None` if the related attribute is `None`.
@@ -923,8 +936,16 @@ def _general_manager_accessor(
         Returns:
             The related manager instance, or `None` if the related object is `None`.
         """
+        search_date = getattr(self, "_search_date", None)
+        if search_date is not None and historical_lookup is not None:
+            lookup_name, source_attribute = historical_lookup
+            source_value = getattr(self._instance, source_attribute)
+            if source_value is None:
+                return None
+            return manager_type.filter(
+                **{lookup_name: source_value}, search_date=search_date
+            ).first()
         if raw_id_name is not None:
-            search_date = getattr(self, "_search_date", None)
             raw_id = getattr(self._instance, raw_id_name, None)
             if raw_id is None:
                 return None
@@ -949,7 +970,6 @@ def _general_manager_accessor(
             return None
         if related is None:
             return None
-        search_date = getattr(self, "_search_date", None)
         if search_date is not None:
             return manager_type(related.pk, search_date=search_date)
         trusted_hydrate = getattr(manager_type, "_from_trusted_orm_instance", None)

{generalmanager-0.87.2 → generalmanager-0.87.3}/src/general_manager/manager/general_manager.py

@@ -450,7 +450,7 @@ class GeneralManager(metaclass=GeneralManagerMeta):
 
     @property
     def history(self) -> object:
-        """Return the history queryset scoped to this manager instance."""
+        """Return scoped history; ORM results are managers with ``.raw`` audit access."""
         from general_manager.interface.capabilities.orm import HistoryNotSupportedError
 
         history_handler = self.Interface.get_capability_handler("history")
@@ -565,11 +565,16 @@ class GeneralManager(metaclass=GeneralManagerMeta):
                 yield key, value(self._interface)
                 continue
             yield key, value
+        inherited_aliases = vars(self.__class__).get(
+            "_gm_inherited_property_aliases", {}
+        )
         for name, value in self.__class__.__dict__.items():
             if name == "history":
                 continue
             if getattr(value, "_general_manager_generated_relation", False):
                 continue
+            if inherited_aliases.get(name, _EFFECTIVE_SEARCH_DATE_MISSING) is value:
+                continue
             if isinstance(value, (GraphQLProperty, property)):
                 yield name, getattr(self, name)
 
@@ -664,7 +669,7 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         Raises:
             PermissionError: If the permission check fails when `ignore_permission` is False.
         """
-        reject_historical_mutation()
+        reject_historical_mutation(self)
         self._ensure_manager_not_invalidated()
         if not ignore_permission:
             self.Permission.check_update_permission(kwargs, self, creator_id)
@@ -710,7 +715,7 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         Raises:
             PermissionError: If permission validation fails.
         """
-        reject_historical_mutation()
+        reject_historical_mutation(self)
         self._ensure_manager_not_invalidated()
         if not ignore_permission:
             self.Permission.check_delete_permission(self, creator_id)