GeneralManager 0.50.0__tar.gz → 0.52.0__tar.gz

{generalmanager-0.50.0/src/GeneralManager.egg-info → generalmanager-0.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.50.0
+Version: 0.52.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.50.0 → generalmanager-0.52.0}/pyproject.toml

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

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

@@ -48,13 +48,16 @@ src/general_manager/bucket/base_bucket.py
 src/general_manager/bucket/calculation_bucket.py
 src/general_manager/bucket/database_bucket.py
 src/general_manager/bucket/group_bucket.py
+src/general_manager/bucket/indexing.py
 src/general_manager/bucket/request_bucket.py
 src/general_manager/cache/__init__.py
 src/general_manager/cache/cache_decorator.py
 src/general_manager/cache/cache_tracker.py
 src/general_manager/cache/dependency_cache.py
 src/general_manager/cache/dependency_index.py
+src/general_manager/cache/dependency_matching.py
 src/general_manager/cache/dependency_publish.py
+src/general_manager/cache/dependency_shards.py
 src/general_manager/cache/model_dependency_collector.py
 src/general_manager/cache/run_context.py
 src/general_manager/cache/signals.py

{generalmanager-0.50.0 → generalmanager-0.52.0}/src/general_manager/_types/bucket.py

@@ -4,14 +4,26 @@ from __future__ import annotations
 
 __all__ = [
     "Bucket",
+    "BucketIndexTooLargeError",
     "CalculationBucket",
     "DatabaseBucket",
+    "DuplicateBucketIndexKeyError",
     "GroupBucket",
+    "MissingBucketIndexKeyError",
     "RequestBucket",
+    "UnhashableBucketIndexKeyError",
+    "UnsupportedBucketIndexKeySpecError",
 ]
 
 from general_manager.bucket.base_bucket import Bucket
 from general_manager.bucket.calculation_bucket import CalculationBucket
 from general_manager.bucket.database_bucket import DatabaseBucket
 from general_manager.bucket.group_bucket import GroupBucket
+from general_manager.bucket.indexing import (
+    BucketIndexTooLargeError,
+    DuplicateBucketIndexKeyError,
+    MissingBucketIndexKeyError,
+    UnhashableBucketIndexKeyError,
+    UnsupportedBucketIndexKeySpecError,
+)
 from general_manager.bucket.request_bucket import RequestBucket

{generalmanager-0.50.0 → generalmanager-0.52.0}/src/general_manager/bucket/base_bucket.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 from abc import ABC, abstractmethod
+from collections.abc import Hashable
 from typing import (
     Type,
     Generator,
@@ -11,6 +12,15 @@ from typing import (
     TypeVar,
 )
 
+from general_manager.bucket.indexing import (
+    BucketIndexKeySpec,
+    build_multi_bucket_index,
+    build_unique_bucket_index,
+    normalize_bucket_index_key_spec,
+)
+from general_manager.cache.cache_tracker import DependencyTracker
+from general_manager.cache.run_context import ensure_calculation_run_context
+
 GeneralManagerType = TypeVar("GeneralManagerType", bound="GeneralManager")
 
 if TYPE_CHECKING:
@@ -239,6 +249,92 @@ class Bucket(ABC, Generic[GeneralManagerType]):
 
         return GroupBucket(self._manager_class, group_by_keys, self)
 
+    def _bucket_index_source_signature(self) -> Hashable:
+        """Return the conservative run-local source signature for bucket indexes."""
+        return (
+            self.__class__,
+            self._manager_class,
+            id(self),
+        )
+
+    def index_by(
+        self,
+        key_spec: BucketIndexKeySpec,
+        *,
+        max_rows: int | None = 1000,
+    ) -> dict[Hashable, GeneralManagerType]:
+        """Build or reuse a unique run-scoped index over this bucket.
+
+        Duplicate frozen keys raise an error because each key must identify one
+        row. The result is cached only for the active calculation run.
+        """
+        normalized_key_spec = normalize_bucket_index_key_spec(key_spec)
+        source_signature = self._bucket_index_source_signature()
+        with ensure_calculation_run_context() as context:
+            cached = context.get_bucket_index_result(
+                source_signature,
+                normalized_key_spec,
+                False,
+                max_rows,
+            )
+            if cached is not None:
+                return cached  # type: ignore[return-value]
+
+            with DependencyTracker() as dependencies:
+                index = build_unique_bucket_index(
+                    self,
+                    key_spec,
+                    max_rows=max_rows,
+                )
+            context.set_bucket_index_result(
+                source_signature,
+                normalized_key_spec,
+                False,
+                index,
+                dependencies,
+                max_rows,
+            )
+            return index
+
+    def index_many(
+        self,
+        key_spec: BucketIndexKeySpec,
+        *,
+        max_rows: int | None = 1000,
+    ) -> dict[Hashable, tuple[GeneralManagerType, ...]]:
+        """Build or reuse a run-scoped index that groups rows by key.
+
+        Values are tuples preserving source iteration order, and the cached
+        result is scoped to the active calculation run.
+        """
+        normalized_key_spec = normalize_bucket_index_key_spec(key_spec)
+        source_signature = self._bucket_index_source_signature()
+        with ensure_calculation_run_context() as context:
+            cached = context.get_bucket_index_result(
+                source_signature,
+                normalized_key_spec,
+                True,
+                max_rows,
+            )
+            if cached is not None:
+                return cached  # type: ignore[return-value]
+
+            with DependencyTracker() as dependencies:
+                index = build_multi_bucket_index(
+                    self,
+                    key_spec,
+                    max_rows=max_rows,
+                )
+            context.set_bucket_index_result(
+                source_signature,
+                normalized_key_spec,
+                True,
+                index,
+                dependencies,
+                max_rows,
+            )
+            return index
+
     def none(self) -> Bucket[GeneralManagerType]:
         """
         Return an empty bucket instance.

{generalmanager-0.50.0 → generalmanager-0.52.0}/src/general_manager/bucket/calculation_bucket.py

@@ -1,7 +1,7 @@
 """Bucket implementation that enumerates calculation interface combinations."""
 
 from __future__ import annotations
-from collections.abc import Iterable
+from collections.abc import Hashable, Iterable
 from types import UnionType
 from typing import (
     Any,
@@ -22,6 +22,7 @@ from general_manager.interface.base_interface import (
     GeneralManagerType,
 )
 from general_manager.bucket.base_bucket import Bucket
+from general_manager.bucket.indexing import freeze_bucket_index_value
 from general_manager.manager.input import Input, InputDomain
 from general_manager.utils.filter_parser import parse_filters
 
@@ -461,6 +462,17 @@ class CalculationBucket(Bucket[GeneralManagerType]):
             return (self.sort_key,)
         return self.sort_key
 
+    def _bucket_index_source_signature(self) -> Hashable:
+        """Return a stable signature for equivalent calculation bucket plans."""
+        return (
+            "calculation",
+            self._manager_class,
+            freeze_bucket_index_value(self.filter_definitions),
+            freeze_bucket_index_value(self.exclude_definitions),
+            self._normalized_sort_key(),
+            self.reverse,
+        )
+
     def _sort_uses_only_inputs(self, sort_key: tuple[str, ...] | None) -> bool:
         """Return whether a sort can be applied to raw input dictionaries."""
         if sort_key is None:

{generalmanager-0.50.0 → generalmanager-0.52.0}/src/general_manager/bucket/database_bucket.py

@@ -329,6 +329,13 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             self._sort_reverse,
         )
 
+    def _bucket_index_source_signature(self) -> Hashable:
+        """Return a queryset signature when safe, otherwise use object identity."""
+        query_signature = self._query_signature()
+        if query_signature is None:
+            return super()._bucket_index_source_signature()
+        return ("database", query_signature)
+
     def _get_run_scoped_primary_keys(self) -> tuple[Any, ...] | None:
         """
         Load or reuse a bounded primary-key snapshot for this bucket.

generalmanager-0.52.0/src/general_manager/bucket/indexing.py

@@ -0,0 +1,184 @@
+"""Run-scoped bucket index helpers."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Hashable, Iterable
+from typing import TypeVar, cast
+
+T = TypeVar("T")
+BucketIndexKeySpec = str | tuple[str, ...]
+NormalizedBucketIndexKeySpec = tuple[str, tuple[str, ...], bool]
+
+
+def _frozen_pair_sort_key(pair: tuple[Hashable, Hashable]) -> tuple[str, str]:
+    """Return a string-only sort key for frozen mapping pairs."""
+    return (str(pair[0]), str(pair[1]))
+
+
+class UnsupportedBucketIndexKeySpecError(TypeError):
+    """Raised when a bucket index key spec cannot produce a stable run key."""
+
+    def __init__(self, key_spec: object) -> None:
+        """Build an error that names the unsupported key specification."""
+        super().__init__(
+            "Bucket index key specs must be a field name or a non-empty tuple "
+            f"of field names; got {key_spec!r}."
+        )
+
+
+class MissingBucketIndexKeyError(AttributeError):
+    """Raised when an indexed row does not expose a requested key field."""
+
+    def __init__(self, field_name: str, row: object) -> None:
+        """Build an error that identifies the missing row field."""
+        super().__init__(
+            f"Cannot build bucket index: {row!r} is missing key field {field_name!r}."
+        )
+
+
+class DuplicateBucketIndexKeyError(ValueError):
+    """Raised when a unique bucket index sees more than one row for a key."""
+
+    def __init__(self, key: Hashable) -> None:
+        """Build an error that identifies the duplicated frozen index key."""
+        super().__init__(f"Bucket index key {key!r} matched more than one row.")
+
+
+class BucketIndexTooLargeError(ValueError):
+    """Raised when index construction exceeds the configured row guardrail."""
+
+    def __init__(self, max_rows: int) -> None:
+        """Build an error that reports the row guardrail that was exceeded."""
+        super().__init__(
+            f"Bucket index construction exceeded the configured limit of {max_rows} rows."
+        )
+
+
+class UnhashableBucketIndexKeyError(TypeError):
+    """Raised when a key value cannot be converted to a hashable identity."""
+
+    def __init__(self, key: object) -> None:
+        """Build an error that reports the unfreezable key value."""
+        super().__init__(f"Bucket index key {key!r} is not hashable.")
+
+
+def normalize_bucket_index_key_spec(
+    key_spec: object,
+) -> NormalizedBucketIndexKeySpec:
+    """Return a stable normalized representation for a supported key spec."""
+    if isinstance(key_spec, str):
+        return ("field", (key_spec,), False)
+    if (
+        isinstance(key_spec, tuple)
+        and len(key_spec) > 0
+        and all(isinstance(part, str) for part in key_spec)
+    ):
+        return ("field", key_spec, True)
+    raise UnsupportedBucketIndexKeySpecError(key_spec)
+
+
+def freeze_bucket_index_value(value: object) -> Hashable:
+    """Return a stable hashable identity for values used as index keys.
+
+    Manager instances are represented by their class and identification, and
+    containers are recursively frozen so equivalent values share a run-cache key.
+    """
+    from general_manager.manager.general_manager import GeneralManager
+
+    if isinstance(value, GeneralManager):
+        return (
+            value.__class__,
+            tuple(
+                sorted(
+                    (
+                        (
+                            cast(Hashable, freeze_bucket_index_value(key)),
+                            freeze_bucket_index_value(identifier),
+                        )
+                        for key, identifier in value.identification.items()
+                    ),
+                    key=_frozen_pair_sort_key,
+                )
+            ),
+        )
+    if isinstance(value, dict):
+        return tuple(
+            sorted(
+                (
+                    (
+                        cast(Hashable, freeze_bucket_index_value(key)),
+                        freeze_bucket_index_value(item),
+                    )
+                    for key, item in value.items()
+                ),
+                key=_frozen_pair_sort_key,
+            )
+        )
+    if isinstance(value, (list, tuple)):
+        return tuple(freeze_bucket_index_value(item) for item in value)
+    if isinstance(value, set):
+        return frozenset(freeze_bucket_index_value(item) for item in value)
+    try:
+        hash(value)
+    except TypeError as error:
+        raise UnhashableBucketIndexKeyError(value) from error
+    return cast(Hashable, value)
+
+
+def resolve_bucket_index_key(
+    row: object,
+    key_spec: BucketIndexKeySpec,
+) -> Hashable:
+    """Resolve the requested field value or composite key for one row."""
+    _, field_names, composite = normalize_bucket_index_key_spec(key_spec)
+    values: list[Hashable] = []
+    for field_name in field_names:
+        try:
+            value = getattr(row, field_name)
+        except AttributeError as error:
+            raise MissingBucketIndexKeyError(field_name, row) from error
+        values.append(freeze_bucket_index_value(value))
+    if composite:
+        return tuple(values)
+    return values[0]
+
+
+def _iter_guarded_rows(
+    rows: Iterable[T],
+    max_rows: int | None,
+) -> Iterable[T]:
+    """Yield rows until max_rows is exceeded, then raise a guardrail error."""
+    for index, row in enumerate(rows):
+        if max_rows is not None and index >= max_rows:
+            raise BucketIndexTooLargeError(max_rows)
+        yield row
+
+
+def build_unique_bucket_index(
+    rows: Iterable[T],
+    key_spec: BucketIndexKeySpec,
+    *,
+    max_rows: int | None,
+) -> dict[Hashable, T]:
+    """Build a unique index and fail when duplicate frozen keys are found."""
+    indexed: dict[Hashable, T] = {}
+    for row in _iter_guarded_rows(rows, max_rows):
+        key = resolve_bucket_index_key(row, key_spec)
+        if key in indexed:
+            raise DuplicateBucketIndexKeyError(key)
+        indexed[key] = row
+    return indexed
+
+
+def build_multi_bucket_index(
+    rows: Iterable[T],
+    key_spec: BucketIndexKeySpec,
+    *,
+    max_rows: int | None,
+) -> dict[Hashable, tuple[T, ...]]:
+    """Build a grouped index that preserves row order for duplicate keys."""
+    grouped: defaultdict[Hashable, list[T]] = defaultdict(list)
+    for row in _iter_guarded_rows(rows, max_rows):
+        grouped[resolve_bucket_index_key(row, key_spec)].append(row)
+    return {key: tuple(values) for key, values in grouped.items()}

{generalmanager-0.50.0 → generalmanager-0.52.0}/src/general_manager/bucket/request_bucket.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-from collections.abc import Generator, Mapping
+from collections.abc import Generator, Hashable, Mapping
 from typing import TYPE_CHECKING, Any, cast
 
 from general_manager.bucket.base_bucket import Bucket, GeneralManagerType
+from general_manager.bucket.indexing import freeze_bucket_index_value
 from general_manager.interface.requests import (
     RequestLocalPredicate,
     RequestLocalPaginationUnsupportedError,
@@ -172,6 +173,22 @@ class RequestBucket(Bucket[GeneralManagerType]):
             item.identification for item in other._ensure_items()
         )
 
+    def _bucket_index_source_signature(self) -> Hashable:
+        """Return a stable request signature, or object identity for materialized data."""
+        if self.request_plan is not None:
+            restore_func, restore_args = self.request_plan.__reduce__()
+            return (
+                "request",
+                self._manager_class,
+                self._interface_cls,
+                self._operation_name,
+                restore_func,
+                freeze_bucket_index_value(restore_args),
+                freeze_bucket_index_value(self.filters),
+                freeze_bucket_index_value(self.excludes),
+            )
+        return super()._bucket_index_source_signature()
+
     def __iter__(self) -> Generator[GeneralManagerType, None, None]:
         yield from self._ensure_items()