GeneralManager 0.69.2__tar.gz → 0.70.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.69.2
+Version: 0.70.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.70.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.69.2
+Version: 0.70.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.70.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.70.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.70.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,
     )
 
+    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 = queryset
-    if not permission_plan.requires_instance_check and permission_plan.filters == [
-        {"filter": {}, "exclude": {}}
-    ]:
-        candidate_count = len(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,
@@ -332,19 +361,18 @@ 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.
+    class, the original queryset is returned without eagerly computing counts.
     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.
     """
     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,12 +382,11 @@ 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,

{generalmanager-0.69.2 → generalmanager-0.70.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.70.0}/src/general_manager/permission/base_permission.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Collection, Mapping
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Literal, TypeAlias, TypedDict, cast
 
@@ -16,7 +16,10 @@ from general_manager.permission.audit import (
     audit_logging_enabled,
     emit_permission_audit_event,
 )
-from general_manager.permission.permission_checks import permission_functions
+from general_manager.permission.permission_checks import (
+    PermissionFilterDecision,
+    permission_functions,
+)
 from general_manager.permission.permission_data_manager import PermissionDataManager
 from general_manager.permission.utils import (
     PermissionNotFoundError,
@@ -33,9 +36,15 @@ UserLike: TypeAlias = AbstractBaseUser | AnonymousUser
 ReadPermissionReason: TypeAlias = Literal[
     "unfilterable_read_rule",
     "based_on_class_context",
+    "compound_exclude_semantics",
     "filter_key_conflict",
     "no_prefilter_backend",
 ]
+ReadPermissionDecision: TypeAlias = Literal[
+    "allow_all",
+    "deny_all",
+    "conditional",
+]
 
 
 class PermissionConstraint(TypedDict, total=False):
@@ -98,6 +107,9 @@ class ReadPermissionPlan:
     least one read rule could not be converted into a backend prefilter.
     ``"based_on_class_context"`` means delegated permission logic required
     class-level context that cannot be represented as a row prefilter.
+    ``"compound_exclude_semantics"`` means multiple ANDed exclusion predicates
+    were conservatively merged into one safe prefilter but require row-level
+    authorization to preserve sequential exclusion semantics.
     ``"filter_key_conflict"`` means generated filter keys conflicted while
     composing permission filters. ``"no_prefilter_backend"`` means the interface
     backend cannot enforce read prefilters fully. Reason tuples are request
@@ -106,11 +118,19 @@ class ReadPermissionPlan:
     ``requires_instance_check=False`` should normally use an empty reasons tuple.
     Non-empty reasons in that state are diagnostic only and do not force an
     instance check by themselves.
+
+    ``decision`` describes the complete read authorization outcome.
+    ``"allow_all"`` and ``"deny_all"`` are definitive and therefore use no
+    prefilters or instance check. ``"conditional"`` means authorization still
+    depends on the listed row constraints, an instance check, or both. The
+    default remains conditional so legacy constructors retain their safe
+    behavior.
     """
 
     filters: list[PermissionConstraint]
     requires_instance_check: bool = True
     instance_check_reasons: tuple[ReadPermissionReason, ...] = ()
+    decision: ReadPermissionDecision = "conditional"
 
 
 class PermissionCheckError(PermissionError):
@@ -131,6 +151,29 @@ class PermissionCheckError(PermissionError):
         )
 
 
+class _InvalidPermissionFilterResultError(TypeError):
+    """Raised when a registered read-filter callback returns an invalid shape."""
+
+    def __init__(
+        self,
+        permission: str,
+        result: object,
+        *,
+        part_name: str | None = None,
+        unsupported_keys: Collection[object] | None = None,
+    ) -> None:
+        if unsupported_keys:
+            rendered_keys = ", ".join(sorted(repr(key) for key in unsupported_keys))
+            detail = f"unsupported constraint keys: {rendered_keys}"
+        elif part_name is None:
+            detail = f"unsupported {type(result).__name__}"
+        else:
+            detail = f"a non-mapping '{part_name}' constraint"
+        super().__init__(
+            f"Permission filter for fragment '{permission}' returned {detail}."
+        )
+
+
 class BasePermission(ABC):
     """Abstract base class defining CRUD permission checks for managers."""
 
@@ -604,25 +647,67 @@ class BasePermission(ABC):
             PermissionConstraint: A mapping with optional ``"filter"`` and
             ``"exclude"`` dictionaries whose lookup values are typed as
             ``object``. Superusers and unfilterable permissions that return
-            ``None`` both resolve to empty ``filter`` and ``exclude`` mappings.
+            ``None`` or a static decision both resolve to empty ``filter`` and
+            ``exclude`` mappings.
 
         Raises:
             PermissionNotFoundError: If no permission function matches the leading name in `permission`.
         """
-        if self._is_superuser():
+        permission_filter = self._get_permission_filter_result(permission)
+        if permission_filter is None or isinstance(
+            permission_filter, PermissionFilterDecision
+        ):
             return {"filter": {}, "exclude": {}}
+        return permission_filter
+
+    def _get_permission_filter_result(
+        self,
+        permission: str,
+    ) -> PermissionConstraint | PermissionFilterDecision | None:
+        """Resolve and normalize one permission-filter callback result.
+
+        Static decisions and ``None`` are preserved for read-plan composition.
+        Mapping results are copied into plain constraint dictionaries. Invalid
+        callback results fail here so query planning never accidentally treats
+        them as authorization constraints.
+        """
+        if self._is_superuser():
+            return PermissionFilterDecision.ALLOW_ALL
         permission_function, *config = permission.split(":")
         if permission_function not in permission_functions:
             raise PermissionNotFoundError(permission)
-        permission_filter = cast(
-            PermissionConstraint | None,
-            permission_functions[permission_function]["permission_filter"](
-                self.request_user, config
-            ),
+        result: object = permission_functions[permission_function]["permission_filter"](
+            self.request_user,
+            config,
         )
-        if permission_filter is None:
-            return {"filter": {}, "exclude": {}}
-        return permission_filter
+        if result is None or isinstance(result, PermissionFilterDecision):
+            return result
+        if not isinstance(result, Mapping):
+            raise _InvalidPermissionFilterResultError(permission, result)
+        unsupported_keys = set(result).difference(("filter", "exclude"))
+        if unsupported_keys:
+            raise _InvalidPermissionFilterResultError(
+                permission,
+                result,
+                unsupported_keys=unsupported_keys,
+            )
+
+        constraint: PermissionConstraint = {}
+        for part_name in ("filter", "exclude"):
+            if part_name not in result:
+                continue
+            part = result[part_name]
+            if not isinstance(part, Mapping):
+                raise _InvalidPermissionFilterResultError(
+                    permission,
+                    result,
+                    part_name=part_name,
+                )
+            if part_name == "filter":
+                constraint["filter"] = dict(part)
+            else:
+                constraint["exclude"] = dict(part)
+        return constraint
 
     def _get_permission_filter_info(
         self, permission: str
@@ -631,8 +716,9 @@ class BasePermission(ABC):
         Resolve filter/exclude constraints and whether the permission is query-filterable.
 
         Superusers return empty filter/exclude mappings marked filterable. When
-        a permission filter returns ``None``, empty mappings are returned with
-        ``False`` to signal that callers must keep a row-level instance check.
+        a permission filter returns ``None`` or a static decision, empty
+        mappings are returned with ``False`` to signal that callers must keep
+        a row-level instance check until static decisions are planned directly.
 
         Returns:
             ``(constraint, is_filterable)``.
@@ -641,18 +727,10 @@ class BasePermission(ABC):
             PermissionNotFoundError: If no registered permission function
                 matches the leading permission name.
         """
-        if self._is_superuser():
-            return {"filter": {}, "exclude": {}}, True
-        permission_function, *config = permission.split(":")
-        if permission_function not in permission_functions:
-            raise PermissionNotFoundError(permission)
-        permission_filter = cast(
-            PermissionConstraint | None,
-            permission_functions[permission_function]["permission_filter"](
-                self.request_user, config
-            ),
-        )
-        if permission_filter is None:
+        permission_filter = self._get_permission_filter_result(permission)
+        if permission_filter is None or isinstance(
+            permission_filter, PermissionFilterDecision
+        ):
             return {"filter": {}, "exclude": {}}, False
         return permission_filter, True