GeneralManager 0.68.2__tar.gz → 0.69.0__tar.gz

{generalmanager-0.68.2/src/GeneralManager.egg-info → generalmanager-0.69.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.68.2
+Version: 0.69.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.68.2 → generalmanager-0.69.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.68.2
+Version: 0.69.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.68.2 → generalmanager-0.69.0}/src/general_manager/api/graphql.py

@@ -6,6 +6,7 @@ import asyncio
 from contextlib import asynccontextmanager
 from copy import deepcopy
 import re
+from time import perf_counter
 from types import UnionType
 from typing import (
     AsyncIterator,
@@ -37,6 +38,7 @@ from general_manager.bucket.group_bucket import GroupBucket
 from general_manager.cache.dependency_index import (
     Dependency,
 )
+from general_manager.cache.data_change_context import record_data_change_phase
 from general_manager.cache.signals import post_data_change
 from general_manager.conf import get_setting
 from general_manager.interface.base_interface import InterfaceBase
@@ -1784,38 +1786,44 @@ class GraphQL:
             instance (GeneralManager | None): The GeneralManager instance that changed.
             action (str): A string describing the change action (e.g., "created", "updated", "deleted").
         """
-        event_instance = instance if instance is not None else previous_instance
-        if event_instance is None or not isinstance(event_instance, GeneralManager):
-            return
+        started = perf_counter()
+        try:
+            event_instance = instance if instance is not None else previous_instance
+            if event_instance is None or not isinstance(event_instance, GeneralManager):
+                return
 
-        if isinstance(sender, type) and issubclass(sender, GeneralManager):
-            manager_class: type[GeneralManager] = sender
-        else:
-            manager_class = event_instance.__class__
+            if isinstance(sender, type) and issubclass(sender, GeneralManager):
+                manager_class: type[GeneralManager] = sender
+            else:
+                manager_class = event_instance.__class__
 
-        if manager_class.__name__ not in cls.manager_registry:
-            logger.debug(
-                "skipping subscription event for unregistered manager",
-                context={
-                    "manager": manager_class.__name__,
-                    "action": action,
-                },
-            )
-            return
+            if manager_class.__name__ not in cls.manager_registry:
+                logger.debug(
+                    "skipping subscription event for unregistered manager",
+                    context={
+                        "manager": manager_class.__name__,
+                        "action": action,
+                    },
+                )
+                return
 
-        event_identification = deepcopy(
-            identification
-            if identification is not None
-            else event_instance.identification
-        )
-        transaction.on_commit(
-            lambda: cls._publish_data_change(
-                manager_class,
-                action,
-                event_identification,
-            ),
-            using=database_alias,
-        )
+            event_identification = deepcopy(
+                identification
+                if identification is not None
+                else event_instance.identification
+            )
+            transaction.on_commit(
+                lambda: cls._publish_data_change(
+                    manager_class,
+                    action,
+                    event_identification,
+                ),
+                using=database_alias,
+            )
+        finally:
+            record_data_change_phase(
+                "subscription", perf_counter() - started, database_alias
+            )
 
     @classmethod
     def _publish_data_change(

{generalmanager-0.68.2 → generalmanager-0.69.0}/src/general_manager/api/graphql_resolvers.py

@@ -499,6 +499,8 @@ def apply_pagination(
     Negative ``page`` or ``page_size`` values raise ``ValueError`` before
     slicing. Falsey explicit values such as ``page=0`` or ``page_size=0`` also
     fall back through those defaults for slicing.
+    Already-empty grouped buckets are returned unchanged when pagination is
+    requested, preserving their shape without invoking an invalid empty slice.
     The returned object keeps the same bucket/group-bucket shape as the slice
     operation exposes. Slice errors from the bucket implementation propagate
     unchanged.
@@ -508,6 +510,8 @@ def apply_pagination(
     if page_size is not None and page_size < 0:
         raise InvalidPaginationValueError
     if page is not None or page_size is not None:
+        if isinstance(queryset, GroupBucket) and len(queryset) == 0:
+            return queryset
         page = page or 1
         page_size = page_size or 10
         offset = (page - 1) * page_size

{generalmanager-0.68.2 → generalmanager-0.69.0}/src/general_manager/api/remote_invalidation.py

@@ -8,6 +8,7 @@ from datetime import date, datetime
 import json
 from importlib import import_module
 import re
+from time import perf_counter
 from uuid import UUID, uuid4
 from collections.abc import Callable, Coroutine, Mapping, MutableSequence, Sequence
 from types import ModuleType
@@ -25,6 +26,7 @@ from general_manager.api.remote_api import (
     get_remote_api_config,
 )
 from general_manager.api.notification_batching import _queue_notification
+from general_manager.cache.data_change_context import record_data_change_phase
 from general_manager.cache.signals import post_data_change
 from general_manager.logging import get_logger
 
@@ -200,24 +202,30 @@ def emit_remote_invalidation(
     originating database alias and delegates channel lookup, batching, payload
     creation, and delivery to `_publish_remote_invalidation` after commit.
     """
-    config = get_remote_api_config(sender)
-    if config is None or not config.websocket_invalidation:
-        return
+    started = perf_counter()
+    try:
+        config = get_remote_api_config(sender)
+        if config is None or not config.websocket_invalidation:
+            return
 
-    event_identification = identification
-    if event_identification is None and instance is not None:
-        event_identification = dict(instance.identification)
-    captured_identification = (
-        deepcopy(event_identification) if event_identification is not None else None
-    )
-    transaction.on_commit(
-        lambda: _publish_remote_invalidation(
-            config,
-            action,
-            captured_identification,
-        ),
-        using=database_alias,
-    )
+        event_identification = identification
+        if event_identification is None and instance is not None:
+            event_identification = dict(instance.identification)
+        captured_identification = (
+            deepcopy(event_identification) if event_identification is not None else None
+        )
+        transaction.on_commit(
+            lambda: _publish_remote_invalidation(
+                config,
+                action,
+                captured_identification,
+            ),
+            using=database_alias,
+        )
+    finally:
+        record_data_change_phase(
+            "subscription", perf_counter() - started, database_alias
+        )
 
 
 post_data_change.connect(emit_remote_invalidation, weak=False)

{generalmanager-0.68.2 → generalmanager-0.69.0}/src/general_manager/cache/data_change_context.py

@@ -5,17 +5,45 @@ from __future__ import annotations
 from collections.abc import Iterator
 from contextlib import contextmanager
 from contextvars import ContextVar
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from math import isfinite
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class DataChangeTransactionContext:
+    """Mutable state owned by one framework-managed data-change transaction."""
+
+    database_alias: str
+    caller_in_atomic_block: bool
+    changed_classes: set[str] = field(default_factory=set)
+    metadata: dict[str, object] = field(default_factory=dict)
+    phase_seconds: dict[str, float] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class DataChangeTransactionScope:
+    """Public view of a context-manager entry's transaction state."""
+
+    transaction: DataChangeTransactionContext
+    is_outermost: bool
 
 
 @dataclass
 class _DataChangeTransaction:
     """Live marker for one framework-owned transaction envelope."""
 
-    database_alias: str
-    caller_in_atomic_block: bool
+    context: DataChangeTransactionContext
     active: bool = True
 
+    @property
+    def database_alias(self) -> str:
+        return self.context.database_alias
+
+    @property
+    def caller_in_atomic_block(self) -> bool:
+        return self.context.caller_in_atomic_block
+
 
 _owned_transactions: ContextVar[tuple[_DataChangeTransaction, ...]] = ContextVar(
     "owned_data_change_transactions",
@@ -34,25 +62,68 @@ def _current_owner(database_alias: str) -> _DataChangeTransaction | None:
     return None
 
 
+def current_data_change_transaction(
+    database_alias: str,
+) -> DataChangeTransactionContext | None:
+    """Return the live framework-owned context for a database alias, if any."""
+    owner = _current_owner(database_alias)
+    return owner.context if owner is not None else None
+
+
 @contextmanager
 def own_data_change_transaction(
     database_alias: str,
     *,
     caller_in_atomic_block: bool,
-) -> Iterator[None]:
+) -> Iterator[DataChangeTransactionScope]:
     """Record a live framework envelope without inspecting Django internals."""
-    owner = _DataChangeTransaction(
+    existing_owner = _current_owner(database_alias)
+    if existing_owner is not None:
+        yield DataChangeTransactionScope(
+            transaction=existing_owner.context,
+            is_outermost=False,
+        )
+        return
+
+    context = DataChangeTransactionContext(
         database_alias=database_alias,
         caller_in_atomic_block=caller_in_atomic_block,
     )
+    owner = _DataChangeTransaction(
+        context=context,
+    )
     token = _owned_transactions.set((*_owned_transactions.get(), owner))
     try:
-        yield
+        yield DataChangeTransactionScope(transaction=context, is_outermost=True)
     finally:
         owner.active = False
         _owned_transactions.reset(token)
 
 
+def register_data_change_class(class_name: str, database_alias: str) -> bool:
+    """Record a changed class when the framework owns the live transaction."""
+    context = current_data_change_transaction(database_alias)
+    if context is None or context.caller_in_atomic_block:
+        return False
+    context.changed_classes.add(class_name)
+    return True
+
+
+def record_data_change_phase(
+    phase: Literal["database", "invalidation", "subscription", "search", "workflow"],
+    duration_seconds: float,
+    database_alias: str,
+) -> None:
+    """Accumulate a non-negative duration for a phase in the live context."""
+    if not isfinite(duration_seconds):
+        return
+    context = current_data_change_transaction(database_alias)
+    if context is not None:
+        context.phase_seconds[phase] = context.phase_seconds.get(phase, 0.0) + max(
+            duration_seconds, 0.0
+        )
+
+
 @contextmanager
 def authorize_data_change_operation(database_alias: str) -> Iterator[None]:
     """Authorize only the decorated manager method to reuse its envelope."""

{generalmanager-0.68.2 → generalmanager-0.69.0}/src/general_manager/cache/dependency_index.py

@@ -8,9 +8,11 @@ import time
 import uuid
 from contextvars import ContextVar
 from datetime import date, datetime
+from time import perf_counter
 from typing import TYPE_CHECKING, Callable, Iterable, Literal, Tuple, Type, cast
 
 from django.core.cache import cache
+from django.db import DEFAULT_DB_ALIAS
 from django.dispatch import receiver
 
 from general_manager.cache.dependency_matching import (
@@ -34,6 +36,7 @@ from general_manager.cache.dependency_shards import (
     reverse_memberships,
     tracked_lookup_names,
 )
+from general_manager.cache.data_change_context import record_data_change_phase
 from general_manager.cache.signals import post_data_change, pre_data_change
 from general_manager.logging import get_logger
 
@@ -1384,6 +1387,7 @@ def generic_cache_invalidation(
     sender: type[GeneralManager],
     instance: GeneralManager,
     old_relevant_values: dict[str, object],
+    database_alias: str = DEFAULT_DB_ALIAS,
     **kwargs: object,
 ) -> None:
     """
@@ -1395,27 +1399,34 @@ def generic_cache_invalidation(
         sender (type[GeneralManager]): Manager class that emitted the signal.
         instance (GeneralManager): The manager instance that was changed.
         old_relevant_values (dict[str, object]): Mapping of lookup paths (joined by "__") to their values as captured before the change; used to compare old vs. new values for invalidation decisions.
+        database_alias (str): Database alias used to attribute invalidation timing.
     """
-    manager_name = sender.__name__
-    invalidated_cache_keys: set[str] = set()
-    lock_token = acquire_lock_with_retry("generic_cache_invalidation")
+    started = perf_counter()
     try:
-        if legacy_dependency_index_exists():
-            idx = get_full_index()
-            invalidated_cache_keys = _generic_cache_invalidation_locked(
-                idx,
-                manager_name,
-                instance,
-                old_relevant_values,
-            )
-            set_full_index(idx)
-        else:
-            invalidated_cache_keys = _generic_cache_invalidation_from_shards(
-                manager_name,
-                instance,
-                old_relevant_values,
-            )
+        manager_name = sender.__name__
+        invalidated_cache_keys: set[str] = set()
+        lock_token = acquire_lock_with_retry("generic_cache_invalidation")
+        try:
+            if legacy_dependency_index_exists():
+                idx = get_full_index()
+                invalidated_cache_keys = _generic_cache_invalidation_locked(
+                    idx,
+                    manager_name,
+                    instance,
+                    old_relevant_values,
+                )
+                set_full_index(idx)
+            else:
+                invalidated_cache_keys = _generic_cache_invalidation_from_shards(
+                    manager_name,
+                    instance,
+                    old_relevant_values,
+                )
+        finally:
+            release_lock(lock_token)
+        if invalidated_cache_keys:
+            record_invalidated_cache_keys_for_graphql_rewarm(invalidated_cache_keys)
     finally:
-        release_lock(lock_token)
-    if invalidated_cache_keys:
-        record_invalidated_cache_keys_for_graphql_rewarm(invalidated_cache_keys)
+        record_data_change_phase(
+            "invalidation", perf_counter() - started, database_alias
+        )

{generalmanager-0.68.2 → generalmanager-0.69.0}/src/general_manager/cache/signals.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from contextlib import nullcontext
 from copy import deepcopy
 from functools import wraps
+from time import perf_counter
 from typing import Callable, ParamSpec, TypeVar, cast, overload
 
 from django.db import DEFAULT_DB_ALIAS, connections, transaction
@@ -12,8 +13,10 @@ from django.dispatch import Signal
 from django.utils.connection import ConnectionDoesNotExist
 
 from general_manager.cache.data_change_context import (
+    DataChangeTransactionScope,
     authorize_data_change_operation,
     own_data_change_transaction,
+    record_data_change_phase,
 )
 from general_manager.as_of import reject_historical_mutation
 from general_manager.logging import get_logger
@@ -22,6 +25,12 @@ post_data_change = Signal()
 
 pre_data_change = Signal()
 
+data_change_transaction_started = Signal()
+
+data_change_transaction_finishing = Signal()
+
+data_change_transaction_finished = Signal()
+
 P = ParamSpec("P")
 R = TypeVar("R")
 
@@ -64,6 +73,12 @@ def data_change(
     data-change barrier has closed; failed mutations drain pending keys but do
     not enqueue rewarm work.
 
+    ORM-backed outermost mutations also emit transaction lifecycle signals.
+    A ``committed`` finished outcome means this GeneralManager atomic block or
+    savepoint completed. When ``caller_in_atomic_block`` is true, consumers
+    requiring the caller's durable commit must register work with
+    ``transaction.on_commit()``.
+
     Parameters:
         func: Function that performs a data mutation. Methods named `create`
             are treated as class-level creates; every other name is treated as
@@ -134,6 +149,8 @@ def data_change(
 
         primary_exc: BaseException | None = None
         completed = False
+        transaction_scope: DataChangeTransactionScope | None = None
+        transaction_outcome = "rolled_back"
         begin_dependency_data_change()
         context = current_calculation_run_context()
         if context is not None:
@@ -157,7 +174,30 @@ def data_change(
                 if is_orm_backed
                 else nullcontext()
             )
-            with transaction_context, ownership_context:
+            with transaction_context, ownership_context as entered_scope:
+                if is_orm_backed:
+                    assert isinstance(entered_scope, DataChangeTransactionScope)
+                    transaction_scope = entered_scope
+                lifecycle_action = (
+                    action if action in {"create", "update", "delete"} else "other"
+                )
+                lifecycle_kwargs = (
+                    {
+                        "transaction_context": transaction_scope.transaction,
+                        "database_alias": database_alias,
+                        "caller_in_atomic_block": (
+                            transaction_scope.transaction.caller_in_atomic_block
+                        ),
+                        "action": lifecycle_action,
+                    }
+                    if transaction_scope is not None
+                    else {}
+                )
+                if transaction_scope is not None and transaction_scope.is_outermost:
+                    data_change_transaction_started.send(
+                        sender=sender,
+                        **lifecycle_kwargs,
+                    )
                 pre_data_change.send(
                     sender=sender,
                     instance=instance_before,
@@ -174,11 +214,22 @@ def data_change(
                     else nullcontext()
                 )
                 with operation_context:
-                    if isinstance(func, classmethod):
-                        inner = cast(Callable[P, R], func.__func__)
-                        result = inner(*args, **kwargs)
-                    else:
-                        result = func(*args, **kwargs)
+                    mutation_started = (
+                        perf_counter() if transaction_scope is not None else None
+                    )
+                    try:
+                        if isinstance(func, classmethod):
+                            inner = cast(Callable[P, R], func.__func__)
+                            result = inner(*args, **kwargs)
+                        else:
+                            result = func(*args, **kwargs)
+                    finally:
+                        if mutation_started is not None:
+                            record_data_change_phase(
+                                "database",
+                                perf_counter() - mutation_started,
+                                database_alias,
+                            )
 
                 context = current_calculation_run_context()
                 if context is not None:
@@ -205,6 +256,13 @@ def data_change(
                         delattr(instance_before, "_old_values")
                     except AttributeError:
                         pass
+                if transaction_scope is not None and transaction_scope.is_outermost:
+                    data_change_transaction_finishing.send(
+                        sender=sender,
+                        **lifecycle_kwargs,
+                    )
+            if transaction_scope is not None and transaction_scope.is_outermost:
+                transaction_outcome = "committed"
             completed = True
         except BaseException as error:
             primary_exc = error
@@ -215,15 +273,31 @@ def data_change(
             cache_keys: tuple[str, ...] = ()
             try:
                 try:
+                    if transaction_scope is not None and transaction_scope.is_outermost:
+                        try:
+                            lifecycle_kwargs["outcome"] = transaction_outcome
+                            data_change_transaction_finished.send(
+                                sender=sender,
+                                **lifecycle_kwargs,
+                            )
+                        except Exception:
+                            if primary_exc is not None:
+                                logger.exception(
+                                    "Data-change transaction finished receiver failed "
+                                    "while handling another exception."
+                                )
+                            else:
+                                raise
+                finally:
                     end_dependency_data_change()
-                except Exception:
-                    if primary_exc is not None:
-                        logger.exception(
-                            "Dependency data-change cleanup failed while handling "
-                            "another exception."
-                        )
-                    else:
-                        raise
+            except Exception:
+                if primary_exc is not None:
+                    logger.exception(
+                        "Dependency data-change cleanup failed while handling "
+                        "another exception."
+                    )
+                else:
+                    raise
             finally:
                 try:
                     if not is_dependency_data_change_active():