GeneralManager 0.11.2__tar.gz → 0.12.1__tar.gz

{generalmanager-0.11.2 → generalmanager-0.12.1}/GeneralManager.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.11.2
+Version: 0.12.1
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License-Expression: MIT

{generalmanager-0.11.2 → generalmanager-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.11.2
+Version: 0.12.1
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License-Expression: MIT

{generalmanager-0.11.2 → generalmanager-0.12.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.11.2"
+version = "0.12.1"
 description = "Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching."
 readme = "README.md"
 authors = [{ name = "Tim Kleindick", email = "tkleindick@yahoo.de" }]

{generalmanager-0.11.2 → generalmanager-0.12.1}/src/general_manager/api/graphql.py

@@ -4,6 +4,7 @@ from typing import Any, Callable, get_args, TYPE_CHECKING, cast, Type
 from decimal import Decimal
 from datetime import date, datetime
 import json
+from graphql.language import ast
 
 from general_manager.measurement.measurement import Measurement
 from general_manager.manager.generalManager import GeneralManagerMeta, GeneralManager
@@ -11,6 +12,10 @@ from general_manager.api.property import GraphQLProperty
 from general_manager.bucket.baseBucket import Bucket
 from general_manager.interface.baseInterface import InterfaceBase
 from django.db.models import NOT_PROVIDED
+from django.core.exceptions import ValidationError
+
+from graphql import GraphQLError
+
 
 if TYPE_CHECKING:
     from general_manager.permission.basePermission import BasePermission
@@ -22,13 +27,43 @@ class MeasurementType(graphene.ObjectType):
     unit = graphene.String()
 
 
+class MeasurementScalar(graphene.Scalar):
+    """
+    A measurement in format "value unit", e.g. "12.5 m/s".
+    """
+
+    @staticmethod
+    def serialize(value: Measurement) -> str:
+        if not isinstance(value, Measurement):
+            raise TypeError(f"Expected Measurement, got {type(value)}")
+        return str(value)
+
+    @staticmethod
+    def parse_value(value: str) -> Measurement:
+        return Measurement.from_string(value)
+
+    @staticmethod
+    def parse_literal(node: Any) -> Measurement | None:
+        if isinstance(node, ast.StringValueNode):
+            return Measurement.from_string(node.value)
+        return None
+
+
+class PageInfo(graphene.ObjectType):
+    total_count = graphene.Int(required=True)
+    page_size = graphene.Int(required=False)
+    current_page = graphene.Int(required=True)
+    total_pages = graphene.Int(required=True)
+
+
 def getReadPermissionFilter(
     generalManagerClass: GeneralManagerMeta,
     info: GraphQLResolveInfo,
 ) -> list[tuple[dict[str, Any], dict[str, Any]]]:
     """
-    Ermittelt die Filter, die auf Basis der read-Permission für den angegebenen
-    Manager angewendet werden müssen.
+    Returns permission-based filter and exclude constraints for querying instances of a manager class.
+
+    For the given manager class and user context, retrieves a list of (filter, exclude) dictionary pairs that represent the read access restrictions to be applied to queries. Returns an empty list if no permission class is defined.
     """
     filters = []
     PermissionClass: type[BasePermission] | None = getattr(
@@ -55,17 +90,16 @@ class GraphQL:
     _mutation_class: type[graphene.ObjectType] | None = None
     _mutations: dict[str, Any] = {}
     _query_fields: dict[str, Any] = {}
+    _page_type_registry: dict[str, type[graphene.ObjectType]] = {}
     graphql_type_registry: dict[str, type] = {}
     graphql_filter_type_registry: dict[str, type] = {}
 
     @classmethod
     def createGraphqlMutation(cls, generalManagerClass: type[GeneralManager]) -> None:
         """
-        Erzeugt ein GraphQL-Mutation-Interface für die übergebene Manager-Klasse.
-        Dabei werden:
-          - Attribute aus dem Interface in Graphene-Felder abgebildet
-          - Zu jedem Feld ein Resolver generiert und hinzugefügt
-          - Der neue Type in das Registry eingetragen und Mutationen angehängt.
+        Generates and registers GraphQL mutation classes for create, update, and delete operations on the specified manager class if its interface provides custom implementations.
+
+        For each supported mutation, a corresponding GraphQL mutation class is created and added to the mutation registry, enabling dynamic mutation support in the schema.
         """
 
         interface_cls: InterfaceBase | None = getattr(
@@ -76,7 +110,6 @@ class GraphQL:
 
         default_return_values = {
             "success": graphene.Boolean(),
-            "errors": graphene.List(graphene.String),
             generalManagerClass.__name__: graphene.Field(
                 lambda: GraphQL.graphql_type_registry[generalManagerClass.__name__]
             ),
@@ -102,9 +135,9 @@ class GraphQL:
     @classmethod
     def createGraphqlInterface(cls, generalManagerClass: GeneralManagerMeta) -> None:
         """
-        Generates and registers a GraphQL ObjectType for the specified GeneralManager class.
-        
-        This method maps interface attributes and GraphQLProperty fields to Graphene fields, creates appropriate resolvers, registers the resulting type in the internal registry, and adds related query fields to the schema.
+        Creates and registers a GraphQL ObjectType for a GeneralManager subclass.
+
+        Introspects the manager's interface and GraphQLProperty fields, maps them to Graphene fields with appropriate resolvers, registers the resulting type in the internal registry, and adds corresponding query fields to the schema.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -146,9 +179,9 @@ class GraphQL:
     ) -> type[graphene.Enum] | None:
         """
         Creates a Graphene Enum type representing sortable fields for a given GeneralManager class.
-        
+
         Returns:
-            A Graphene Enum type with options for each sortable attribute, or None if no sortable fields exist.
+            A Graphene Enum type with options for each sortable attribute, including separate entries for the value and unit of Measurement fields. Returns None if there are no sortable fields.
         """
         sort_options = []
         for (
@@ -158,9 +191,6 @@ class GraphQL:
             field_type = field_info["type"]
             if issubclass(field_type, GeneralManager):
                 continue
-            elif issubclass(field_type, Measurement):
-                sort_options.append(f"{field_name}_value")
-                sort_options.append(f"{field_name}_unit")
             else:
                 sort_options.append(field_name)
 
@@ -179,8 +209,15 @@ class GraphQL:
     ) -> type[graphene.InputObjectType] | None:
         """
         Dynamically generates a Graphene InputObjectType for filtering fields of a GeneralManager subclass.
-        
-        Creates filter fields for each attribute based on its type, supporting numeric and string filter options, as well as specialized handling for Measurement attributes. Returns the generated InputObjectType or None if no filter fields are applicable.
+
+        Creates filter fields for each attribute based on its type, supporting numeric and string filter operations, and specialized handling for Measurement attributes. Returns the generated InputObjectType, or None if no applicable filter fields exist.
+
+        Parameters:
+            field_name (str): The name of the field to generate filter options for.
+            field_type (GeneralManagerMeta): The manager class whose attributes are used to build filter fields.
+
+        Returns:
+            type[graphene.InputObjectType] | None: The generated filter input type, or None if no filter fields are applicable.
         """
         number_options = ["exact", "gt", "gte", "lt", "lte"]
         string_options = [
@@ -202,11 +239,9 @@ class GraphQL:
             if issubclass(attr_type, GeneralManager):
                 continue
             elif issubclass(attr_type, Measurement):
-                filter_fields[f"{attr_name}_value"] = graphene.Float()
-                filter_fields[f"{attr_name}_unit"] = graphene.String()
+                filter_fields[f"{attr_name}"] = MeasurementScalar()
                 for option in number_options:
-                    filter_fields[f"{attr_name}_value__{option}"] = graphene.Float()
-                    filter_fields[f"{attr_name}_unit__{option}"] = graphene.String()
+                    filter_fields[f"{attr_name}__{option}"] = MeasurementScalar()
             else:
                 filter_fields[attr_name] = GraphQL._mapFieldToGrapheneRead(
                     attr_type, attr_name
@@ -236,8 +271,8 @@ class GraphQL:
     def _mapFieldToGrapheneRead(field_type: type, field_name: str) -> Any:
         """
         Maps a Python field type and name to the appropriate Graphene field for GraphQL schema generation.
-        
-        For `Measurement` types, returns a field with an optional `target_unit` argument. For `GeneralManager` subclasses, returns either a list field (with optional filtering, exclusion, sorting, pagination, and grouping arguments if available) or a single field, depending on the field name. For other types, returns the corresponding Graphene scalar field.
+
+        For `Measurement` fields, returns a Graphene field with an optional `target_unit` argument. For `GeneralManager` subclasses, returns a paginated field with filtering, exclusion, sorting, pagination, and grouping arguments if the field name ends with `_list`; otherwise, returns a single object field. For all other types, returns the corresponding Graphene scalar field.
         """
         if issubclass(field_type, Measurement):
             return graphene.Field(MeasurementType, target_unit=graphene.String())
@@ -257,6 +292,13 @@ class GraphQL:
                 sort_by_options = GraphQL._sortByOptions(field_type)
                 if sort_by_options:
                     attributes["sort_by"] = sort_by_options()
+
+                page_type = GraphQL._getOrCreatePageType(
+                    field_type.__name__ + "Page",
+                    lambda: GraphQL.graphql_type_registry[field_type.__name__],
+                )
+                return graphene.Field(page_type, **attributes)
+
                 return graphene.List(
                     lambda: GraphQL.graphql_type_registry[field_type.__name__],
                     **attributes,
@@ -282,6 +324,8 @@ class GraphQL:
             return graphene.Float
         elif issubclass(field_type, (date, datetime)):
             return graphene.Date
+        elif issubclass(field_type, Measurement):
+            return MeasurementScalar
         else:
             return graphene.String
 
@@ -306,11 +350,18 @@ class GraphQL:
         exclude_input: dict[str, Any] | str | None,
         sort_by: graphene.Enum | None,
         reverse: bool,
-        page: int | None,
-        page_size: int | None,
     ) -> Bucket[GeneralManager]:
         """
-        Wendet Filter, Excludes, Sortierung und Paginierung auf das Queryset an.
+        Apply filtering, exclusion, and sorting to a queryset based on provided parameters.
+
+        Parameters:
+            filter_input: Filters to apply, as a dictionary or JSON string.
+            exclude_input: Exclusions to apply, as a dictionary or JSON string.
+            sort_by: Field to sort by, as a Graphene Enum value.
+            reverse: If True, reverses the sort order.
+
+        Returns:
+            The queryset after applying filters, exclusions, and sorting.
         """
         filters = GraphQL._parseInput(filter_input)
         if filters:
@@ -324,12 +375,6 @@ class GraphQL:
             sort_by_str = cast(str, getattr(sort_by, "value", sort_by))
             queryset = queryset.sort(sort_by_str, reverse=reverse)
 
-        if page is not None or page_size is not None:
-            page = page or 1
-            page_size = page_size or 10
-            offset = (page - 1) * page_size
-            queryset = cast(Bucket, queryset[offset : offset + page_size])
-
         return queryset
 
     @staticmethod
@@ -370,14 +415,9 @@ class GraphQL:
         base_getter: Callable[[Any], Any], fallback_manager_class: type[GeneralManager]
     ) -> Callable[..., Any]:
         """
-        Create a resolver function for GraphQL list fields that retrieves and returns a queryset with permission filters, query filters, sorting, pagination, and optional grouping applied.
-        
-        Parameters:
-            base_getter: Function to obtain the base queryset from the parent instance.
-            fallback_manager_class: Manager class to use if the queryset does not specify one.
-        
-        Returns:
-            A resolver function that processes list queries with filtering, sorting, pagination, and grouping.
+        Creates a resolver for GraphQL list fields that returns paginated, filtered, sorted, and optionally grouped results with permission checks.
+
+        The generated resolver applies permission-based filtering, user-specified filters and exclusions, sorting, grouping, and pagination to the list field. It returns a dictionary containing the resulting items and pagination metadata.
         """
 
         def resolver(
@@ -390,21 +430,21 @@ class GraphQL:
             page: int | None = None,
             page_size: int | None = None,
             group_by: list[str] | None = None,
-        ) -> Any:
+        ) -> dict[str, Any]:
             """
-            Resolves a list field by returning a queryset with permission filters, query filters, sorting, pagination, and optional grouping applied.
-            
+            Resolves a list field by returning filtered, excluded, sorted, grouped, and paginated results with permission checks.
+
             Parameters:
                 filter: Filter criteria as a dictionary or JSON string.
                 exclude: Exclusion criteria as a dictionary or JSON string.
                 sort_by: Field to sort by, as a Graphene Enum.
-                reverse: Whether to reverse the sort order.
+                reverse: If True, reverses the sort order.
                 page: Page number for pagination.
                 page_size: Number of items per page.
                 group_by: List of field names to group results by.
-            
+
             Returns:
-                The resulting queryset after applying permissions, filters, sorting, pagination, and grouping.
+                A dictionary containing the paginated items under "items" and pagination metadata under "pageInfo".
             """
             base_queryset = base_getter(self)
             # use _manager_class from the attribute if available, otherwise fallback
@@ -412,22 +452,73 @@ class GraphQL:
                 base_queryset, "_manager_class", fallback_manager_class
             )
             qs = GraphQL._applyPermissionFilters(base_queryset, manager_class, info)
-            qs = GraphQL._applyQueryParameters(
-                qs, filter, exclude, sort_by, reverse, page, page_size
-            )
-            if group_by is not None:
-                if group_by == [""]:
-                    qs = qs.group_by()
-                else:
-                    qs = qs.group_by(*group_by)
-            return qs
+            qs = GraphQL._applyQueryParameters(qs, filter, exclude, sort_by, reverse)
+            qs = GraphQL._applyGrouping(qs, group_by)
+
+            total_count = len(qs)
+
+            qs_paginated = GraphQL._applyPagination(qs, page, page_size)
+
+            page_info = {
+                "total_count": total_count,
+                "page_size": page_size,
+                "current_page": page or 1,
+                "total_pages": (
+                    ((total_count + page_size - 1) // page_size) if page_size else 1
+                ),
+            }
+            return {
+                "items": qs_paginated,
+                "pageInfo": page_info,
+            }
 
         return resolver
 
+    @staticmethod
+    def _applyPagination(
+        queryset: Bucket[GeneralManager], page: int | None, page_size: int | None
+    ) -> Bucket[GeneralManager]:
+        """
+        Returns a paginated subset of the queryset based on the given page number and page size.
+
+        If neither `page` nor `page_size` is provided, the entire queryset is returned. Defaults to page 1 and page size 10 if only one parameter is specified.
+
+        Parameters:
+            page (int | None): The page number to retrieve (1-based).
+            page_size (int | None): The number of items per page.
+
+        Returns:
+            Bucket[GeneralManager]: The paginated queryset.
+        """
+        if page is not None or page_size is not None:
+            page = page or 1
+            page_size = page_size or 10
+            offset = (page - 1) * page_size
+            queryset = cast(Bucket, queryset[offset : offset + page_size])
+        return queryset
+
+    @staticmethod
+    def _applyGrouping(
+        queryset: Bucket[GeneralManager], group_by: list[str] | None
+    ) -> Bucket[GeneralManager]:
+        """
+        Groups the queryset by the specified fields.
+
+        If `group_by` is `[""]`, groups by all default fields. If `group_by` is a list of field names, groups by those fields. Returns the grouped queryset.
+        """
+        if group_by is not None:
+            if group_by == [""]:
+                queryset = queryset.group_by()
+            else:
+                queryset = queryset.group_by(*group_by)
+        return queryset
+
     @staticmethod
     def _createMeasurementResolver(field_name: str) -> Callable[..., Any]:
         """
-        Erzeugt einen Resolver für Felder vom Typ Measurement.
+        Creates a resolver for a Measurement field that returns its value and unit, with optional unit conversion.
+
+        The generated resolver checks read permissions for the specified field. If permitted and the field is a Measurement, it returns a dictionary containing the measurement's value and unit, converting to the specified target unit if provided. Returns None if permission is denied or the field is not a Measurement.
         """
 
         def resolver(
@@ -465,7 +556,9 @@ class GraphQL:
     @classmethod
     def _createResolver(cls, field_name: str, field_type: type) -> Callable[..., Any]:
         """
-        Wählt anhand des Feldtyps den passenden Resolver aus.
+        Returns a resolver function for a field, selecting list, measurement, or standard resolution based on the field's type and name.
+
+        For fields ending with `_list` referencing a `GeneralManager` subclass, provides a resolver supporting pagination and filtering. For `Measurement` fields, returns a resolver that handles unit conversion and permission checks. For all other fields, returns a standard resolver with permission enforcement.
         """
         if field_name.endswith("_list") and issubclass(field_type, GeneralManager):
             return cls._createListResolver(
@@ -475,14 +568,36 @@ class GraphQL:
             return cls._createMeasurementResolver(field_name)
         return cls._createNormalResolver(field_name)
 
+    @classmethod
+    def _getOrCreatePageType(
+        cls,
+        page_type_name: str,
+        item_type: type[graphene.ObjectType] | Callable[[], type[graphene.ObjectType]],
+    ) -> type[graphene.ObjectType]:
+        """
+        Returns a paginated GraphQL ObjectType for the specified item type, creating and caching it if it does not already exist.
+
+        The returned ObjectType includes an `items` field (a required list of the item type) and a `pageInfo` field (pagination metadata).
+        """
+        if page_type_name not in cls._page_type_registry:
+            cls._page_type_registry[page_type_name] = type(
+                page_type_name,
+                (graphene.ObjectType,),
+                {
+                    "items": graphene.List(item_type, required=True),
+                    "pageInfo": graphene.Field(PageInfo, required=True),
+                },
+            )
+        return cls._page_type_registry[page_type_name]
+
     @classmethod
     def _addQueriesToSchema(
         cls, graphene_type: type, generalManagerClass: GeneralManagerMeta
     ) -> None:
         """
-        Add list and single-item query fields for a GeneralManager subclass to the GraphQL schema.
-        
-        Registers a list query field with optional filtering, exclusion, sorting, pagination, and grouping arguments, as well as a single-item query field using identification fields from the manager's interface. Attaches the corresponding resolvers for both queries to the schema.
+        Adds paginated list and single-item query fields for a GeneralManager subclass to the GraphQL schema.
+
+        The list query field enables filtering, exclusion, sorting, pagination, and grouping, returning a paginated result with metadata. The single-item query field retrieves an instance by its identification fields. Both queries are registered with their respective resolvers.
         """
         if not issubclass(generalManagerClass, GeneralManager):
             raise TypeError(
@@ -509,10 +624,11 @@ class GraphQL:
         sort_by_options = cls._sortByOptions(generalManagerClass)
         if sort_by_options:
             attributes["sort_by"] = sort_by_options()
-        list_field = graphene.List(
-            graphene_type,
-            **attributes,
+
+        page_type = cls._getOrCreatePageType(
+            graphene_type.__name__ + "Page", graphene_type
         )
+        list_field = graphene.Field(page_type, **attributes)
 
         list_resolver = cls._createListResolver(
             lambda self: generalManagerClass.all(), generalManagerClass
@@ -551,10 +667,10 @@ class GraphQL:
     @classmethod
     def createWriteFields(cls, interface_cls: InterfaceBase) -> dict[str, Any]:
         """
-        Generate a dictionary of Graphene input fields for mutations based on the attributes of the provided interface class.
-        
-        Skips system-managed and derived attributes. For attributes referencing `GeneralManager` subclasses, uses an ID or list of IDs as appropriate. Other types are mapped to their corresponding Graphene scalar types. Each field is annotated with an `editable` attribute. An optional `history_comment` field, also marked as editable, is always included.
-        
+        Generates a dictionary of Graphene input fields for mutations based on the attributes of the provided interface class.
+
+        Skips system-managed and derived attributes. For attributes referencing `GeneralManager` subclasses, uses an ID or list of IDs as appropriate. Other types are mapped to their corresponding Graphene scalar types. Each field is annotated with an `editable` attribute. Always includes an optional `history_comment` field marked as editable.
+
         Returns:
             dict[str, Any]: Mapping of attribute names to Graphene input fields for mutation arguments.
         """
@@ -607,11 +723,11 @@ class GraphQL:
     ) -> type[graphene.Mutation] | None:
         """
         Dynamically generates a Graphene mutation class for creating an instance of a specified GeneralManager subclass.
-        
-        The generated mutation class filters out fields with `NOT_PROVIDED` values, calls the manager's `create` method with the provided arguments and the current user's ID, and returns a dictionary containing a success flag, any errors, and the created instance. Returns None if the manager class does not define an interface.
-        
+
+        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.
+
         Returns:
-            The generated Graphene mutation class, or None if the manager class does not define an interface.
+            The generated Graphene mutation class, or `None` if the manager class does not define an interface.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -625,9 +741,9 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Create a new instance of the manager class using the provided arguments.
-            
-            Filters out any fields with values set to `NOT_PROVIDED` before invoking the creation method. Returns a dictionary with a success flag, a list of errors if creation fails, and the created instance keyed by the manager class name.
+            Creates a new instance of the manager class using the provided arguments.
+
+            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`.
             """
             try:
                 kwargs = {
@@ -639,14 +755,13 @@ class GraphQL:
                     **kwargs, creator_id=info.context.user.id
                 )
             except Exception as e:
+                GraphQL._handleGraphQLError(e)
                 return {
                     "success": False,
-                    "errors": [str(e)],
                 }
 
             return {
                 "success": True,
-                "errors": [],
                 generalManagerClass.__name__: instance,
             }
 
@@ -679,11 +794,11 @@ class GraphQL:
     ) -> type[graphene.Mutation] | None:
         """
         Generates a GraphQL mutation class for updating an instance of a GeneralManager subclass.
-        
-        The generated mutation accepts editable fields as arguments, calls the manager's `update` method with the provided values and the current user's ID, and returns a dictionary containing the operation's success status, any error messages, and the updated instance. Returns None if the manager class does not define an `Interface`.
-        
+
+        The generated mutation accepts editable fields as arguments, calls the manager's `update` method with the provided values and the current user's ID, and returns a dictionary containing a success flag and the updated instance. Returns `None` if the manager class does not define an `Interface`.
+
         Returns:
-            The generated Graphene mutation class, or None if no interface is defined.
+            The generated Graphene mutation class, or `None` if no interface is defined.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -697,14 +812,14 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Updates a GeneralManager instance with the provided fields.
-            
+            Updates an instance of a GeneralManager subclass with the specified field values.
+
             Parameters:
-                info (GraphQLResolveInfo): The GraphQL resolver context, typically containing user and request information.
-                **kwargs: Fields to update, including the required 'id' of the instance.
-            
+                info (GraphQLResolveInfo): The GraphQL resolver context, including user and request data.
+                **kwargs: Field values to update, including the required 'id' of the instance.
+
             Returns:
-                dict: A dictionary with keys 'success' (bool), 'errors' (list of str), and the updated instance keyed by its class name.
+                dict: A dictionary with 'success' (bool) and the updated instance keyed by its class name.
             """
             try:
                 manager_id = kwargs.pop("id", None)
@@ -712,13 +827,13 @@ class GraphQL:
                     creator_id=info.context.user.id, **kwargs
                 )
             except Exception as e:
+                GraphQL._handleGraphQLError(e)
                 return {
                     "success": False,
-                    "errors": [str(e)],
                 }
+
             return {
                 "success": True,
-                "errors": [],
                 generalManagerClass.__name__: instance,
             }
 
@@ -751,11 +866,11 @@ class GraphQL:
     ) -> type[graphene.Mutation] | None:
         """
         Generates a GraphQL mutation class for deactivating (soft-deleting) an instance of a GeneralManager subclass.
-        
-        The generated mutation accepts input fields defined by the manager's interface, deactivates the specified instance using its ID, and returns a dictionary containing the operation's success status, any error messages, and the deactivated instance keyed by the class name.
-        
+
+        The generated mutation accepts input fields defined by the manager's interface, deactivates the specified instance using its ID, and returns a dictionary containing a success status and the deactivated instance keyed by the class name. Returns None if the manager class does not define an interface.
+
         Returns:
-            The generated Graphene mutation class, or None if the manager class does not define an interface.
+            The generated Graphene mutation class, or None if no interface is defined.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -769,13 +884,10 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Deactivates an instance of the specified GeneralManager class and returns the operation result.
-            
+            Deactivates an instance of a GeneralManager subclass and returns the operation result.
+
             Returns:
-                dict: A dictionary with keys:
-                    - "success": Boolean indicating if the operation was successful.
-                    - "errors": List of error messages, empty if successful.
-                    - <ClassName>: The deactivated instance, keyed by the class name.
+                dict: A dictionary with a "success" boolean and the deactivated instance keyed by its class name.
             """
             try:
                 manager_id = kwargs.pop("id", None)
@@ -783,13 +895,13 @@ class GraphQL:
                     creator_id=info.context.user.id
                 )
             except Exception as e:
+                GraphQL._handleGraphQLError(e)
                 return {
                     "success": False,
-                    "errors": [str(e)],
                 }
+
             return {
                 "success": True,
-                "errors": [],
                 generalManagerClass.__name__: instance,
             }
 
@@ -813,3 +925,32 @@ class GraphQL:
                 "mutate": delete_mutation,
             },
         )
+
+    @staticmethod
+    def _handleGraphQLError(error: Exception) -> None:
+        """
+        Raises a GraphQLError with a specific error code based on the exception type.
+
+        PermissionError results in "PERMISSION_DENIED", ValueError or ValidationError in "BAD_USER_INPUT", and all other exceptions in "INTERNAL_SERVER_ERROR".
+        """
+        if isinstance(error, PermissionError):
+            raise GraphQLError(
+                str(error),
+                extensions={
+                    "code": "PERMISSION_DENIED",
+                },
+            )
+        elif isinstance(error, (ValueError, ValidationError)):
+            raise GraphQLError(
+                str(error),
+                extensions={
+                    "code": "BAD_USER_INPUT",
+                },
+            )
+        else:
+            raise GraphQLError(
+                str(error),
+                extensions={
+                    "code": "INTERNAL_SERVER_ERROR",
+                },
+            )