GeneralManager 0.17.0__py3-none-any.whl → 0.19.0__py3-none-any.whl

general_manager/api/graphql.py

@@ -16,6 +16,7 @@ from typing import (
     Any,
     AsyncIterator,
     Callable,
+    ClassVar,
     Generator,
     Iterable,
     TYPE_CHECKING,
@@ -28,7 +29,12 @@ from typing import (
 
 import graphene  # type: ignore[import]
 from graphql.language import ast
-from graphql.language.ast import FieldNode, FragmentSpreadNode, InlineFragmentNode, SelectionSetNode
+from graphql.language.ast import (
+    FieldNode,
+    FragmentSpreadNode,
+    InlineFragmentNode,
+    SelectionSetNode,
+)
 from asgiref.sync import async_to_sync
 from channels.layers import BaseChannelLayer, get_channel_layer
 
@@ -58,6 +64,87 @@ class SubscriptionEvent:
     action: str
 
 
+class InvalidMeasurementValueError(TypeError):
+    """Raised when a scalar receives a value that is not a Measurement instance."""
+
+    def __init__(self, value: object) -> None:
+        """
+        Initialize the error raised when a scalar value is not a Measurement instance.
+
+        Parameters:
+            value (object): The value that failed validation; its type name is included in the exception message.
+        """
+        super().__init__(f"Expected Measurement, got {type(value).__name__}.")
+
+
+class MissingChannelLayerError(RuntimeError):
+    """Raised when GraphQL subscriptions run without a configured channel layer."""
+
+    def __init__(self) -> None:
+        """
+        Indicates that Django Channels channel layer is not configured for GraphQL subscriptions.
+
+        Raised when subscription functionality requires a configured channel layer (e.g., CHANNEL_LAYERS) but none is present.
+        """
+        super().__init__(
+            "No channel layer configured. Configure CHANNEL_LAYERS to enable GraphQL subscriptions."
+        )
+
+
+class UnsupportedGraphQLFieldTypeError(TypeError):
+    """Raised when attempting to map an unsupported Python type to GraphQL."""
+
+    def __init__(self, field_type: type) -> None:
+        """
+        Exception raised when a Python `dict` type is encountered while mapping a field to GraphQL, which is not supported.
+
+        Parameters:
+            field_type (type): The offending Python type that was provided for the field. The exception message includes this type's `__name__`.
+        """
+        super().__init__(
+            f"GraphQL does not support dict fields (received {field_type.__name__})."
+        )
+
+
+class InvalidGeneralManagerClassError(TypeError):
+    """Raised when a non-GeneralManager subclass is used in the GraphQL registry."""
+
+    def __init__(self, received_class: type) -> None:
+        """
+        Initialize the exception indicating the provided class is not a GeneralManager subclass.
+
+        Parameters:
+            received_class (type): The class that was supplied but is not a subclass of GeneralManager.
+        """
+        super().__init__(
+            f"{received_class.__name__} must be a subclass of GeneralManager to create a GraphQL interface."
+        )
+
+
+class MissingManagerIdentifierError(ValueError):
+    """Raised when a GraphQL mutation is missing the required manager identifier."""
+
+    def __init__(self) -> None:
+        """
+        Initialize the exception indicating a required manager identifier is missing.
+
+        This exception instance carries the default message "id is required.".
+        """
+        super().__init__("id is required.")
+
+
+HANDLED_MANAGER_ERRORS: tuple[type[Exception], ...] = (
+    PermissionError,
+    ValidationError,
+    ValueError,
+    LookupError,
+    TypeError,
+    AttributeError,
+    GraphQLError,
+    RuntimeError,
+)
+
+
 class MeasurementType(graphene.ObjectType):
     value = graphene.Float()
     unit = graphene.String()
@@ -70,8 +157,20 @@ class MeasurementScalar(graphene.Scalar):
 
     @staticmethod
     def serialize(value: Measurement) -> str:
+        """
+        Convert a Measurement to its string representation.
+
+        Parameters:
+            value (Measurement): Measurement to serialize.
+
+        Returns:
+            str: String representation of the given Measurement.
+
+        Raises:
+            InvalidMeasurementValueError: If `value` is not a Measurement instance.
+        """
         if not isinstance(value, Measurement):
-            raise TypeError(f"Expected Measurement, got {type(value)}")
+            raise InvalidMeasurementValueError(value)
         return str(value)
 
     @staticmethod
@@ -98,11 +197,11 @@ def getReadPermissionFilter(
 ) -> list[tuple[dict[str, Any], dict[str, Any]]]:
     """
     Produce a list of permission-derived filter and exclude mappings for queries against a manager class.
-    
+
     Parameters:
         generalManagerClass (Type[GeneralManager]): Manager class to derive permission filters for.
         info (GraphQLResolveInfo): GraphQL resolver info whose context provides the current user.
-    
+
     Returns:
         list[tuple[dict[str, Any], dict[str, Any]]]: A list of `(filter, exclude)` tuples where each `filter` and `exclude` is a mapping of query constraints produced by the manager's Permission class.
     """
@@ -124,45 +223,43 @@ def getReadPermissionFilter(
 class GraphQL:
     """Static helper that builds GraphQL types, queries, and mutations for managers."""
 
-    _query_class: type[graphene.ObjectType] | None = None
-    _mutation_class: type[graphene.ObjectType] | None = None
-    _subscription_class: type[graphene.ObjectType] | None = None
-    _mutations: dict[str, Any] = {}
-    _query_fields: dict[str, Any] = {}
-    _subscription_fields: dict[str, Any] = {}
-    _page_type_registry: dict[str, type[graphene.ObjectType]] = {}
-    _subscription_payload_registry: dict[str, type[graphene.ObjectType]] = {}
-    graphql_type_registry: dict[str, type] = {}
-    graphql_filter_type_registry: dict[str, type] = {}
-    manager_registry: dict[str, type[GeneralManager]] = {}
-    _schema: graphene.Schema | None = None
+    _query_class: ClassVar[type[graphene.ObjectType] | None] = None
+    _mutation_class: ClassVar[type[graphene.ObjectType] | None] = None
+    _subscription_class: ClassVar[type[graphene.ObjectType] | None] = None
+    _mutations: ClassVar[dict[str, Any]] = {}
+    _query_fields: ClassVar[dict[str, Any]] = {}
+    _subscription_fields: ClassVar[dict[str, Any]] = {}
+    _page_type_registry: ClassVar[dict[str, type[graphene.ObjectType]]] = {}
+    _subscription_payload_registry: ClassVar[dict[str, type[graphene.ObjectType]]] = {}
+    graphql_type_registry: ClassVar[dict[str, type]] = {}
+    graphql_filter_type_registry: ClassVar[dict[str, type]] = {}
+    manager_registry: ClassVar[dict[str, type[GeneralManager]]] = {}
+    _schema: ClassVar[graphene.Schema | None] = None
 
     @staticmethod
     def _get_channel_layer(strict: bool = False) -> BaseChannelLayer | None:
         """
-        Return the configured channel layer used for GraphQL subscriptions.
-        
+        Retrieve the configured channel layer for GraphQL subscriptions.
+
         Parameters:
-        	strict (bool): If True, raise an error when no channel layer is configured.
-        
+            strict (bool): When True, raise MissingChannelLayerError if no channel layer is configured.
+
         Returns:
-        	BaseChannelLayer | None: The channel layer instance if configured, otherwise `None`.
-        
+            BaseChannelLayer | None: The configured channel layer instance if available, otherwise None.
+
         Raises:
-        	RuntimeError: If `strict` is True and no channel layer is configured.
+            MissingChannelLayerError: If `strict` is True and no channel layer is configured.
         """
         layer = cast(BaseChannelLayer | None, get_channel_layer())
         if layer is None and strict:
-            raise RuntimeError(
-                "No channel layer configured. Configure CHANNEL_LAYERS to enable GraphQL subscriptions."
-            )
+            raise MissingChannelLayerError()
         return layer
 
     @classmethod
     def get_schema(cls) -> graphene.Schema | None:
         """
         Get the currently configured Graphene schema for the GraphQL registry.
-        
+
         Returns:
             The active `graphene.Schema` instance, or `None` if no schema has been created.
         """
@@ -173,14 +270,14 @@ class GraphQL:
         manager_class: type[GeneralManager], identification: dict[str, Any]
     ) -> str:
         """
-        Build a consistent channel group name for subscriptions tied to a manager and its identification.
-        
+        Builds a deterministic channel group name for subscription events for a specific manager instance.
+
         Parameters:
-        	manager_class (type[GeneralManager]): Manager class used to namespace the group.
-        	identification (dict[str, Any]): Mapping of identifying fields for a manager instance; will be JSON-normalized and included in the group name.
-        
+            manager_class (type[GeneralManager]): GeneralManager subclass used to namespace the group.
+            identification (dict[str, Any]): Identifying fields for the manager instance; the mapping is JSON-normalized (sorted keys) before being incorporated.
+
         Returns:
-        	group_name (str): A deterministic string usable as a channel group identifier for subscription events.
+            group_name (str): A deterministic channel group identifier derived from the manager class and normalized identification.
         """
         normalized = json.dumps(identification, sort_keys=True, default=str)
         digest = hashlib.sha256(
@@ -198,17 +295,19 @@ class GraphQL:
     ) -> None:
         """
         Listen to a channel layer for "gm.subscription.event" messages and enqueue their `action` values.
-        
+
         Continuously receives messages from the given channel_name on the channel_layer, and when a message of type "gm.subscription.event" contains an `action`, that action string is put into the provided asyncio queue. Ignores messages of other types. The loop exits silently when the task is cancelled.
-        
+
         Parameters:
-        	channel_layer (BaseChannelLayer): Channel layer to receive messages from.
-        	channel_name (str): Name of the channel to listen on.
-        	queue (asyncio.Queue[str]): Async queue to which received action strings will be enqueued.
+                channel_layer (BaseChannelLayer): Channel layer to receive messages from.
+                channel_name (str): Name of the channel to listen on.
+                queue (asyncio.Queue[str]): Async queue to which received action strings will be enqueued.
         """
         try:
             while True:
-                message = cast(dict[str, Any], await channel_layer.receive(channel_name))
+                message = cast(
+                    dict[str, Any], await channel_layer.receive(channel_name)
+                )
                 if message.get("type") != "gm.subscription.event":
                     continue
                 action = cast(str | None, message.get("action"))
@@ -220,12 +319,12 @@ class GraphQL:
     @classmethod
     def createGraphqlMutation(cls, generalManagerClass: type[GeneralManager]) -> None:
         """
-        Register create, update, and delete GraphQL mutations for a manager class when its Interface overrides the default CRUD methods.
-        
-        For each of `create`, `update`, and `deactivate` that is implemented on the manager's `Interface` (i.e., differs from InterfaceBase), this method generates a corresponding mutation class and stores it on the class-level mutation registry (`cls._mutations`) under the names `create<ManagerName>`, `update<ManagerName>`, and `delete<ManagerName>`. The generated mutations return a `success` flag and the created/updated/deactivated object field keyed by the manager class name.
-        
+        Register GraphQL mutation classes for a GeneralManager based on its Interface.
+
+        If the manager's Interface overrides the default `create`, `update`, or `deactivate` methods, corresponding mutation classes are generated and stored in the class-level mutation registry under the names `create<ManagerName>`, `update<ManagerName>`, and `delete<ManagerName>`. Each generated mutation exposes a `success` flag and a field named for the manager class that returns the created/updated/deactivated object.
+
         Parameters:
-            generalManagerClass (type[GeneralManager]): Manager class whose `Interface` drives which mutations are generated and registered.
+            generalManagerClass (type[GeneralManager]): Manager class whose `Interface` determines which mutations are generated and registered.
         """
 
         interface_cls: InterfaceBase | None = getattr(
@@ -262,9 +361,9 @@ class GraphQL:
     def createGraphqlInterface(cls, generalManagerClass: Type[GeneralManager]) -> None:
         """
         Create and register a Graphene ObjectType for a GeneralManager class and expose its queries and subscription.
-        
+
         Builds a Graphene type by mapping the manager's Interface attributes and GraphQLProperties to Graphene fields and resolvers, registers the resulting type and manager in the GraphQL registries, and adds corresponding query and subscription fields to the schema.
-        
+
         Parameters:
             generalManagerClass (Type[GeneralManager]): The manager class whose Interface and GraphQLProperties are used to generate Graphene fields and resolvers.
         """
@@ -337,7 +436,7 @@ class GraphQL:
     ) -> type[graphene.Enum] | None:
         """
         Builds an enum of sortable field names for the given manager class.
-        
+
         Returns:
             An Enum type whose members are the sortable field names for the manager, or `None` if no sortable fields exist.
         """
@@ -376,7 +475,9 @@ class GraphQL:
         )
 
     @staticmethod
-    def _getFilterOptions(attribute_type: type, attribute_name: str) -> Generator[
+    def _getFilterOptions(
+        attribute_type: type, attribute_name: str
+    ) -> Generator[
         tuple[
             str, type[graphene.ObjectType] | MeasurementScalar | graphene.List | None
         ],
@@ -384,14 +485,18 @@ class GraphQL:
         None,
     ]:
         """
-        Yield filter field names and Graphene types for a given attribute.
+        Produce filter field names and corresponding Graphene input types for a given attribute.
 
         Parameters:
-            attribute_type (type): Python type declared for the attribute.
-            attribute_name (str): Name of the attribute.
+            attribute_type (type): The Python type declared for the attribute.
+            attribute_name (str): The attribute's name used as the base for generated filter field names.
 
         Yields:
-            tuple[str, Graphene type | None]: Filter name and corresponding Graphene type.
+            tuple[str, type | MeasurementScalar | graphene.List | None]:
+                A pair where the first element is a filter field name (e.g., "age", "price__gte",
+                "name__icontains") and the second element is the Graphene input type for that filter
+                or `None` when no Graphene input type should be exposed (for example, nested
+                GeneralManager references).
         """
         number_options = ["exact", "gt", "gte", "lt", "lte"]
         string_options = [
@@ -410,13 +515,19 @@ class GraphQL:
             for option in number_options:
                 yield f"{attribute_name}__{option}", MeasurementScalar()
         else:
-            yield attribute_name, GraphQL._mapFieldToGrapheneRead(
-                attribute_type, attribute_name
+            yield (
+                attribute_name,
+                GraphQL._mapFieldToGrapheneRead(attribute_type, attribute_name),
             )
             if issubclass(attribute_type, (int, float, Decimal, date, datetime)):
                 for option in number_options:
-                    yield f"{attribute_name}__{option}", (
-                        GraphQL._mapFieldToGrapheneRead(attribute_type, attribute_name)
+                    yield (
+                        f"{attribute_name}__{option}",
+                        (
+                            GraphQL._mapFieldToGrapheneRead(
+                                attribute_type, attribute_name
+                            )
+                        ),
                     )
             elif issubclass(attribute_type, str):
                 base_type = GraphQL._mapFieldToGrapheneBaseType(attribute_type)
@@ -424,10 +535,13 @@ class GraphQL:
                     if option == "in":
                         yield f"{attribute_name}__in", graphene.List(base_type)
                     else:
-                        yield f"{attribute_name}__{option}", (
-                            GraphQL._mapFieldToGrapheneRead(
-                                attribute_type, attribute_name
-                            )
+                        yield (
+                            f"{attribute_name}__{option}",
+                            (
+                                GraphQL._mapFieldToGrapheneRead(
+                                    attribute_type, attribute_name
+                                )
+                            ),
                         )
 
     @staticmethod
@@ -436,12 +550,12 @@ class GraphQL:
     ) -> type[graphene.InputObjectType] | None:
         """
         Create a Graphene InputObjectType that exposes available filter fields for a GeneralManager subclass.
-        
+
         Builds filter fields from the manager's Interface attributes and any GraphQLProperty marked filterable. Returns None when no filterable fields are found.
-        
+
         Parameters:
             field_type (Type[GeneralManager]): Manager class whose Interface and GraphQLProperties determine the filter fields.
-        
+
         Returns:
             type[graphene.InputObjectType] | None: Generated InputObjectType class for filters, or `None` if no filter fields are applicable.
         """
@@ -502,7 +616,7 @@ class GraphQL:
             return graphene.Field(MeasurementType, target_unit=graphene.String())
         elif issubclass(field_type, GeneralManager):
             if field_name.endswith("_list"):
-                attributes = {
+                attributes: dict[str, Any] = {
                     "reverse": graphene.Boolean(),
                     "page": graphene.Int(),
                     "page_size": graphene.Int(),
@@ -532,29 +646,37 @@ class GraphQL:
     @staticmethod
     def _mapFieldToGrapheneBaseType(field_type: type) -> Type[Any]:
         """
-        Map a Python type to the corresponding Graphene scalar/class.
+        Map a Python interface type to the corresponding Graphene scalar or custom scalar.
 
         Parameters:
-            field_type (type): Python type declared on the interface.
+            field_type (type): Python type from the interface to map.
 
         Returns:
-            Type[Any]: Graphene scalar or type implementing the field.
+            Type[Any]: The Graphene scalar or custom scalar type used to represent the input type (e.g., graphene.String, graphene.Int, MeasurementScalar).
+
+        Raises:
+            UnsupportedGraphQLFieldTypeError: If `field_type` is `dict`, which is not supported for GraphQL mapping.
         """
-        if issubclass(field_type, dict):
-            raise TypeError("GraphQL does not support dict fields")
-        if issubclass(field_type, str):
+        base_type = (
+            get_origin(field_type) or field_type
+        )  # Handle typing generics safely.
+        if not isinstance(base_type, type):
             return graphene.String
-        elif issubclass(field_type, bool):
+        if issubclass(base_type, dict):
+            raise UnsupportedGraphQLFieldTypeError(field_type)
+        if issubclass(base_type, str):
+            return graphene.String
+        elif issubclass(base_type, bool):
             return graphene.Boolean
-        elif issubclass(field_type, int):
+        elif issubclass(base_type, int):
             return graphene.Int
-        elif issubclass(field_type, (float, Decimal)):
+        elif issubclass(base_type, (float, Decimal)):
             return graphene.Float
-        elif issubclass(field_type, datetime):
+        elif issubclass(base_type, datetime):
             return graphene.DateTime
-        elif issubclass(field_type, date):
+        elif issubclass(base_type, date):
             return graphene.Date
-        elif issubclass(field_type, Measurement):
+        elif issubclass(base_type, Measurement):
             return MeasurementScalar
         else:
             return graphene.String
@@ -562,20 +684,22 @@ class GraphQL:
     @staticmethod
     def _parseInput(input_val: dict[str, Any] | str | None) -> dict[str, Any]:
         """
-        Normalise filter/exclude input into a dictionary.
+        Normalize a filter or exclude input into a dictionary.
+
+        Accepts a dict, a JSON-encoded string, or None. If given None or an invalid JSON string, returns an empty dict.
 
         Parameters:
-            input_val (dict[str, Any] | str | None): Raw filter/exclude value.
+            input_val: Filter or exclude input provided as a dict, a JSON-encoded string, or None.
 
         Returns:
-            dict[str, Any]: Parsed dictionary suitable for queryset filtering.
+            dict: Mapping of filter keys to values; empty dict if input is None or invalid JSON.
         """
         if input_val is None:
             return {}
         if isinstance(input_val, str):
             try:
                 return json.loads(input_val)
-            except Exception:
+            except (json.JSONDecodeError, ValueError):
                 return {}
         return input_val
 
@@ -697,6 +821,8 @@ class GraphQL:
                 A dictionary containing the paginated items under "items" and pagination metadata under "pageInfo".
             """
             base_queryset = base_getter(self)
+            if base_queryset is None:
+                base_queryset = fallback_manager_class.all()
             # use _manager_class from the attribute if available, otherwise fallback
             manager_class = getattr(
                 base_queryset, "_manager_class", fallback_manager_class
@@ -826,16 +952,16 @@ class GraphQL:
     ) -> type[graphene.ObjectType]:
         """
         Provide or retrieve a GraphQL ObjectType that represents a paginated page for the given item type.
-        
+
         Creates and caches a GraphQL ObjectType with two fields:
         - `items`: a required list of the provided item type.
         - `pageInfo`: a required PageInfo object containing pagination metadata.
-        
+
         Parameters:
             page_type_name (str): The name to use for the generated GraphQL ObjectType.
             item_type (type[graphene.ObjectType] | Callable[[], type[graphene.ObjectType]]):
                 The Graphene ObjectType used for items, or a zero-argument callable that returns it (to support forward references).
-        
+
         Returns:
             type[graphene.ObjectType]: A Graphene ObjectType with `items` and `pageInfo` fields.
         """
@@ -855,16 +981,21 @@ class GraphQL:
         cls, generalManagerClass: Type[GeneralManager]
     ) -> dict[str, Any]:
         """
-        Builds GraphQL arguments required to uniquely identify an instance of the given manager class.
-        
+        Build the GraphQL arguments required to uniquely identify an instance of the given manager class.
+
+        For each input field defined on the manager's Interface: use "<name>_id" as a required ID argument for fields that reference another GeneralManager, use "id" as a required ID argument when present, and map other fields to their corresponding Graphene base type marked required.
+
         Parameters:
-            generalManagerClass (Type[GeneralManager]): Manager class whose Interface.input_fields are used to derive identification arguments.
-        
+            generalManagerClass: GeneralManager subclass whose Interface.input_fields are used to derive identification arguments.
+
         Returns:
-            dict[str, Any]: Mapping from argument name to a Graphene argument/field. Fields for related manager inputs use "<name>_id" as an ID, the "id" input uses an ID, and other inputs are mapped to appropriate Graphene read fields with `required=True`.
+            dict[str, Any]: Mapping of argument name to a Graphene Argument suitable for identifying a single manager instance.
         """
-        identification_fields: dict[str, graphene.Argument] = {}
-        for input_field_name, input_field in generalManagerClass.Interface.input_fields.items():
+        identification_fields: dict[str, Any] = {}
+        for (
+            input_field_name,
+            input_field,
+        ) in generalManagerClass.Interface.input_fields.items():
             if issubclass(input_field.type, GeneralManager):
                 key = f"{input_field_name}_id"
                 identification_fields[key] = graphene.Argument(
@@ -887,25 +1018,23 @@ class GraphQL:
     ) -> None:
         """
         Registers list and detail GraphQL query fields for the given manager type into the class query registry.
-        
+
         Parameters:
             graphene_type (type): The Graphene ObjectType that represents the manager's GraphQL type.
             generalManagerClass (Type[GeneralManager]): The GeneralManager subclass to expose via queries.
-        
+
         Raises:
             TypeError: If `generalManagerClass` is not a subclass of GeneralManager.
         """
         if not issubclass(generalManagerClass, GeneralManager):
-            raise TypeError(
-                "generalManagerClass must be a subclass of GeneralManager to create a GraphQL interface"
-            )
+            raise InvalidGeneralManagerClassError(generalManagerClass)
 
         if not hasattr(cls, "_query_fields"):
             cls._query_fields = cast(dict[str, Any], {})
 
         # resolver and field for the list query
         list_field_name = f"{generalManagerClass.__name__.lower()}_list"
-        attributes = {
+        attributes: dict[str, Any] = {
             "reverse": graphene.Boolean(),
             "page": graphene.Int(),
             "page_size": graphene.Int(),
@@ -924,9 +1053,16 @@ class GraphQL:
         )
         list_field = graphene.Field(page_type, **attributes)
 
-        list_resolver = cls._createListResolver(
-            lambda self: generalManagerClass.all(), generalManagerClass
-        )
+        def _all_items(_: Any) -> Any:
+            """
+            Return all instances for the associated GeneralManager class.
+
+            Returns:
+                All instances for the associated GeneralManager class, typically provided as a Bucket/QuerySet-like iterable.
+            """
+            return generalManagerClass.all()
+
+        list_resolver = cls._createListResolver(_all_items, generalManagerClass)
         cls._query_fields[list_field_name] = list_field
         cls._query_fields[f"resolve_{list_field_name}"] = list_resolver
 
@@ -939,13 +1075,13 @@ class GraphQL:
             self: GeneralManager, info: GraphQLResolveInfo, **identification: dict
         ) -> GeneralManager:
             """
-            Resolve a single manager instance from provided identification arguments.
-            
+            Instantiate and return a GeneralManager for the provided identification arguments.
+
             Parameters:
-                identification (dict): Mapping of identification argument names to their values; used as keyword arguments when instantiating the manager.
-            
+                identification (dict): Mapping of identification argument names to values passed to the manager constructor.
+
             Returns:
-                GeneralManager: The instantiated manager corresponding to the given identification.
+                GeneralManager: The manager instance identified by the provided arguments.
             """
             return generalManagerClass(**identification)
 
@@ -958,9 +1094,9 @@ class GraphQL:
     ) -> None:
         """
         Eagerly evaluate GraphQLProperty attributes on a manager instance to capture dependency metadata.
-        
+
         When GraphQLProperty descriptors are accessed they may record dependency information on the instance; this function forces those properties to be read so their dependency tracking is populated. If `property_names` is provided, only those property names that exist on the Interface are evaluated; otherwise all GraphQLProperties from the Interface are evaluated.
-        
+
         Parameters:
             instance (GeneralManager): The manager instance whose GraphQLProperty attributes should be evaluated.
             property_names (Iterable[str] | None): Optional iterable of property names to evaluate. Names not present in the Interface's GraphQLProperties are ignored.
@@ -981,15 +1117,15 @@ class GraphQL:
         cls, dependency_records: Iterable[Dependency]
     ) -> list[tuple[type[GeneralManager], dict[str, Any]]]:
         """
-        Convert DependencyTracker records into tuples of (manager class, identification dict).
-        
-        Filters input records to those whose operation is "identification", whose manager name maps to a registered GeneralManager class, and whose identifier can be parsed to a dict; returns one tuple per successfully resolved record.
-        
+        Convert dependency tracker records into resolved (manager class, identification dict) pairs.
+
+        Parses records whose operation is "identification", looks up the corresponding GeneralManager class by name in the registry, and parses the identifier into a dict. Records that do not meet these criteria are skipped.
+
         Parameters:
             dependency_records (Iterable[Dependency]): Iterable of dependency records as (manager_name, operation, identifier).
-        
+
         Returns:
-            list[tuple[type[GeneralManager], dict[str, Any]]]: A list of (manager_class, identification_dict) tuples for each resolved record.
+            list[tuple[type[GeneralManager], dict[str, Any]]]: List of (manager_class, identification_dict) tuples for each successfully resolved record.
         """
         resolved: list[tuple[type[GeneralManager], dict[str, Any]]] = []
         for manager_name, operation, identifier in dependency_records:
@@ -1014,14 +1150,14 @@ class GraphQL:
         manager_class: type[GeneralManager],
     ) -> set[str]:
         """
-        Identify GraphQLProperty names selected within the subscription payload's `item` field.
-        
+        Determine which GraphQLProperty names are selected under the subscription payload's `item` field.
+
         Parameters:
             info (GraphQLResolveInfo): Resolve info containing the parsed selection set and fragments.
-            manager_class (type[GeneralManager]): Manager class whose Interface defines available GraphQLProperty names.
-        
+            manager_class (type[GeneralManager]): GeneralManager subclass whose Interface defines available GraphQLProperty names.
+
         Returns:
-            property_names (set[str]): Set of GraphQLProperty names referenced under the `item` selection in the subscription request; empty if none or if the manager has no Interface.
+            property_names (set[str]): Set of GraphQLProperty names referenced under the `item` selection in the subscription request; empty set if none or if the manager has no Interface.
         """
         interface_cls = getattr(manager_class, "Interface", None)
         if interface_cls is None:
@@ -1035,12 +1171,12 @@ class GraphQL:
         def collect_from_selection(selection_set: SelectionSetNode | None) -> None:
             """
             Recursively collect selected GraphQL property names from a SelectionSetNode into the enclosing `property_names` set.
-            
+
             Processes each selection in the provided selection_set:
             - Adds a field's name to `property_names` when the name is present in the surrounding `available_properties` set.
             - For fragment spreads, resolves the fragment via `info.fragments` (from the enclosing scope) and recurses into its selection set.
             - For inline fragments, recurses into the fragment's selection set.
-            
+
             Parameters:
                 selection_set (SelectionSetNode | None): GraphQL selection set to traverse; no action is taken if None.
             """
@@ -1060,16 +1196,16 @@ class GraphQL:
 
         def inspect_selection_set(selection_set: SelectionSetNode | None) -> None:
             """
-            Recursively traverse a GraphQL SelectionSet and delegate the subselection of any field named "item" to collect_from_selection.
-            
+            Traverse a GraphQL SelectionSet and collect subselections of any field named "item".
+
             Parameters:
-            	selection_set (SelectionSetNode | None): The AST selection set to inspect. If None, the function does nothing.
-            
+                selection_set (SelectionSetNode | None): The AST selection set to inspect. If None, the function returns without action.
+
             Description:
-            	Visits FieldNode, FragmentSpreadNode, and InlineFragmentNode entries:
-            	- For FieldNode named "item", calls collect_from_selection with that field's subselection.
-            	- For other FieldNode entries and inline fragments, continues recursion into their subselections.
-            	- For fragment spreads, resolves the fragment from `info.fragments` (if present) and inspects its subselection.
+                - Visits FieldNode, FragmentSpreadNode, and InlineFragmentNode entries.
+                - For a FieldNode named "item", delegates its subselection to collect_from_selection.
+                - For other FieldNode entries and InlineFragmentNode entries, recurses into their subselections.
+                - For FragmentSpreadNode entries, attempts to resolve the referenced fragment (via the surrounding `info.fragments` if available) and inspects that fragment's subselection.
             """
             if selection_set is None:
                 return
@@ -1099,16 +1235,16 @@ class GraphQL:
     ) -> list[tuple[type[GeneralManager], dict[str, Any]]]:
         """
         Builds a list of dependency pairs (manager class, identification) for subscription wiring from an instance and optional dependency records.
-        
+
         Given a manager class and its instantiated item, returns deduplicated dependency definitions derived from:
         - any Dependency records produced by a dependency tracker, and
         - the manager Interface's input fields that reference other GeneralManager types and are populated on the instance.
-        
+
         Parameters:
             manager_class (type[GeneralManager]): The manager type whose subscription dependencies are being resolved.
             instance (GeneralManager): The instantiated manager item whose inputs and identification are inspected.
             dependency_records (Iterable[Dependency] | None): Optional dependency-tracker records to include.
-        
+
         Returns:
             list[tuple[type[GeneralManager], dict[str, Any]]]: A list of (dependent_manager_class, identification) pairs.
             Each identification is a dict of identification fields. The list excludes the (manager_class, instance.identification) pair and contains no duplicates.
@@ -1116,9 +1252,10 @@ class GraphQL:
         dependencies: list[tuple[type[GeneralManager], dict[str, Any]]] = []
         seen: set[tuple[str, str]] = set()
         if dependency_records:
-            for dependency_class, dependency_identification in cls._dependencies_from_tracker(
-                dependency_records
-            ):
+            for (
+                dependency_class,
+                dependency_identification,
+            ) in cls._dependencies_from_tracker(dependency_records):
                 if (
                     dependency_class is manager_class
                     and dependency_identification == instance.identification
@@ -1181,13 +1318,13 @@ class GraphQL:
     ) -> tuple[GeneralManager, set[Dependency]]:
         """
         Create a GeneralManager instance for the given identification and optionally prime its GraphQL properties to capture dependency records.
-        
+
         Parameters:
             manager_class (type[GeneralManager]): Manager class to instantiate.
             identification (dict[str, Any]): Mapping of identification field names to values used to construct the instance.
             collect_dependencies (bool): If True, prime GraphQL properties while tracking and return the captured Dependency records.
             property_names (Iterable[str] | None): Specific GraphQLProperty names to prime; if None, all relevant properties are primed.
-        
+
         Returns:
             tuple[GeneralManager, set[Dependency]]: The instantiated manager and a set of captured Dependency objects (empty if collect_dependencies is False).
         """
@@ -1202,20 +1339,22 @@ class GraphQL:
 
     @classmethod
     def _addSubscriptionField(
-        cls, graphene_type: type[graphene.ObjectType], generalManagerClass: Type[GeneralManager]
+        cls,
+        graphene_type: type[graphene.ObjectType],
+        generalManagerClass: Type[GeneralManager],
     ) -> None:
         """
         Register a GraphQL subscription field that publishes change events for the given manager type.
-        
+
         Creates (or reuses) a SubscriptionEvent payload GraphQL type and adds three entries to the class subscription registry:
         - a field exposing the subscription with identification arguments,
         - an async subscribe function that yields an initial "snapshot" event and subsequent change events for the identified instance and its dependencies,
         - and a resolve function that returns the delivered payload.
-        
+
         Parameters:
             graphene_type (type[graphene.ObjectType]): GraphQL ObjectType representing the manager's item type used as the payload `item` field.
             generalManagerClass (Type[GeneralManager]): The GeneralManager subclass whose changes the subscription will publish.
-        
+
         Notes:
         - The subscribe function requires an available channel layer and subscribes the caller to channel groups derived from the instance identification and its resolved dependencies.
         - The subscribe coroutine yields SubscriptionEvent objects with fields `item` (the current instance or None if it cannot be instantiated) and `action` (a string such as `"snapshot"` or other change actions).
@@ -1237,9 +1376,9 @@ class GraphQL:
                     "action": graphene.String(required=True),
                 },
             )
-            cls._subscription_payload_registry[
-                generalManagerClass.__name__
-            ] = payload_type
+            cls._subscription_payload_registry[generalManagerClass.__name__] = (
+                payload_type
+            )
 
         identification_args = cls._buildIdentificationArguments(generalManagerClass)
         subscription_field = graphene.Field(payload_type, **identification_args)
@@ -1250,15 +1389,15 @@ class GraphQL:
             **identification: Any,
         ) -> AsyncIterator[SubscriptionEvent]:
             """
-            Open a subscription stream for a specific manager instance identified by the provided arguments.
-            
-            The iterator first yields a `SubscriptionEvent` with action `"snapshot"` containing the current item, then yields subsequent `SubscriptionEvent`s for each received action. If an item cannot be re-instantiated while producing an update event, the yielded `SubscriptionEvent.item` will be `None`. The subscription registers the caller on the manager's channel groups and automatically unsubscribes and cancels background listeners when the iterator is closed or cancelled.
-            
+            Stream subscription events for a specific manager instance identified by the provided arguments.
+
+            Yields an initial `SubscriptionEvent` with `action` set to `"snapshot"` containing the current manager instance, then yields `SubscriptionEvent`s for each subsequent action. For update events, `item` will be the re-instantiated manager instance or `None` if instantiation fails. The subscriber is registered on the manager's channel groups (including dependent managers' groups) and the channel subscriptions and background listener are cleaned up when the iterator is closed or cancelled.
+
             Parameters:
                 identification: Identification fields required to locate the manager instance (maps to the manager's identification signature).
-            
+
             Returns:
-                AsyncIterator[SubscriptionEvent]: An asynchronous iterator that produces subscription events (initial snapshot then updates).
+                AsyncIterator[SubscriptionEvent]: An asynchronous iterator that first yields a snapshot event and then yields update events; each event's `item` is the manager instance or `None` if it could not be instantiated.
             """
             identification_copy = deepcopy(identification)
             property_names = cls._subscription_property_names(
@@ -1276,7 +1415,9 @@ class GraphQL:
                 raise GraphQLError(str(exc)) from exc
 
             try:
-                channel_layer = cast(BaseChannelLayer, cls._get_channel_layer(strict=True))
+                channel_layer = cast(
+                    BaseChannelLayer, cls._get_channel_layer(strict=True)
+                )
             except RuntimeError as exc:
                 raise GraphQLError(str(exc)) from exc
             channel_name = cast(str, await channel_layer.new_channel())
@@ -1307,13 +1448,13 @@ class GraphQL:
 
             async def event_stream() -> AsyncIterator[SubscriptionEvent]:
                 """
-                Asynchronously yields subscription events for a manager instance: an initial "snapshot" event followed by events for subsequent actions.
-                
-                Yields:
-                    SubscriptionEvent: First yields a `SubscriptionEvent` with `action` set to "snapshot" and `item` containing the current manager instance (or `None` if instantiation failed). Afterwards yields `SubscriptionEvent` values for each action received, where `action` is the action string and `item` is the (re-)instantiated manager or `None` if instantiation failed.
-                
+                Yield subscription events for a manager instance, starting with an initial snapshot followed by subsequent updates.
+
+                Returns:
+                    AsyncIterator[SubscriptionEvent]: An asynchronous iterator that first yields a `SubscriptionEvent` with `action` set to `"snapshot"` and `item` containing the current manager instance (or `None` if instantiation failed). Subsequent yields provide `SubscriptionEvent` values for each received action, where `action` is the action string and `item` is the (re-)instantiated manager or `None` if instantiation failed.
+
                 Notes:
-                    On exit the function cancels the background listener task and discards the channel subscriptions for all groups associated with the subscription.
+                    When the iterator is closed or exits, the background listener task is cancelled and the subscription's channel group memberships are discarded.
                 """
                 try:
                     yield SubscriptionEvent(item=instance, action="snapshot")
@@ -1326,7 +1467,7 @@ class GraphQL:
                                 identification_copy,
                                 property_names=property_names,
                             )
-                        except Exception:
+                        except HANDLED_MANAGER_ERRORS:
                             item = None
                         yield SubscriptionEvent(item=item, action=action)
                 finally:
@@ -1345,11 +1486,11 @@ class GraphQL:
         ) -> SubscriptionEvent:
             """
             Passes a subscription payload through unchanged.
-            
+
             Parameters:
                 payload (SubscriptionEvent): The subscription event payload to deliver to the client.
                 info (GraphQLResolveInfo): GraphQL resolver info (unused).
-            
+
             Returns:
                 SubscriptionEvent: The same payload instance provided as input.
             """
@@ -1362,16 +1503,13 @@ class GraphQL:
     @classmethod
     def createWriteFields(cls, interface_cls: InterfaceBase) -> dict[str, Any]:
         """
-        Generate Graphene input fields for writable attributes defined by an Interface.
-        
-        Skips system fields ("changed_by", "created_at", "updated_at") and derived attributes.
-        For relation attributes referencing another GeneralManager, produces ID or list-of-ID fields.
-        Each generated field is annotated with an `editable` attribute reflecting the interface metadata.
-        Always includes an optional "history_comment" String field marked editable.
-        
+        Create Graphene input fields for writable attributes defined by an Interface.
+
+        Skips system fields ("changed_by", "created_at", "updated_at") and attributes marked as derived. For attributes whose type is a GeneralManager, produces an ID field or a list of ID fields for names ending with "_list". Each generated field is annotated with an `editable` attribute reflecting the interface metadata. Always includes an optional `history_comment` string field marked editable.
+
         Parameters:
-            interface_cls (InterfaceBase): Interface whose attribute metadata (types, required, default, editable, derived) is used to build input fields.
-        
+            interface_cls (InterfaceBase): Interface providing attribute metadata (type, required, default, editable, derived) used to build the input fields.
+
         Returns:
             dict[str, Any]: Mapping from attribute name to a Graphene input field instance.
         """
@@ -1387,6 +1525,7 @@ class GraphQL:
             req = info["is_required"]
             default = info["default"]
 
+            fld: Any
             if issubclass(typ, GeneralManager):
                 if name.endswith("_list"):
                     fld = graphene.List(
@@ -1407,12 +1546,13 @@ class GraphQL:
                 )
 
             # mark for generate* code to know what is editable
-            setattr(fld, "editable", info["is_editable"])
+            cast(Any, fld).editable = info["is_editable"]
             fields[name] = fld
 
         # history_comment is always optional without a default value
-        fields["history_comment"] = graphene.String()
-        setattr(fields["history_comment"], "editable", True)
+        history_field = graphene.String()
+        cast(Any, history_field).editable = True
+        fields["history_comment"] = history_field
 
         return fields
 
@@ -1423,12 +1563,14 @@ class GraphQL:
         default_return_values: dict[str, Any],
     ) -> type[graphene.Mutation] | None:
         """
-        Dynamically generates a Graphene mutation class for creating an instance of a specified GeneralManager subclass.
+        Generate a Graphene Mutation class that creates instances of the given GeneralManager subclass.
 
-        The generated mutation class uses the manager's interface to define input arguments, filters out fields with `NOT_PROVIDED` values, and invokes the manager's `create` method with the provided data and the current user's ID. On success, it returns a dictionary with a success flag and the created instance; on failure, it raises a GraphQL error. Returns `None` if the manager class does not define an interface.
+        Parameters:
+            generalManagerClass (type[GeneralManager]): The GeneralManager subclass to expose a create mutation for.
+            default_return_values (dict[str, Any]): Base mutation return fields to include on the generated class.
 
         Returns:
-            The generated Graphene mutation class, or `None` if the manager class does not define an interface.
+            type[graphene.Mutation] | None: A Mutation class named `Create<ManagerName>` that implements creation for the manager (exposes appropriate Arguments and a `mutate` implementation), or `None` if the manager class does not define an `Interface`.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -1442,9 +1584,14 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Creates a new instance of the manager class using the provided arguments.
+            Create a new instance of the manager using the provided input fields.
 
-            Filters out any fields set to `NOT_PROVIDED` before invoking the creation method. Returns a dictionary with a success flag and the created instance keyed by the manager class name. If creation fails, raises a GraphQL error and returns a dictionary with `success` set to `False`.
+            Parameters:
+                info (GraphQLResolveInfo): GraphQL resolve info whose context user ID is used as the creator_id.
+                kwargs (Any): Input fields for the new instance; fields equal to `NOT_PROVIDED` are ignored.
+
+            Returns:
+                result (dict): A dictionary containing `success` (`True` if creation succeeded, `False` otherwise). On success the dictionary also includes the created instance under a key matching the manager class name.
             """
             try:
                 kwargs = {
@@ -1455,11 +1602,8 @@ class GraphQL:
                 instance = generalManagerClass.create(
                     **kwargs, creator_id=info.context.user.id
                 )
-            except Exception as e:
-                GraphQL._handleGraphQLError(e)
-                return {
-                    "success": False,
-                }
+            except HANDLED_MANAGER_ERRORS as error:
+                raise GraphQL._handleGraphQLError(error) from error
 
             return {
                 "success": True,
@@ -1513,27 +1657,24 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Updates an instance of a GeneralManager subclass with the specified field values.
+            Update a GeneralManager instance identified by its `id` with the provided field values.
 
             Parameters:
-                info (GraphQLResolveInfo): The GraphQL resolver context, including user and request data.
-                **kwargs: Field values to update, including the required 'id' of the instance.
+                info (GraphQLResolveInfo): GraphQL resolver context (contains the requesting user and request data).
+                **kwargs: Field values to update. Must include `id` to identify the target instance; other keys are treated as fields to update.
 
             Returns:
-                dict: A dictionary with 'success' (bool) and the updated instance keyed by its class name.
+                dict: Contains `success` (`True` if the update succeeded, `False` otherwise`) and, on success, the updated instance under a key matching the manager class name.
             """
+            manager_id = kwargs.pop("id", None)
+            if manager_id is None:
+                raise GraphQL._handleGraphQLError(MissingManagerIdentifierError())
             try:
-                manager_id = kwargs.pop("id", None)
-                if manager_id is None:
-                    raise ValueError("id is required")
                 instance = generalManagerClass(id=manager_id).update(
                     creator_id=info.context.user.id, **kwargs
                 )
-            except Exception as e:
-                GraphQL._handleGraphQLError(e)
-                return {
-                    "success": False,
-                }
+            except HANDLED_MANAGER_ERRORS as error:
+                raise GraphQL._handleGraphQLError(error) from error
 
             return {
                 "success": True,
@@ -1590,23 +1731,20 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Deactivates an instance of a GeneralManager subclass and returns the operation result.
+            Deactivates the identified GeneralManager instance.
 
             Returns:
-                dict: A dictionary with a "success" boolean and the deactivated instance keyed by its class name.
+                dict: `success` key with `True` if deactivation succeeded, `False` otherwise. On success, includes an additional key equal to the manager class name containing the deactivated instance.
             """
+            manager_id = kwargs.pop("id", None)
+            if manager_id is None:
+                raise GraphQL._handleGraphQLError(MissingManagerIdentifierError())
             try:
-                manager_id = kwargs.pop("id", None)
-                if manager_id is None:
-                    raise ValueError("id is required")
                 instance = generalManagerClass(id=manager_id).deactivate(
                     creator_id=info.context.user.id
                 )
-            except Exception as e:
-                GraphQL._handleGraphQLError(e)
-                return {
-                    "success": False,
-                }
+            except HANDLED_MANAGER_ERRORS as error:
+                raise GraphQL._handleGraphQLError(error) from error
 
             return {
                 "success": True,
@@ -1635,37 +1773,37 @@ class GraphQL:
         )
 
     @staticmethod
-    def _handleGraphQLError(error: Exception) -> None:
+    def _handleGraphQLError(error: Exception) -> GraphQLError:
         """
         Convert an exception into a GraphQL error with an appropriate extensions['code'].
-        
+
         Maps:
             PermissionError -> "PERMISSION_DENIED"
             ValueError, ValidationError, TypeError -> "BAD_USER_INPUT"
             other exceptions -> "INTERNAL_SERVER_ERROR"
-        
+
         Parameters:
             error (Exception): The original exception to convert.
-        
-        Raises:
+
+        Returns:
             GraphQLError: GraphQL error containing the original message and an `extensions['code']` indicating the error category.
         """
         if isinstance(error, PermissionError):
-            raise GraphQLError(
+            return GraphQLError(
                 str(error),
                 extensions={
                     "code": "PERMISSION_DENIED",
                 },
             )
         elif isinstance(error, (ValueError, ValidationError, TypeError)):
-            raise GraphQLError(
+            return GraphQLError(
                 str(error),
                 extensions={
                     "code": "BAD_USER_INPUT",
                 },
             )
         else:
-            raise GraphQLError(
+            return GraphQLError(
                 str(error),
                 extensions={
                     "code": "INTERNAL_SERVER_ERROR",
@@ -1681,17 +1819,14 @@ class GraphQL:
         **_: Any,
     ) -> None:
         """
-        Send a subscription event to the channel group for a changed GeneralManager instance.
-        
-        If `instance` is a GeneralManager of a registered manager type and a channel layer is available,
-        publish a "gm.subscription.event" message containing the provided `action` to the group identified
-        by the manager class and the instance's identification. If `instance` is missing, the manager is
-        not registered, or no channel layer is available, the function returns without side effects.
-        
+        Send a "gm.subscription.event" message to the channel group corresponding to a changed GeneralManager instance.
+
+        If the provided instance is a registered GeneralManager and a channel layer is configured, publish a message containing the given action to the channel group derived from the manager class and the instance's identification. If the instance is None, the manager type is not registered, or no channel layer is available, the function returns without side effects.
+
         Parameters:
-            sender: The signal sender; either a GeneralManager subclass or an instance.
-            instance: The GeneralManager instance that changed.
-            action: A string describing the change action (e.g., "created", "updated", "deleted").
+            sender (type[GeneralManager] | GeneralManager): The signal sender; either a GeneralManager subclass or an instance.
+            instance (GeneralManager | None): The GeneralManager instance that changed.
+            action (str): A string describing the change action (e.g., "created", "updated", "deleted").
         """
         if instance is None or not isinstance(instance, GeneralManager):
             return
@@ -1718,4 +1853,4 @@ class GraphQL:
         )
 
 
-post_data_change.connect(GraphQL._handle_data_change, weak=False)
+post_data_change.connect(GraphQL._handle_data_change, weak=False)