GeneralManager 0.69.2__tar.gz → 0.71.0__tar.gz

{generalmanager-0.69.2/src/GeneralManager.egg-info → generalmanager-0.71.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.69.2
+Version: 0.71.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.69.2 → generalmanager-0.71.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.69.2
+Version: 0.71.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.69.2 → generalmanager-0.71.0}/src/general_manager/_types/permission.py

@@ -16,6 +16,7 @@ __all__ = [
     "OverrideManagerPermission",
     "PermissionAuditEvent",
     "PermissionDataManager",
+    "PermissionFilterDecision",
     "configure_audit_logger",
     "configure_audit_logger_from_settings",
     "mutation_capability",
@@ -44,6 +45,7 @@ from general_manager.permission.manager_based_permission import (
 )
 from general_manager.permission.audit import PermissionAuditEvent
 from general_manager.permission.permission_data_manager import PermissionDataManager
+from general_manager.permission.permission_checks import PermissionFilterDecision
 from general_manager.permission.audit import configure_audit_logger
 from general_manager.permission.audit import configure_audit_logger_from_settings
 from general_manager.permission.graphql_capabilities import mutation_capability

{generalmanager-0.69.2 → generalmanager-0.71.0}/src/general_manager/api/graphql_errors.py

@@ -655,7 +655,7 @@ def get_read_permission_filter(
 
     Returns:
         A ``ReadPermissionPlan`` with ``filters``, ``requires_instance_check``,
-        and ``instance_check_reasons`` fields. ``ReadPermissionPlan`` is an
+        ``instance_check_reasons``, and ``decision`` fields. ``ReadPermissionPlan`` is an
         internal adapter from ``general_manager.permission.base_permission``, not
         a stable public import path, but generated resolvers rely on these
         fields.
@@ -677,7 +677,8 @@ def get_read_permission_filter(
         ``("no_prefilter_backend",)``.
 
         Managers without a permission factory receive an empty filter plan and
-        do not require instance checks. This is a default-allow read policy for
+        do not require instance checks, with an explicit ``"allow_all"``
+        decision. This is a default-allow read policy for
         managers that do not define ``Permission``; no additional GraphQL
         permission filtering or per-object read authorization is applied by this
         helper. More generally, ``filters=[]`` with
@@ -715,4 +716,8 @@ def get_read_permission_filter(
         )
     if permission_attribute is not None:
         raise InvalidReadPermissionConfigurationError(generalManagerClass.__name__)
-    return ReadPermissionPlan(filters=[], requires_instance_check=False)
+    return ReadPermissionPlan(
+        filters=[],
+        requires_instance_check=False,
+        decision="allow_all",
+    )

{generalmanager-0.69.2 → generalmanager-0.71.0}/src/general_manager/api/graphql_resolvers.py

@@ -90,12 +90,17 @@ class UnsupportedExcludeNoneRelationFilterError(ValueError):
 
 @dataclass(slots=True)
 class ReadAuthorizationResult(Generic[GeneralManagerT]):
-    """Aggregate outcome from GraphQL read prefiltering and row authorization."""
+    """Aggregate outcome from GraphQL read prefiltering and row authorization.
+
+    Counts remain ``None`` when authorization can return a bucket lazily without
+    inspecting or counting it. They are populated when a row-level gate actually
+    scans candidates; deny-all plans use known zero counts.
+    """
 
     queryset: Bucket[GeneralManagerT]
-    candidate_count: int
-    authorized_count: int
-    denied_count: int
+    candidate_count: int | None
+    authorized_count: int | None
+    denied_count: int | None
     backend_shape: str
     requires_instance_check: bool
     instance_check_reasons: tuple[str, ...]
@@ -266,7 +271,7 @@ def apply_read_authorization(
     final row gate runs and an aggregate log event is emitted only if the final
     authorization result still requires instance checks.
     Unrestricted plans that do not require instance checks return the original
-    queryset with matching candidate and authorized counts.
+    queryset without evaluating it to compute counts.
     """
     permission_plan = get_read_permission_filter(general_manager_class, info)
     backend_shape = get_backend_shape(general_manager_class)
@@ -275,16 +280,40 @@ def apply_read_authorization(
         backend_shape=backend_shape,
     )
 
-    filtered_queryset = queryset
-    if not permission_plan.requires_instance_check and permission_plan.filters == [
-        {"filter": {}, "exclude": {}}
-    ]:
-        candidate_count = len(queryset)
+    if permission_plan.decision == "deny_all":
+        return ReadAuthorizationResult(
+            queryset=queryset.none(),
+            candidate_count=0,
+            authorized_count=0,
+            denied_count=0,
+            backend_shape=backend_shape,
+            requires_instance_check=False,
+            instance_check_reasons=(),
+        )
+
+    if permission_plan.decision == "allow_all":
+        return ReadAuthorizationResult(
+            queryset=queryset,
+            candidate_count=None,
+            authorized_count=None,
+            denied_count=None,
+            backend_shape=backend_shape,
+            requires_instance_check=False,
+            instance_check_reasons=(),
+        )
+
+    filtered_queryset: Bucket[GeneralManagerT] | None = queryset
+    if (
+        not permission_plan.requires_instance_check
+        and len(permission_plan.filters) == 1
+        and not permission_plan.filters[0].get("filter")
+        and not permission_plan.filters[0].get("exclude")
+    ):
         result = ReadAuthorizationResult(
             queryset=queryset,
-            candidate_count=candidate_count,
-            authorized_count=candidate_count,
-            denied_count=0,
+            candidate_count=None,
+            authorized_count=None,
+            denied_count=None,
             backend_shape=backend_shape,
             requires_instance_check=False,
             instance_check_reasons=instance_check_reasons,
@@ -292,7 +321,7 @@ def apply_read_authorization(
         return result
 
     if permission_plan.filters:
-        filtered_queryset = queryset.none()
+        filtered_queryset = None
         for permission_filter in permission_plan.filters:
             filter_dict = permission_filter.get("filter", {})
             exclude_dict = permission_filter.get("exclude", {})
@@ -300,7 +329,10 @@ def apply_read_authorization(
                 qs_perm = queryset
             else:
                 qs_perm = queryset.filter(**filter_dict).exclude(**exclude_dict)
-            filtered_queryset = filtered_queryset | qs_perm
+            filtered_queryset = (
+                qs_perm if filtered_queryset is None else filtered_queryset | qs_perm
+            )
+    assert filtered_queryset is not None
 
     result = filter_queryset_by_read_permission(
         filtered_queryset,
@@ -332,19 +364,17 @@ def filter_queryset_by_read_permission(
     Apply final row-level read authorization to a bucket.
 
     When an instance gate is not required, or the manager has no Permission
-    class, the original queryset is returned with all candidates authorized.
-    Otherwise each candidate is checked with ``can_read_instance()``. Authorized
-    rows with an ``identification["id"]`` are rebuilt through an ``id__in``
-    filter; authorized rows without an id are unioned back as concrete manager
-    instances.
+    class, the original queryset is returned without eagerly computing counts.
+    Otherwise each candidate is checked with ``can_read_instance()`` and the
+    originating bucket reconstructs the exact authorized instance subset using
+    its backend-native representation.
     """
     if not requires_instance_check:
-        candidate_count = len(queryset)
         return ReadAuthorizationResult(
             queryset=queryset,
-            candidate_count=candidate_count,
-            authorized_count=candidate_count,
-            denied_count=0,
+            candidate_count=None,
+            authorized_count=None,
+            denied_count=None,
             backend_shape=backend_shape,
             requires_instance_check=False,
             instance_check_reasons=instance_check_reasons,
@@ -354,36 +384,25 @@ def filter_queryset_by_read_permission(
         general_manager_class, "Permission", None
     )
     if PermissionClass is None:
-        candidate_count = len(queryset)
         return ReadAuthorizationResult(
             queryset=queryset,
-            candidate_count=candidate_count,
-            authorized_count=candidate_count,
-            denied_count=0,
+            candidate_count=None,
+            authorized_count=None,
+            denied_count=None,
             backend_shape=backend_shape,
             requires_instance_check=False,
             instance_check_reasons=instance_check_reasons,
         )
 
-    authorized_ids: list[object] = []
     authorized_instances: list[GeneralManagerT] = []
     candidate_count = 0
     for instance in queryset:
         candidate_count += 1
         if PermissionClass(instance, info.context.user).can_read_instance():
-            identification = cast(Mapping[str, object], instance.identification)
-            instance_id = identification.get("id")
-            if instance_id is None:
-                authorized_instances.append(instance)
-            else:
-                authorized_ids.append(instance_id)
+            authorized_instances.append(instance)
 
-    authorized_queryset = (
-        queryset.filter(id__in=authorized_ids) if authorized_ids else queryset.none()
-    )
-    for instance in authorized_instances:
-        authorized_queryset = authorized_queryset | instance
-    authorized_count = len(authorized_ids) + len(authorized_instances)
+    authorized_queryset = queryset.with_instances(authorized_instances)
+    authorized_count = len(authorized_instances)
     return ReadAuthorizationResult(
         queryset=authorized_queryset,
         candidate_count=candidate_count,

{generalmanager-0.69.2 → generalmanager-0.71.0}/src/general_manager/api/graphql_search.py

@@ -382,6 +382,11 @@ def passes_permission_filters(
     """
     if permission_plan is None:
         permission_plan = get_read_permission_filter(instance.__class__, info)
+    decision = getattr(permission_plan, "decision", "conditional")
+    if decision == "allow_all":
+        return True
+    if decision == "deny_all":
+        return False
     permission_filters = permission_plan.filters
     if not permission_filters:
         return can_read_instance(instance, info)
@@ -1046,14 +1051,21 @@ def register_search_query(
         for manager_class in manager_classes:
             type_label = manager_class.__name__
             permission_plan = get_read_permission_filter(manager_class, info)
+            decision = getattr(permission_plan, "decision", "conditional")
+            if decision == "deny_all":
+                continue
             backend_shape = get_backend_shape(manager_class)
             instance_check_reasons = resolve_instance_check_reasons(
                 permission_plan,
                 backend_shape=backend_shape,
             )
-            filter_groups = merge_permission_filters(
-                parsed_filters,
-                permission_plan.filters,
+            filter_groups = (
+                parsed_filters or None
+                if decision == "allow_all"
+                else merge_permission_filters(
+                    parsed_filters,
+                    permission_plan.filters,
+                )
             )
             total_hits_for_manager = 0
             candidate_hits_for_manager = 0
@@ -1127,7 +1139,7 @@ def register_search_query(
             total += total_hits_for_manager
             if not manager_total_is_exact:
                 total_is_exact = False
-            if permission_plan.requires_instance_check:
+            if decision == "conditional" and permission_plan.requires_instance_check:
                 logger.info(
                     "graphql read authorization summary",
                     context={

{generalmanager-0.69.2 → generalmanager-0.71.0}/src/general_manager/bucket/base_bucket.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 from abc import ABC, abstractmethod
-from collections.abc import Hashable, Mapping
+from collections.abc import Hashable, Iterable, Mapping
 from typing import (
     Generator,
     TYPE_CHECKING,
@@ -437,3 +437,18 @@ class Bucket(ABC, Generic[GeneralManagerType]):
             "The 'none' method is not implemented in the base Bucket class. "
             "Subclasses should implement this method to return an empty bucket."
         )
+
+    def with_instances(
+        self,
+        instances: Iterable[GeneralManagerType],
+    ) -> Bucket[GeneralManagerType]:
+        """Return a bucket containing exactly the supplied manager instances.
+
+        Callers provide instances in source iteration order and implementations
+        retain that order. Backends may override this compatibility fallback to
+        avoid repeated unions or unsupported lookups.
+        """
+        subset = self.none()
+        for instance in instances:
+            subset = subset | instance
+        return subset

{generalmanager-0.69.2 → generalmanager-0.71.0}/src/general_manager/bucket/calculation_bucket.py

@@ -219,6 +219,7 @@ class CalculationBucket(Bucket[GeneralManagerType]):
         self._excludes = parse_filters(self.exclude_definitions, possible_values)
 
         self._data: list[Combination] | None = None
+        self._allowed_identifications: list[Combination] | None = None
         self.sort_key = sort_key
         self.reverse = reverse
         self._effective_search_date = current_as_of_date()
@@ -251,6 +252,10 @@ class CalculationBucket(Bucket[GeneralManagerType]):
             reverse,
         )
         bucket._effective_search_date = self._effective_search_date
+        if self._allowed_identifications is not None:
+            bucket._allowed_identifications = [
+                dict(identification) for identification in self._allowed_identifications
+            ]
         return bucket
 
     def __eq__(self, other: object) -> bool:
@@ -292,6 +297,7 @@ class CalculationBucket(Bucket[GeneralManagerType]):
             ),
             {
                 "data": self._data,
+                "allowed_identifications": self._allowed_identifications,
                 "effective_search_date": self._effective_search_date,
             },
         )
@@ -307,6 +313,10 @@ class CalculationBucket(Bucket[GeneralManagerType]):
             None
         """
         self._data = cast(list[Combination] | None, state.get("data"))
+        self._allowed_identifications = cast(
+            list[Combination] | None,
+            state.get("allowed_identifications"),
+        )
         self._effective_search_date = cast(
             "datetime | None", state.get("effective_search_date")
         )
@@ -360,12 +370,29 @@ class CalculationBucket(Bucket[GeneralManagerType]):
         }
 
         other._ensure_as_of_compatible()
-        return self._derive(
+        combined = self._derive(
             filter_definitions=combined_filters,
             exclude_definitions=combined_excludes,
             sort_key=None,
             reverse=False,
         )
+        if self._allowed_identifications is None:
+            if other._allowed_identifications is not None:
+                combined._allowed_identifications = [
+                    dict(identification)
+                    for identification in other._allowed_identifications
+                ]
+        elif other._allowed_identifications is not None:
+            other_allowed_keys = {
+                freeze_bucket_index_value(identification)
+                for identification in other._allowed_identifications
+            }
+            combined._allowed_identifications = [
+                dict(identification)
+                for identification in self._allowed_identifications
+                if freeze_bucket_index_value(identification) in other_allowed_keys
+            ]
+        return combined
 
     def __str__(self) -> str:
         """
@@ -431,11 +458,22 @@ class CalculationBucket(Bucket[GeneralManagerType]):
                 sorted_filters["input_excludes"],
                 snapshot_iterables=snapshot_iterables,
             )
-            if sorted_filters["prop_filters"] or sorted_filters["prop_excludes"]:
+            allowed_identification_keys = None
+            if self._allowed_identifications is not None:
+                allowed_identification_keys = {
+                    freeze_bucket_index_value(identification)
+                    for identification in self._allowed_identifications
+                }
+            if (
+                sorted_filters["prop_filters"]
+                or sorted_filters["prop_excludes"]
+                or allowed_identification_keys is not None
+            ):
                 preview_iterator = self._iter_prop_filtered_identifications(
                     preview_iterator,
                     sorted_filters["prop_filters"],
                     sorted_filters["prop_excludes"],
+                    allowed_identification_keys,
                 )
             preview = list(islice(preview_iterator, limit + 1))
 
@@ -656,6 +694,7 @@ class CalculationBucket(Bucket[GeneralManagerType]):
             self._manager_class,
             freeze_bucket_index_value(self.filter_definitions),
             freeze_bucket_index_value(self.exclude_definitions),
+            freeze_bucket_index_value(self._allowed_identifications),
             self._normalized_sort_key(),
             self.reverse,
         )
@@ -738,6 +777,21 @@ class CalculationBucket(Bucket[GeneralManagerType]):
                     sorted_filters["input_filters"],
                     sorted_filters["input_excludes"],
                 )
+                manager_combinations: list[GeneralManagerType] | None = None
+                if self._allowed_identifications is not None:
+                    allowed_identification_keys = {
+                        freeze_bucket_index_value(identification)
+                        for identification in self._allowed_identifications
+                    }
+                    manager_combinations = [
+                        manager
+                        for manager in self._manager_combinations(current_combinations)
+                        if freeze_bucket_index_value(manager.identification)
+                        in allowed_identification_keys
+                    ]
+                    current_combinations = self._manager_identifications(
+                        manager_combinations
+                    )
                 sort_key = self._normalized_sort_key()
                 needs_manager_access = (
                     bool(sorted_filters["prop_filters"])
@@ -746,9 +800,10 @@ class CalculationBucket(Bucket[GeneralManagerType]):
                 )
 
                 if needs_manager_access:
-                    manager_combinations = self._manager_combinations(
-                        current_combinations
-                    )
+                    if manager_combinations is None:
+                        manager_combinations = self._manager_combinations(
+                            current_combinations
+                        )
                     manager_combinations = self._filter_prop_combinations(
                         manager_combinations,
                         sorted_filters["prop_filters"],
@@ -1006,6 +1061,7 @@ class CalculationBucket(Bucket[GeneralManagerType]):
         combinations: Iterable[Combination],
         prop_filters: ParsedFilters,
         prop_excludes: ParsedFilters,
+        allowed_identification_keys: set[Hashable] | None = None,
     ) -> Generator[Combination, None, None]:
         """
         Lazily apply property filters and yield manager identifications.
@@ -1016,6 +1072,12 @@ class CalculationBucket(Bucket[GeneralManagerType]):
         """
         for combo in combinations:
             manager = self._manager_class(**combo)
+            if (
+                allowed_identification_keys is not None
+                and freeze_bucket_index_value(manager.identification)
+                not in allowed_identification_keys
+            ):
+                continue
             if self._filter_prop_combinations([manager], prop_filters, prop_excludes):
                 yield manager.identification
 
@@ -1222,4 +1284,32 @@ class CalculationBucket(Bucket[GeneralManagerType]):
         own.exclude_definitions = {}
         own._filters = {}
         own._excludes = {}
+        own._allowed_identifications = []
         return own
+
+    def with_instances(
+        self,
+        instances: Iterable[GeneralManagerType],
+    ) -> CalculationBucket[GeneralManagerType]:
+        """Return a materialized subset using declared input identifications."""
+        self._ensure_as_of_compatible()
+        from general_manager.manager.general_manager import GeneralManager
+
+        identifications: list[Combination] = []
+        for instance in instances:
+            if instance.__class__ != self._manager_class:
+                raise IncompatibleBucketTypeError(self.__class__, type(instance))
+            if isinstance(instance, GeneralManager):
+                instance._ensure_as_of_compatible()
+            identifications.append(dict(instance.identification))
+        subset = self._derive(
+            filter_definitions=self.filter_definitions.copy(),
+            exclude_definitions=self.exclude_definitions.copy(),
+            sort_key=self.sort_key,
+            reverse=self.reverse,
+        )
+        subset._allowed_identifications = [
+            dict(identification) for identification in identifications
+        ]
+        subset._data = identifications
+        return subset

{generalmanager-0.69.2 → generalmanager-0.71.0}/src/general_manager/bucket/database_bucket.py

@@ -1,7 +1,7 @@
 """Database-backed bucket implementation for GeneralManager collections."""
 
 from __future__ import annotations
-from collections.abc import Callable, Hashable, Mapping
+from collections.abc import Callable, Hashable, Iterable, Mapping
 from datetime import date, datetime
 from typing import TYPE_CHECKING, Generator, TypeVar, cast
 
@@ -1533,3 +1533,19 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         own._query_signature_cache = _QUERY_SIGNATURE_NOT_COMPUTED
         own._trusted_query_signature = None
         return own
+
+    def with_instances(
+        self,
+        instances: Iterable[GeneralManagerType],
+    ) -> DatabaseBucket[GeneralManagerType]:
+        """Return a source-ordered subset selected by manager primary keys."""
+        self._ensure_as_of_compatible()
+        ids: list[object] = []
+        for instance in instances:
+            if not isinstance(instance, GeneralManager) or (
+                instance.__class__ != self._manager_class
+            ):
+                raise DatabaseBucketTypeMismatchError(self.__class__, type(instance))
+            instance._ensure_as_of_compatible()
+            ids.append(instance.identification["id"])
+        return self.filter(id__in=ids) if ids else self.none()

{generalmanager-0.69.2 → generalmanager-0.71.0}/src/general_manager/bucket/request_bucket.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Generator, Hashable, Mapping
+from collections.abc import Generator, Hashable, Iterable, Mapping
 from typing import TYPE_CHECKING, Protocol, cast
 
 from general_manager.bucket.base_bucket import Bucket, GeneralManagerType
@@ -452,6 +452,17 @@ class RequestBucket(Bucket[GeneralManagerType]):
         """Return an empty materialized bucket preserving the operation name."""
         return self._from_items(tuple())
 
+    def with_instances(
+        self,
+        instances: Iterable[GeneralManagerType],
+    ) -> "RequestBucket[GeneralManagerType]":
+        """Return a materialized subset without re-executing the request plan."""
+        items = tuple(instances)
+        for instance in items:
+            if not isinstance(instance, self._manager_class):
+                raise RequestBucketTypeMismatchError(self.__class__, type(instance))
+        return self._from_items(items)
+
     @property
     def operation_name(self) -> str:
         """Return the query operation name preserved on this bucket.