GeneralManager 0.11.2__tar.gz → 0.12.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.11.2
+Version: 0.12.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-Expression: MIT

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.11.2
+Version: 0.12.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-Expression: MIT

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.11.2"
+version = "0.12.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.11.2 → generalmanager-0.12.0}/src/general_manager/api/graphql.py

@@ -11,6 +11,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 +26,21 @@ class MeasurementType(graphene.ObjectType):
     unit = graphene.String()
 
 
+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 a list of filter and exclude dictionaries based on the read permissions for the specified manager class and user context.
+    
+    Each tuple in the returned list contains a filter dictionary and an exclude dictionary, representing permission-based constraints to be applied to queries.
     """
     filters = []
     PermissionClass: type[BasePermission] | None = getattr(
@@ -55,17 +67,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.
+        Creates and registers GraphQL mutation classes (create, update, delete) for the given manager class if its interface overrides the corresponding base methods.
+        
+        For each supported mutation, generates a GraphQL mutation class with appropriate input and output fields, and adds it to the mutation registry.
         """
 
         interface_cls: InterfaceBase | None = getattr(
@@ -76,7 +87,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 +112,9 @@ class GraphQL:
     @classmethod
     def createGraphqlInterface(cls, generalManagerClass: GeneralManagerMeta) -> None:
         """
-        Generates and registers a GraphQL ObjectType for the specified GeneralManager class.
+        Creates and registers a GraphQL ObjectType for the given GeneralManager subclass.
         
-        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.
+        This method 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
@@ -145,10 +155,10 @@ class GraphQL:
         generalManagerClass: GeneralManagerMeta,
     ) -> type[graphene.Enum] | None:
         """
-        Creates a Graphene Enum type representing sortable fields for a given GeneralManager class.
+        Generate a Graphene Enum type listing the 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 options for the value and unit of Measurement fields, or None if no sortable fields are found.
         """
         sort_options = []
         for (
@@ -180,7 +190,7 @@ class GraphQL:
         """
         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.
         """
         number_options = ["exact", "gt", "gte", "lt", "lte"]
         string_options = [
@@ -237,7 +247,7 @@ class GraphQL:
         """
         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 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 +267,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,
@@ -306,11 +323,19 @@ 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.
+        Applies filtering, exclusion, and sorting parameters to a queryset.
+        
+        Parameters:
+            queryset (Bucket[GeneralManager]): The queryset to modify.
+            filter_input (dict | str | None): Filters to apply, as a dict or JSON string.
+            exclude_input (dict | str | None): Exclusions to apply, as a dict or JSON string.
+            sort_by (graphene.Enum | None): Field to sort by, if provided.
+            reverse (bool): Whether to reverse the sort order.
+        
+        Returns:
+            Bucket[GeneralManager]: The modified queryset after applying filters, exclusions, and sorting.
         """
         filters = GraphQL._parseInput(filter_input)
         if filters:
@@ -324,12 +349,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 +389,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.
+        Creates a resolver for GraphQL list fields that returns paginated, filtered, sorted, and optionally grouped results with permission checks applied.
         
-        Returns:
-            A resolver function that processes list queries with filtering, sorting, pagination, and grouping.
+        The returned resolver processes list queries by applying permission-based filtering, user-specified filters and exclusions, sorting, grouping, and pagination. It returns a dictionary containing the paginated items and pagination metadata.
         """
 
         def resolver(
@@ -390,21 +404,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 paginated, filtered, sorted, and optionally grouped results with permission checks applied.
             
             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.
-                page: Page number for pagination.
-                page_size: Number of items per page.
-                group_by: List of field names to group results by.
+                filter (dict[str, Any] | str | None): Filter criteria as a dictionary or JSON string.
+                exclude (dict[str, Any] | str | None): Exclusion criteria as a dictionary or JSON string.
+                sort_by (graphene.Enum | None): Field to sort by.
+                reverse (bool): Whether to reverse the sort order.
+                page (int | None): Page number for pagination.
+                page_size (int | None): Number of items per page.
+                group_by (list[str] | None): List of field names to group results by.
             
             Returns:
-                The resulting queryset after applying permissions, filters, sorting, pagination, and grouping.
+                dict[str, Any]: 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 +426,70 @@ 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]:
+        """
+        Return a paginated subset of the queryset based on the specified page number and page size.
+        
+        If either `page` or `page_size` is provided, pagination is applied; otherwise, the original queryset is returned.
+        """
+        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]:
+        """
+        Group a 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 function for Measurement fields that returns the value and unit, optionally converting to a specified target unit.
+        
+        Parameters:
+            field_name (str): The name of the Measurement field to resolve.
+        
+        Returns:
+            Callable[..., dict[str, Any] | None]: A resolver that returns a dictionary with 'value' and 'unit' keys, or None if permission is denied or the field is not a Measurement.
         """
 
         def resolver(
@@ -465,7 +527,9 @@ class GraphQL:
     @classmethod
     def _createResolver(cls, field_name: str, field_type: type) -> Callable[..., Any]:
         """
-        Wählt anhand des Feldtyps den passenden Resolver aus.
+        Selects and returns the appropriate resolver function for a given field based on its type and name.
+        
+        For fields ending with `_list` and referencing a `GeneralManager` subclass, returns a list resolver supporting pagination and filtering. For `Measurement` fields, returns a measurement resolver. For all other fields, returns a standard resolver.
         """
         if field_name.endswith("_list") and issubclass(field_type, GeneralManager):
             return cls._createListResolver(
@@ -475,14 +539,40 @@ 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]:
+        """
+        Return a paginated GraphQL ObjectType for the given item type, creating and caching it if it does not already exist.
+        
+        Parameters:
+            page_type_name (str): The name to use for the paginated type.
+        
+        Returns:
+            type[graphene.ObjectType]: A GraphQL ObjectType with `items` (list of item_type) and `pageInfo` (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.
+        Adds paginated 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.
+        The list query field supports 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 corresponding resolvers.
         """
         if not issubclass(generalManagerClass, GeneralManager):
             raise TypeError(
@@ -509,10 +599,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
@@ -608,7 +699,7 @@ class GraphQL:
         """
         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 accepts input fields defined by the manager's interface, filters out fields with `NOT_PROVIDED` values, and calls the manager's `create` method with the provided arguments and the current user's ID. If creation succeeds, it returns a dictionary with a success flag and the created instance; if an error occurs, a GraphQL error is raised. 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.
@@ -625,9 +716,9 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Create a new instance of the manager class using the provided arguments.
+            Creates a new instance of the manager class with 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.
+            Filters out fields set to `NOT_PROVIDED` before creation. Returns a dictionary containing a success flag and the created instance keyed by the manager class name. Raises a GraphQL error if creation fails.
             """
             try:
                 kwargs = {
@@ -639,14 +730,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,
             }
 
@@ -680,7 +770,7 @@ class GraphQL:
         """
         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, invokes 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 and the updated instance. If the manager class does not define an `Interface`, returns None.
         
         Returns:
             The generated Graphene mutation class, or None if no interface is defined.
@@ -697,14 +787,14 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Updates a GeneralManager instance with the provided fields.
+            Updates an instance of the specified GeneralManager class with the provided field values.
             
             Parameters:
-                info (GraphQLResolveInfo): The GraphQL resolver context, typically containing user and request information.
+                info (GraphQLResolveInfo): The GraphQL resolver context, containing user and request information.
                 **kwargs: Fields 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: Contains 'success' (bool) and the updated instance keyed by its class name.
             """
             try:
                 manager_id = kwargs.pop("id", None)
@@ -712,13 +802,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,
             }
 
@@ -752,10 +842,10 @@ class GraphQL:
         """
         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. If the manager class does not define an interface, returns None.
         
         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 +859,14 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Deactivates an instance of the specified GeneralManager class and returns the operation result.
+            Deactivates an instance of the specified GeneralManager class and returns the result.
+            
+            Parameters:
+                info (GraphQLResolveInfo): GraphQL resolver context containing user information.
+                **kwargs: Arguments including the instance ID to deactivate.
             
             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: Contains "success" (bool) and the deactivated instance keyed by its class name.
             """
             try:
                 manager_id = kwargs.pop("id", None)
@@ -783,13 +874,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 +904,32 @@ class GraphQL:
                 "mutate": delete_mutation,
             },
         )
+
+    @staticmethod
+    def _handleGraphQLError(error: Exception) -> None:
+        """
+        Raises a GraphQLError with an appropriate error code based on the type of exception.
+        
+        If the error is a PermissionError, the code is set to "PERMISSION_DENIED". For ValueError or ValidationError, the code is "BAD_USER_INPUT". All other exceptions result in a code of "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",
+                },
+            )

{generalmanager-0.11.2 → generalmanager-0.12.0}/src/general_manager/api/mutation.py

@@ -21,19 +21,23 @@ from general_manager.permission.mutationPermission import MutationPermission
 
 def graphQlMutation(permission: Optional[Type[MutationPermission]] = None):
     """
-    Decorator that transforms a function into a GraphQL mutation class and registers it for use in a Graphene-based API.
-
-    The decorated function must have type hints for all parameters (except `info`) and a return annotation. The decorator dynamically generates a mutation class with arguments and output fields based on the function's signature and return type. It also enforces authentication if `auth_required` is set to True, returning an error if the user is not authenticated.
-
+    Decorator that converts a function into a GraphQL mutation class for use with Graphene, automatically generating argument and output fields from the function's signature and type annotations.
+    
+    The decorated function must provide type hints for all parameters (except `info`) and a return annotation. The decorator dynamically constructs a mutation class with appropriate Graphene fields, enforces permission checks if a `permission` class is provided, and registers the mutation for use in the GraphQL API.
+    
     Parameters:
-        needs_role (Optional[str]): Reserved for future use to specify a required user role.
-        auth_required (bool): If True, the mutation requires an authenticated user.
-
+        permission (Optional[Type[MutationPermission]]): An optional permission class to enforce access control on the mutation.
+    
     Returns:
         Callable: A decorator that registers the mutation and returns the original function.
     """
 
     def decorator(fn):
+        """
+        Decorator that transforms a function into a GraphQL mutation class compatible with Graphene.
+        
+        Analyzes the decorated function's signature and type hints to dynamically generate a mutation class with appropriate argument and output fields. Handles permission checks if a permission class is provided, manages mutation execution, and registers the mutation for use in the GraphQL API. On success, returns output fields and a `success` flag; on error, returns only `success=False`.
+        """
         sig = inspect.signature(fn)
         hints = get_type_hints(fn)
 
@@ -86,10 +90,9 @@ def graphQlMutation(permission: Optional[Type[MutationPermission]] = None):
 
         Arguments = type("Arguments", (), arg_fields)
 
-        # Build output fields: success, errors, + fn return types
+        # Build output fields: success + fn return types
         outputs = {
             "success": graphene.Boolean(required=True),
-            "errors": graphene.List(graphene.String),
         }
         return_ann: type | tuple[type] | None = hints.get("return")
         if return_ann is None:
@@ -120,28 +123,35 @@ def graphQlMutation(permission: Optional[Type[MutationPermission]] = None):
         # Define mutate method
         def _mutate(root, info, **kwargs):
 
+            """
+            Handles the execution of a GraphQL mutation, including permission checks, result unpacking, and error handling.
+            
+            Returns:
+                An instance of the mutation class with output fields populated from the mutation result and a success status.
+            """
             if permission:
                 permission.check(kwargs, info.context.user)
             try:
                 result = fn(info, **kwargs)
                 data = {}
                 if isinstance(result, tuple):
-                    # unpack according to outputs ordering after success/errors
+                    # unpack according to outputs ordering after success
                     for (field, _), val in zip(
-                        outputs.items(), [None, None] + list(result)
+                        outputs.items(),
+                        [None, *list(result)],  # None for success field to be set later
                     ):
-                        # skip success/errors
-                        if field in ("success", "errors"):
+                        # skip success
+                        if field == "success":
                             continue
                         data[field] = val
                 else:
-                    only = next(k for k in outputs if k not in ("success", "errors"))
+                    only = next(k for k in outputs if k != "success")
                     data[only] = result
                 data["success"] = True
-                data["errors"] = []
                 return mutation_class(**data)
             except Exception as e:
-                return mutation_class(**{"success": False, "errors": [str(e)]})
+                GraphQL._handleGraphQLError(e)
+                return mutation_class(**{"success": False})
 
         # Assemble class dict
         class_dict = {

{generalmanager-0.11.2 → generalmanager-0.12.0}/src/general_manager/measurement/measurement.py

@@ -22,20 +22,18 @@ for currency in currency_units:
 class Measurement:
     def __init__(self, value: Decimal | float | int | str, unit: str):
         """
-        Create a Measurement with the specified numeric value and unit.
-
-        Parameters:
-            value: The numeric value to associate with the unit. Accepts Decimal, float, int, or a string convertible to Decimal.
-            unit: The unit of measurement as a string.
-
+        Initialize a Measurement with a numeric value and unit.
+        
+        Creates a Measurement instance by converting the provided value to a Decimal and associating it with the specified unit. Accepts numeric types or strings convertible to Decimal.
+        
         Raises:
-            TypeError: If the value cannot be converted to a Decimal.
+            ValueError: If the value cannot be converted to a Decimal.
         """
         if not isinstance(value, (Decimal, float, int)):
             try:
                 value = Decimal(str(value))
             except Exception:
-                raise TypeError("Value must be a Decimal, float, int or compatible.")
+                raise ValueError("Value must be a Decimal, float, int or compatible.")
         if not isinstance(value, Decimal):
             value = Decimal(str(value))
         self.__quantity = ureg.Quantity(self.formatDecimal(value), unit)
@@ -228,15 +226,15 @@ class Measurement:
 
     def __mul__(self, other: Any) -> Measurement:
         """
-        Multiply this measurement by another measurement or a numeric value.
+        Multiplies this measurement by another measurement or a numeric value.
         
-        Multiplying two currency measurements is not allowed. When multiplying by another measurement, the resulting measurement combines their units. When multiplying by a numeric value, only the magnitude is scaled.
+        Multiplication between two currency measurements is not permitted. When multiplying by another measurement, the resulting measurement combines their units. When multiplying by a numeric value, only the magnitude is scaled.
         
         Returns:
-            Measurement: The result of the multiplication.
+            Measurement: A new measurement representing the product.
         
         Raises:
-            TypeError: If both operands are currency measurements, or if the operand is not a Measurement or numeric value.
+            TypeError: If both operands are currency measurements, or if the operand is neither a Measurement nor a numeric value.
         """
         if isinstance(other, Measurement):
             if self.is_currency() and other.is_currency():