GeneralManager 0.60.0__tar.gz → 0.60.1__tar.gz

{generalmanager-0.60.0/src/GeneralManager.egg-info → generalmanager-0.60.1}/PKG-INFO

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

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

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

@@ -27,6 +27,9 @@ QueryAnnotationCallable = Callable[
     models.QuerySet[models.Model],
 ]
 MAX_RUN_SCOPED_BUCKET_RESULT_ROWS = 1000
+_QUERY_SIGNATURE_NOT_COMPUTED = object()
+_FIRST_ROW_CACHE_MISS = object()
+_FIRST_ROW_CACHE_NONE = object()
 
 
 class DatabaseBucketTypeMismatchError(TypeError):
@@ -251,6 +254,79 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         self._sort_keys = sort_keys
         self._sort_reverse = sort_reverse
         self._run_scoped_cacheable = run_scoped_cacheable
+        self._query_signature_cache: tuple[Hashable, ...] | None | object = (
+            _QUERY_SIGNATURE_NOT_COMPUTED
+        )
+        self._trusted_query_signature: Hashable | None = None
+
+    def _set_trusted_query_signature(self, signature: Hashable | None) -> None:
+        """Set an internal non-SQL signature for framework-built querysets."""
+        self._trusted_query_signature = signature
+        self._query_signature_cache = _QUERY_SIGNATURE_NOT_COMPUTED
+
+    def _copy_for_run_context_reuse(self) -> DatabaseBucket[GeneralManagerType]:
+        """Return an unexposed bucket copy that reuses the same trusted queryset."""
+
+        bucket = self.__class__(
+            self._data,
+            self._manager_class,
+            self.filters,
+            self.excludes,
+            search_date=self._search_date,
+            sort_keys=self._sort_keys,
+            sort_reverse=self._sort_reverse,
+            run_scoped_cacheable=self._run_scoped_cacheable,
+        )
+        bucket._set_trusted_query_signature(self._trusted_query_signature)
+        return bucket
+
+    @staticmethod
+    def _freeze_trusted_signature_payload(value: object) -> Hashable:
+        if isinstance(value, Mapping):
+            return tuple(
+                (
+                    str(key),
+                    DatabaseBucket._freeze_trusted_signature_payload(item_value),
+                )
+                for key, item_value in sorted(
+                    value.items(),
+                    key=lambda item: str(item[0]),
+                )
+            )
+        if isinstance(value, (list, tuple)):
+            return tuple(
+                DatabaseBucket._freeze_trusted_signature_payload(item) for item in value
+            )
+        if isinstance(value, (set, frozenset)):
+            return tuple(
+                sorted(
+                    (
+                        DatabaseBucket._freeze_trusted_signature_payload(item)
+                        for item in value
+                    ),
+                    key=repr,
+                )
+            )
+        if isinstance(value, models.Model):
+            return ("model", value.__class__, value.pk)
+        try:
+            hash(value)
+        except TypeError:
+            return ("serialized", serialize_dependency_identifier(value))
+        return value
+
+    def _trusted_query_signature_with(
+        self,
+        operation: str,
+        kwargs: Mapping[str, object],
+    ) -> Hashable | None:
+        if self._trusted_query_signature is None:
+            return None
+        return (
+            self._trusted_query_signature,
+            operation,
+            self._freeze_trusted_signature_payload(kwargs),
+        )
 
     def __reduce__(self) -> str | tuple[object, ...]:
         """
@@ -365,27 +441,50 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             tuple[Hashable, ...] | None: Cache key components for equivalent
             queryset results, or ``None`` when reuse should be bypassed.
         """
+        if self._query_signature_cache is not _QUERY_SIGNATURE_NOT_COMPUTED:
+            return cast(tuple[Hashable, ...] | None, self._query_signature_cache)
         if not self._run_scoped_cacheable:
+            self._query_signature_cache = None
             return None
+        if self._trusted_query_signature is not None:
+            signature = (
+                self._manager_class,
+                self._data.model,
+                self._data.db,
+                "trusted",
+                self._trusted_query_signature,
+                self._search_date,
+                self._sort_keys,
+                self._sort_reverse,
+            )
+            self._query_signature_cache = signature
+            return signature
         query = self._data.query
         if not isinstance(query, Query):
+            self._query_signature_cache = None
             return None
         if query.select_for_update:
+            self._query_signature_cache = None
             return None
         if query.combinator:
+            self._query_signature_cache = None
             return None
         if query.distinct:
+            self._query_signature_cache = None
             return None
         if getattr(self._data, "_prefetch_related_lookups", ()):
+            self._query_signature_cache = None
             return None
         deferred_loading = getattr(query, "deferred_loading", None)
         if isinstance(deferred_loading, tuple) and deferred_loading[0]:
+            self._query_signature_cache = None
             return None
         try:
             sql, params = self._data.query.sql_with_params()
         except (EmptyResultSet, FieldError, TypeError, ValueError):
+            self._query_signature_cache = None
             return None
-        return (
+        signature = (
             self._manager_class,
             self._data.model,
             self._data.db,
@@ -395,6 +494,8 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             self._sort_keys,
             self._sort_reverse,
         )
+        self._query_signature_cache = signature
+        return signature
 
     def _bucket_index_source_signature(self) -> Hashable:
         """Return a queryset signature when safe, otherwise use object identity."""
@@ -501,6 +602,38 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             return None
         return cast(tuple[models.Model, ...], cached)
 
+    def _can_cache_run_scoped_managers(self) -> bool:
+        if self._manager_class.__init__ is not GeneralManager.__init__:
+            return False
+        return callable(
+            getattr(self._manager_class.Interface, "_from_trusted_orm_instance", None)
+        )
+
+    def _get_run_scoped_managers(self) -> tuple[GeneralManagerType, ...] | None:
+        """Load or reuse manager wrappers for a trusted row snapshot."""
+        if not self._can_cache_run_scoped_managers():
+            return None
+        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_managers(signature)
+        if cached is not None:
+            managers = cast(tuple[GeneralManagerType, ...], cached)
+            for manager in managers:
+                self._manager_class._track_identification_dependency(
+                    manager.identification
+                )
+            return managers
+        rows = self._get_run_scoped_rows()
+        if rows is None:
+            return None
+        managers = tuple(self._build_manager_from_instance(row) for row in rows)
+        context.set_orm_bucket_managers(signature, managers)
+        return managers
+
     @staticmethod
     def _snapshot_get_primary_key(
         kwargs: Mapping[str, LookupValue],
@@ -528,21 +661,33 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             return kwargs["id"]
         return None
 
+    def _can_materialize_count_snapshot(self) -> bool:
+        """Return whether count/len may populate a bounded run-scoped snapshot."""
+        context = current_calculation_run_context()
+        if context is None:
+            return False
+        query = getattr(self._data, "query", None)
+        if not isinstance(query, Query):
+            return False
+        where = getattr(query, "where", None)
+        children = getattr(where, "children", None)
+        return bool(children)
+
     def _track_effective_dependencies(self) -> None:
         """Record the bucket's effective filter/exclude state when it is evaluated."""
         manager_name = self._manager_class.__name__
         normalized_filters = self._normalize_dependency_mapping(self.filters)
         normalized_excludes = self._normalize_dependency_mapping(self.excludes)
         if self.filters:
-            DependencyTracker.track(
+            DependencyTracker._track_validated(
                 manager_name,
                 "filter",
                 serialize_dependency_identifier(normalized_filters),
             )
         else:
-            DependencyTracker.track(manager_name, "all", "")
+            DependencyTracker._track_validated(manager_name, "all", "")
         if self.excludes:
-            DependencyTracker.track(
+            DependencyTracker._track_validated(
                 manager_name,
                 "exclude",
                 serialize_dependency_identifier(normalized_excludes),
@@ -554,7 +699,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
                     "excludes": normalized_excludes,
                     "reverse": self._sort_reverse,
                 }
-                DependencyTracker.track(
+                DependencyTracker._track_validated(
                     manager_name,
                     "filter",
                     serialize_dependency_identifier({f"__sort__{sort_key}": payload}),
@@ -576,6 +721,10 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             GeneralManagerType: Manager instance for each primary key in the queryset.
         """
         self._track_effective_dependencies()
+        managers = self._get_run_scoped_managers()
+        if managers is not None:
+            yield from managers
+            return
         rows = self._get_run_scoped_rows()
         if rows is not None:
             for row in rows:
@@ -782,7 +931,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             qs = qs.filter(pk__in=ids)
 
         merged_filter = self.__merge_filter_definitions(self.filters, **kwargs)
-        return self.__class__(
+        bucket = self.__class__(
             qs,
             self._manager_class,
             merged_filter,
@@ -792,6 +941,11 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             sort_reverse=self._sort_reverse,
             run_scoped_cacheable=self._run_scoped_cacheable,
         )
+        if not annotations and not python_filters:
+            bucket._set_trusted_query_signature(
+                self._trusted_query_signature_with("filter", orm_kwargs)
+            )
+        return bucket
 
     def exclude(self, **kwargs: LookupValue) -> DatabaseBucket[GeneralManagerType]:
         """
@@ -843,7 +997,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             qs = qs.exclude(pk__in=ids)
 
         merged_exclude = self.__merge_filter_definitions(self.excludes, **kwargs)
-        return self.__class__(
+        bucket = self.__class__(
             qs,
             self._manager_class,
             self.filters,
@@ -853,6 +1007,11 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             sort_reverse=self._sort_reverse,
             run_scoped_cacheable=self._run_scoped_cacheable,
         )
+        if not annotations and not python_filters:
+            bucket._set_trusted_query_signature(
+                self._trusted_query_signature_with("exclude", orm_kwargs)
+            )
+        return bucket
 
     def first(self) -> GeneralManagerType | None:
         """
@@ -875,7 +1034,23 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             if not primary_keys:
                 return None
             return self._build_manager_from_primary_key(primary_keys[0])
+        context = current_calculation_run_context()
+        signature = self._query_signature() if context is not None else None
+        if context is not None and signature is not None:
+            cached = context.get_orm_bucket_first_row(
+                signature,
+                _FIRST_ROW_CACHE_MISS,
+            )
+            if cached is _FIRST_ROW_CACHE_NONE:
+                return None
+            if cached is not _FIRST_ROW_CACHE_MISS:
+                return self._build_manager_from_instance(cast(models.Model, cached))
         first_element = self._data.first()
+        if context is not None and signature is not None:
+            context.set_orm_bucket_first_row(
+                signature,
+                _FIRST_ROW_CACHE_NONE if first_element is None else first_element,
+            )
         if first_element is None:
             return None
         return self._build_manager_from_instance(first_element)
@@ -917,6 +1092,10 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             int: Number of represented rows.
         """
         self._track_effective_dependencies()
+        if self._can_materialize_count_snapshot():
+            rows = self._get_run_scoped_rows()
+            if rows is not None:
+                return len(rows)
         primary_keys = self._peek_run_scoped_primary_keys()
         if primary_keys is not None:
             return len(primary_keys)
@@ -932,7 +1111,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         Returns:
             DatabaseBucket[GeneralManagerType]: Bucket encapsulating `self._data.all()`.
         """
-        return self.__class__(
+        bucket = self.__class__(
             self._data.all(),
             self._manager_class,
             self.filters,
@@ -942,6 +1121,8 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             sort_reverse=self._sort_reverse,
             run_scoped_cacheable=self._run_scoped_cacheable,
         )
+        bucket._set_trusted_query_signature(self._trusted_query_signature)
+        return bucket
 
     def get(self, **kwargs: LookupValue) -> GeneralManagerType:
         """
@@ -1027,21 +1208,43 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             return self._build_manager_from_primary_key(primary_keys[item])
         return self._build_manager_from_instance(self._data[item])
 
+    def __bool__(self) -> bool:
+        """
+        Return whether the bucket contains at least one row without counting all rows.
+
+        Truthiness is an existence check, not a cardinality request. Reuse any
+        active run-context snapshot first, then cache a queryset ``exists()``
+        result for equivalent trusted querysets in the same calculation run.
+        """
+        self._track_effective_dependencies()
+        rows = self._peek_run_scoped_rows()
+        if rows is not None:
+            return bool(rows)
+        primary_keys = self._peek_run_scoped_primary_keys()
+        if primary_keys is not None:
+            return bool(primary_keys)
+        context = current_calculation_run_context()
+        signature = self._query_signature() if context is not None else None
+        if context is not None and signature is not None:
+            cached = context.get_orm_bucket_exists(signature)
+            if cached is not None:
+                return bool(cached)
+        exists = bool(self._data.exists())
+        if context is not None and signature is not None:
+            context.set_orm_bucket_exists(signature, exists)
+        return exists
+
     def __len__(self) -> int:
         """
         Return the number of rows represented by the bucket.
 
-        A safe run-scoped primary-key snapshot is reused when present; otherwise
-        this delegates to the queryset count.
+        Delegates to `count()` so dependency tracking, run-scoped snapshots, and
+        queryset fallback behavior stay aligned between both cardinality paths.
 
         Returns:
             int: Number of represented rows.
         """
-        self._track_effective_dependencies()
-        primary_keys = self._peek_run_scoped_primary_keys()
-        if primary_keys is not None:
-            return len(primary_keys)
-        return int(self._data.count())
+        return self.count()
 
     def __str__(self) -> str:
         """
@@ -1169,7 +1372,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             except (FieldError, TypeError, ValueError) as error:
                 raise QuerysetOrderingError(error) from error
 
-        return self.__class__(
+        bucket = self.__class__(
             qs,
             self._manager_class,
             self.filters,
@@ -1179,6 +1382,9 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             sort_reverse=reverse,
             run_scoped_cacheable=self._run_scoped_cacheable,
         )
+        if not annotations and not python_keys:
+            bucket._set_trusted_query_signature(self._trusted_query_signature)
+        return bucket
 
     def none(self) -> DatabaseBucket[GeneralManagerType]:
         """
@@ -1193,4 +1399,6 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         """
         own = self.all()
         own._data = own._data.none()
+        own._query_signature_cache = _QUERY_SIGNATURE_NOT_COMPUTED
+        own._trusted_query_signature = None
         return own

{generalmanager-0.60.0 → generalmanager-0.60.1}/src/general_manager/cache/cache_tracker.py

@@ -135,12 +135,20 @@ class DependencyTracker:
             raise _InvalidDependencyTrackerValueError
         if operation not in _SUPPORTED_OPERATIONS:
             raise _InvalidDependencyTrackerOperationError(operation)
+        DependencyTracker._track_validated(class_name, operation, identifier)
+
+    @staticmethod
+    def _track_validated(
+        class_name: general_manager_name,
+        operation: filter_type,
+        identifier: str,
+    ) -> None:
+        """Record an already-validated dependency tuple in active collectors."""
         if _dependency_storage.depth < 0:
             return
-        for dep_set in _dependency_storage.dependencies[
-            : _dependency_storage.depth + 1
-        ]:
-            dep_set.add((class_name, operation, identifier))
+        dependency = (class_name, operation, identifier)
+        for dep_set in _dependency_storage.dependencies:
+            dep_set.add(dependency)
 
     @staticmethod
     def is_active() -> bool:

{generalmanager-0.60.0 → generalmanager-0.60.1}/src/general_manager/cache/dependency_cache.py

@@ -9,7 +9,8 @@ from typing import Protocol, TypeGuard, cast
 from general_manager.cache.cache_tracker import DependencyTracker
 from general_manager.cache.dependency_index import Dependency
 
-DEPENDENCY_CACHE_ENTRY_VERSION = 1
+LEGACY_DEPENDENCY_CACHE_ENTRY_VERSION = 1
+DEPENDENCY_CACHE_ENTRY_VERSION = 2
 _VALID_DEPENDENCY_ACTIONS = frozenset(
     {"filter", "exclude", "identification", "request_query", "all"}
 )
@@ -258,10 +259,19 @@ def _combined_payload_to_hit(
 ) -> DependencyCacheHit | None | _MissingSentinel:
     if not isinstance(payload, DependencyCacheEntry):
         return None
-    if payload.version != DEPENDENCY_CACHE_ENTRY_VERSION:
-        return _MISSING
-    dependencies = _legacy_dependency_set(payload.dependencies)
-    if dependencies is None:
+    if payload.version == LEGACY_DEPENDENCY_CACHE_ENTRY_VERSION:
+        dependencies = _legacy_dependency_set(payload.dependencies)
+        if dependencies is None:
+            return _MISSING
+    elif payload.version == DEPENDENCY_CACHE_ENTRY_VERSION:
+        # Legacy entries may contain arbitrary tuple-like data, so the
+        # _legacy_dependency_set path validates each dependency. Current entries
+        # come from make_dependency_cache_entry after that same validation flow,
+        # so keep deserialization on the frozenset type-check fast path.
+        if not isinstance(payload.dependencies, frozenset):
+            return _MISSING
+        dependencies = payload.dependencies
+    else:
         return _MISSING
     return DependencyCacheHit(
         value=payload.value,

{generalmanager-0.60.0 → generalmanager-0.60.1}/src/general_manager/cache/dependency_matching.py

@@ -8,6 +8,7 @@ import re
 from collections.abc import Callable, Mapping, Sequence, Set as AbstractSet
 from dataclasses import dataclass
 from datetime import date, datetime
+from json.encoder import encode_basestring_ascii
 from typing import Literal, Protocol, cast
 
 LookupOperator = Literal[
@@ -29,6 +30,8 @@ SCAN_OPERATORS = frozenset(
 )
 SUPPORTED_LOOKUP_OPERATORS = EXACT_OPERATORS | SCAN_OPERATORS
 UNDEFINED = object()
+_SCALAR_NORMALIZATION_MISS = object()
+_SCALAR_SERIALIZATION_MISS = object()
 
 
 type NormalizedDependencyValue = (
@@ -62,6 +65,47 @@ class SupportsDependencyComparison(Protocol):
         ...
 
 
+def _normalize_scalar_dependency_value(value: object) -> object:
+    """
+    Return the scalar-only equivalent of `normalize_dependency_value`.
+
+    This avoids the slower general path for simple scalars only, and its output
+    must remain equivalent to full normalization for every value it accepts.
+    """
+
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return _SCALAR_NORMALIZATION_MISS
+
+
+def _serialize_scalar_dependency_value(value: object) -> str | object:
+    """
+    Serialize simple scalars without the slower generic JSON path.
+
+    Outputs must remain equivalent to full normalization followed by
+    `json.dumps(..., sort_keys=True)`. Floats are intentionally excluded so the
+    caller can preserve Python's JSON spelling for finite and non-finite values.
+    """
+
+    if isinstance(value, str):
+        return encode_basestring_ascii(value)
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if type(value) is int:
+        return str(value)
+    if isinstance(value, date):
+        return encode_basestring_ascii(value.isoformat())
+    return _SCALAR_SERIALIZATION_MISS
+
+
 @dataclass(frozen=True, slots=True)
 class LookupSpec:
     """Parsed dependency lookup path and operator."""
@@ -75,6 +119,11 @@ def normalize_dependency_value(value: object) -> NormalizedDependencyValue:
     """Return a deterministic JSON-compatible representation for dependency data."""
     if isinstance(value, Mapping):
         mapping = cast(Mapping[object, object], value)
+        if len(mapping) == 1:
+            key, val = next(iter(mapping.items()))
+            normalized_value = _normalize_scalar_dependency_value(val)
+            if normalized_value is not _SCALAR_NORMALIZATION_MISS:
+                return {str(key): cast(NormalizedDependencyValue, normalized_value)}
         return {
             str(key): normalize_dependency_value(val)
             for key, val in sorted(mapping.items(), key=lambda item: str(item[0]))
@@ -101,12 +150,24 @@ def normalize_dependency_value(value: object) -> NormalizedDependencyValue:
 
 def serialize_normalized_value(value: object) -> str:
     """Serialize dependency values in the canonical dependency format."""
-    if isinstance(value, str):
-        return json.dumps(value)
-    if value is None or isinstance(value, (int, float, bool)):
+    serialized_scalar = _serialize_scalar_dependency_value(value)
+    if serialized_scalar is not _SCALAR_SERIALIZATION_MISS:
+        return cast(str, serialized_scalar)
+    if isinstance(value, float):
         return json.dumps(value)
-    if isinstance(value, date):
-        return json.dumps(value.isoformat())
+    if isinstance(value, Mapping):
+        mapping = cast(Mapping[object, object], value)
+        if len(mapping) == 1:
+            key, val = next(iter(mapping.items()))
+            normalized_value = _normalize_scalar_dependency_value(val)
+            serialized_value = _serialize_scalar_dependency_value(normalized_value)
+            if serialized_value is not _SCALAR_SERIALIZATION_MISS:
+                return (
+                    "{"
+                    f"{encode_basestring_ascii(str(key))}: "
+                    f"{cast(str, serialized_value)}"
+                    "}"
+                )
     return json.dumps(normalize_dependency_value(value), sort_keys=True)
 
 

{generalmanager-0.60.0 → generalmanager-0.60.1}/src/general_manager/cache/dependency_shards.py

@@ -13,6 +13,7 @@ import hashlib
 from collections.abc import Iterable, Mapping
 from collections import defaultdict
 from dataclasses import dataclass, field
+from functools import lru_cache
 from typing import Literal
 
 from django.core.cache import cache
@@ -377,6 +378,7 @@ def clear_legacy_dependency_index() -> set[str]:
     return cache_keys
 
 
+@lru_cache(maxsize=16384)
 def _shard_keys_for_dependency(
     manager_name: str,
     action: DependencyAction,