GeneralManager 0.87.6__tar.gz → 0.88.0__tar.gz

{generalmanager-0.87.6/src/GeneralManager.egg-info → generalmanager-0.88.0}/PKG-INFO

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

{generalmanager-0.87.6 → generalmanager-0.88.0}/pyproject.toml

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

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

{generalmanager-0.87.6 → generalmanager-0.88.0}/src/general_manager/api/graphql.py

@@ -109,7 +109,7 @@ from general_manager.api.graphql_mutations import (
     generate_delete_mutation_class as _generate_delete_mutation_class_fn,
 )
 from general_manager.api.graphql_output import (
-    GraphQLOutputIdentityMetadataError,
+    _value_field_is_identifier,
     create_output_field_resolver,
     map_graphql_output_annotation,
     resolve_output_type_hints,
@@ -390,6 +390,9 @@ class GraphQL:
     _subscription_payload_registry: ClassVar[dict[str, type[graphene.ObjectType]]] = {}
     graphql_type_registry: ClassVar[dict[str, type[graphene.ObjectType]]] = {}
     graphql_output_type_registry: ClassVar[dict[str, type[graphene.ObjectType]]] = {}
+    _value_input_type_cache: ClassVar[
+        dict[type[GraphQLType], type[graphene.InputObjectType]]
+    ] = {}
     graphql_filter_type_registry: ClassVar[
         dict[str, type[graphene.InputObjectType]]
     ] = {}
@@ -440,6 +443,7 @@ class GraphQL:
         cls._subscription_payload_registry = {}
         cls.graphql_type_registry = {}
         cls.graphql_output_type_registry = {}
+        cls._value_input_type_cache = {}
         cls.graphql_filter_type_registry = {}
         cls.graphql_capability_type_registry = {}
         cls.manager_registry = {}
@@ -532,11 +536,7 @@ class GraphQL:
         )
         fields: dict[str, graphene.Field] = {}
         for declared_field in dataclasses.fields(output_class):
-            is_identifier = declared_field.metadata.get("is_identifier", False)
-            if not isinstance(is_identifier, bool):
-                raise GraphQLOutputIdentityMetadataError(
-                    output_name, declared_field.name, is_identifier
-                )
+            is_identifier = _value_field_is_identifier(output_name, declared_field)
             mapped = map_graphql_output_annotation(
                 hints[declared_field.name],
                 owner_name=output_name,

{generalmanager-0.87.6 → generalmanager-0.88.0}/src/general_manager/api/graphql_output.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping
-from dataclasses import dataclass, replace
+from dataclasses import Field, dataclass, replace
 from datetime import date, datetime
 from decimal import Decimal
 import sys
@@ -51,6 +51,14 @@ class GraphQLOutputIdentityMetadataError(TypeError):
         )
 
 
+def _value_field_is_identifier(owner_name: str, field: Field[object]) -> bool:
+    """Read the shared identity metadata on a GraphQL value field."""
+    flag = field.metadata.get("is_identifier", False)
+    if not isinstance(flag, bool):
+        raise GraphQLOutputIdentityMetadataError(owner_name, field.name, flag)
+    return flag
+
+
 @dataclass(frozen=True, slots=True)
 class _MappedAnnotation:
     """Internal Graphene type metadata before a field wrapper is mounted."""
@@ -144,19 +152,14 @@ def _lazy_registry_type(
     return lambda: registry[name]
 
 
-def _map_collection_annotation(
+def _collection_element_annotation(
     annotation: object,
     *,
     owner_name: str,
     field_name: str,
-    manager_registry: Mapping[str, type[GeneralManager]],
-    manager_type_registry: Mapping[str, type[graphene.ObjectType]],
-    output_class_registry: Mapping[str, type[GraphQLType]],
-    output_type_registry: Mapping[str, type[graphene.ObjectType]],
-    measurement_type: type[graphene.ObjectType],
-    scalar_mapper: Callable[[type], type],
-    is_identifier: bool = False,
-) -> _MappedAnnotation:
+    is_identifier: bool,
+) -> object:
+    """Validate a homogeneous collection and return its element annotation."""
     origin = get_origin(annotation)
     if origin not in (list, tuple, set):
         raise _annotation_error(owner_name, field_name, annotation)
@@ -178,6 +181,28 @@ def _map_collection_annotation(
         if identity_type not in (int, str, UUID):
             raise _annotation_error(owner_name, field_name, annotation)
 
+    return element_annotation
+
+
+def _map_collection_annotation(
+    annotation: object,
+    *,
+    owner_name: str,
+    field_name: str,
+    manager_registry: Mapping[str, type[GeneralManager]],
+    manager_type_registry: Mapping[str, type[graphene.ObjectType]],
+    output_class_registry: Mapping[str, type[GraphQLType]],
+    output_type_registry: Mapping[str, type[graphene.ObjectType]],
+    measurement_type: type[graphene.ObjectType],
+    scalar_mapper: Callable[[type], type],
+    is_identifier: bool = False,
+) -> _MappedAnnotation:
+    element_annotation = _collection_element_annotation(
+        annotation,
+        owner_name=owner_name,
+        field_name=field_name,
+        is_identifier=is_identifier,
+    )
     element = _map_annotation(
         element_annotation,
         owner_name=owner_name,
@@ -201,6 +226,23 @@ def _map_collection_annotation(
     )
 
 
+def _map_value_scalar_annotation(
+    annotation: object,
+    *,
+    owner_name: str,
+    field_name: str,
+    scalar_mapper: Callable[[type], type],
+    is_identifier: bool,
+) -> object:
+    """Map value scalars without the legacy mapper's fallback to String."""
+    if is_identifier:
+        if annotation in (int, str, UUID):
+            return graphene.ID
+    elif safe_issubclass(annotation, (str, bool, int, float, Decimal, datetime, date)):
+        return scalar_mapper(annotation)
+    raise _annotation_error(owner_name, field_name, annotation)
+
+
 def _map_non_optional_value(
     annotation: object,
     *,
@@ -245,10 +287,14 @@ def _map_non_optional_value(
         )
 
     if is_identifier:
-        if annotation not in (int, str, UUID):
-            raise _annotation_error(owner_name, field_name, annotation)
         return _MappedAnnotation(
-            graphene.ID,
+            _map_value_scalar_annotation(
+                annotation,
+                owner_name=owner_name,
+                field_name=field_name,
+                scalar_mapper=scalar_mapper,
+                is_identifier=True,
+            ),
             annotation,
             nullable=False,
             contains_measurement=False,
@@ -284,25 +330,13 @@ def _map_non_optional_value(
             contains_measurement=True,
         )
 
-    if not isinstance(annotation, type):
-        raise _annotation_error(owner_name, field_name, annotation)
-
-    # Keep this allowlist explicit.  The legacy mapper intentionally falls back
-    # to String for unknown classes, which is unsafe for output declarations.
-    if safe_issubclass(annotation, bool):
-        scalar_type = scalar_mapper(annotation)
-    elif safe_issubclass(annotation, str):
-        scalar_type = scalar_mapper(annotation)
-    elif safe_issubclass(annotation, int):
-        scalar_type = scalar_mapper(annotation)
-    elif safe_issubclass(annotation, (float, Decimal)):
-        scalar_type = scalar_mapper(annotation)
-    elif safe_issubclass(annotation, datetime):
-        scalar_type = scalar_mapper(annotation)
-    elif safe_issubclass(annotation, date):
-        scalar_type = scalar_mapper(annotation)
-    else:
-        raise _annotation_error(owner_name, field_name, annotation)
+    scalar_type = _map_value_scalar_annotation(
+        annotation,
+        owner_name=owner_name,
+        field_name=field_name,
+        scalar_mapper=scalar_mapper,
+        is_identifier=False,
+    )
     return _MappedAnnotation(
         scalar_type,
         annotation,

{generalmanager-0.87.6 → generalmanager-0.88.0}/src/general_manager/api/graphql_type.py

@@ -1,4 +1,4 @@
-"""Frozen value declarations for GraphQL output objects."""
+"""Frozen value declarations for GraphQL objects."""
 
 from __future__ import annotations
 
@@ -8,7 +8,7 @@ from typing import ClassVar, cast, dataclass_transform
 
 @dataclass_transform(field_specifiers=(Field, field), frozen_default=True)
 class GraphQLTypeMeta(type):
-    """Create and register frozen dataclass-based GraphQL output declarations."""
+    """Create and register frozen dataclass-based GraphQL value declarations."""
 
     _registered_types: ClassVar[list[type[GraphQLType]]] = []
 
@@ -29,18 +29,22 @@ class GraphQLTypeMeta(type):
 
 
 class GraphQLType(metaclass=GraphQLTypeMeta):
-    """Frozen annotated value exposed only as a GraphQL output object.
+    """Frozen annotated value for GraphQL outputs and custom mutation inputs.
+
+    A custom mutation parameter annotated with a concrete subclass uses the
+    generated input object named ``<ClassName>Input``. Its constructor fields
+    are populated before the mutation's permission check and resolver run.
 
     Use ``dataclasses.field(metadata={"is_identifier": True})`` to declare
     native int, str, or UUID identity fields and their supported homogeneous
     collections. Schema generation preserves annotation nullability and native
-    values while exposing ID scalars. Missing or false metadata keeps existing
-    output types; other flag values fail schema generation with TypeError.
+    values while exposing ID scalars. Missing or false metadata keeps ordinary
+    scalar types; other flag values fail schema generation with TypeError.
     """
 
 
 def get_registered_graphql_types() -> tuple[type[GraphQLType], ...]:
-    """Return the declared GraphQL output types in creation order."""
+    """Return the declared GraphQL value types in creation order."""
     return tuple(GraphQLTypeMeta._registered_types)
 
 

{generalmanager-0.87.6 → generalmanager-0.88.0}/src/general_manager/api/mutation.py

@@ -2,6 +2,9 @@
 
 import inspect
 from collections.abc import Sequence
+from dataclasses import MISSING, dataclass, fields
+from decimal import Decimal
+from functools import partial
 from typing import (
     Callable,
     TypeVar,
@@ -16,15 +19,28 @@ from typing import (
     Protocol,
     cast,
 )
+from uuid import UUID
+
 import graphene
+from django.core.exceptions import ValidationError
 from graphql import GraphQLError, GraphQLResolveInfo
 
 from general_manager.api.graphql import GraphQL
 from general_manager.api.graphql_identifiers import map_identification_scalar
-from general_manager.api.graphql_output import create_output_field_resolver
+from general_manager.api.graphql_output import (
+    _collection_element_annotation,
+    _map_value_scalar_annotation,
+    _unwrap_optional_annotation as _unwrap_value_optional,
+    _value_field_is_identifier,
+    create_output_field_resolver,
+    resolve_output_type_hints,
+)
+from general_manager.api.graphql_type import GraphQLType, get_registered_graphql_types
 from general_manager.manager.general_manager import GeneralManager
+from general_manager.measurement.measurement import Measurement
 
 from general_manager.utils.format_string import snake_to_camel
+from general_manager.utils.type_checks import safe_issubclass
 from general_manager.permission.mutation_permission import MutationPermission
 from types import UnionType
 
@@ -232,7 +248,7 @@ def _normalize_mutation_arguments(
     annotations: MutationAnnotations,
     kwargs: MutationKwargs,
 ) -> MutationKwargs:
-    """Normalize manager-typed arguments and lists using resolver annotations."""
+    """Normalize mutation values using the resolver annotations."""
     normalized = dict(kwargs)
     for name, annotation in annotations.items():
         if name not in normalized:
@@ -255,7 +271,7 @@ def _unwrap_optional_annotation(annotation: object) -> tuple[bool, object]:
 
 
 def _normalize_mutation_value(annotation: object, value: object) -> object:
-    """Recursively normalize manager values while preserving explicit ``None``."""
+    """Normalize annotated value objects, managers, and lists."""
     if value is None:
         return None
     _, concrete = _unwrap_optional_annotation(annotation)
@@ -267,12 +283,20 @@ def _normalize_mutation_value(annotation: object, value: object) -> object:
         ]
     if _is_general_manager_type(concrete):
         return _normalize_manager_argument(concrete, value)
+    if safe_issubclass(concrete, GraphQLType) and not isinstance(value, concrete):
+        if (
+            not isinstance(value, _GraphQLTypeInput)
+            or value.declaration is not concrete
+        ):
+            message = f"Expected coerced GraphQL input for {concrete.__name__}."
+            raise TypeError(message)
+        return value.construct()
     return value
 
 
 def _mutation_input_type(annotation: object) -> object:
     """Map nested mutation input annotations to unmounted Graphene types."""
-    nullable, concrete = _unwrap_optional_annotation(annotation)
+    _, concrete = _unwrap_optional_annotation(annotation)
     origin = get_origin(concrete)
     if origin is list or origin is List:
         inner_annotation = get_args(concrete)[0]
@@ -285,7 +309,9 @@ def _mutation_input_type(annotation: object) -> object:
         if _uses_single_id_input(concrete):
             return graphene.ID
         return _get_or_create_manager_input_type(concrete)
-    del nullable
+    if safe_issubclass(concrete, GraphQLType):
+        declaration = cast(type[GraphQLType], concrete)
+        return lambda: _get_or_create_value_input_type(declaration)
     return GraphQL._map_field_to_graphene_base_type(cast(type, concrete))
 
 
@@ -300,6 +326,8 @@ def _build_mutation_argument_field(
     input_type = _mutation_input_type(annotation)
     if isinstance(input_type, graphene.List):
         return graphene.List(input_type.of_type, **kwargs)
+    if inspect.isfunction(input_type):
+        return graphene.Argument(input_type, **kwargs)
     return cast(Callable[..., object], input_type)(**kwargs)
 
 
@@ -349,6 +377,173 @@ def _sequence_argument(value: object) -> Sequence[object]:
     return (value,)
 
 
+@dataclass(frozen=True, slots=True)
+class _GraphQLTypeInput:
+    """A coerced input object awaiting construction at the mutation boundary."""
+
+    declaration: type[GraphQLType]
+    construct: Callable[[], GraphQLType]
+
+
+@dataclass(frozen=True, slots=True)
+class _ValueInputField:
+    type: object
+    nullable: bool
+    normalize: Callable[[object], object]
+
+
+def _normalize_value_identifier(
+    identity_type: type, field_path: str, value: object
+) -> object:
+    try:
+        return identity_type(str(value))
+    except ValueError as error:
+        message = f"{field_path} must be a valid {identity_type.__name__} ID."
+        raise ValidationError(message) from error
+
+
+def _map_value_input_field(
+    annotation: object,
+    *,
+    owner_name: str,
+    field_name: str,
+    is_identifier: bool,
+) -> _ValueInputField:
+    """Map a declared field and prepare its GraphQL-to-Python conversion."""
+    nullable, concrete = _unwrap_value_optional(
+        annotation, owner_name=owner_name, field_name=field_name
+    )
+    origin = get_origin(concrete)
+    field_path = f"{owner_name}.{field_name}"
+    convert: Callable[[object], object] | None = None
+
+    if origin is not None:
+        element = _collection_element_annotation(
+            concrete,
+            owner_name=owner_name,
+            field_name=field_name,
+            is_identifier=is_identifier,
+        )
+        item = _map_value_input_field(
+            element,
+            owner_name=owner_name,
+            field_name=field_name,
+            is_identifier=is_identifier,
+        )
+        item_type = item.type if item.nullable else graphene.NonNull(item.type)
+        input_type = graphene.List(item_type)
+
+        def convert_collection(value: object) -> object:
+            return origin(
+                item.normalize(element) for element in _sequence_argument(value)
+            )
+
+        convert = convert_collection
+    elif not is_identifier and safe_issubclass(concrete, (GraphQLType, GeneralManager)):
+        input_type = _mutation_input_type(concrete)
+        convert = partial(_normalize_mutation_value, concrete)
+    elif not is_identifier and safe_issubclass(concrete, Measurement):
+        input_type = GraphQL._map_field_to_graphene_base_type(concrete)
+    else:
+        input_type = _map_value_scalar_annotation(
+            concrete,
+            owner_name=owner_name,
+            field_name=field_name,
+            scalar_mapper=GraphQL._map_field_to_graphene_base_type,
+            is_identifier=is_identifier,
+        )
+        if is_identifier and (concrete is int or concrete is UUID):
+            convert = partial(_normalize_value_identifier, concrete, field_path)
+
+    def normalize(value: object) -> object:
+        if value is None and not nullable:
+            # Defaults let clients omit a field, while the Python field
+            # annotation still determines whether it accepts explicit null.
+            message = f"{field_path} cannot be null."
+            raise ValidationError(message)
+        if value is None:
+            return None
+        if convert is not None:
+            return convert(value)
+        return Decimal(str(value)) if concrete is Decimal else value
+
+    return _ValueInputField(input_type, nullable, normalize)
+
+
+def _get_or_create_value_input_type(
+    declaration: type[GraphQLType],
+) -> type[graphene.InputObjectType]:
+    """Build an input object only when the schema references the declaration."""
+    cache = GraphQL._value_input_type_cache
+    cached = cache.get(declaration)
+    if cached is not None:
+        return cached
+
+    input_name = f"{declaration.__name__}Input"
+    if input_name == "ChecksumInput":
+        message = f"GraphQL input type '{input_name}' is reserved for file uploads."
+        raise ValueError(message)
+    declarations = {
+        value_type.__name__: value_type for value_type in get_registered_graphql_types()
+    }
+    declarations[declaration.__name__] = declaration
+    hints = resolve_output_type_hints(
+        declaration,
+        manager_registry=GraphQL.manager_registry,
+        output_class_registry=declarations,
+    )
+    input_fields: dict[str, graphene.InputField] = {}
+    conversions: dict[str, _ValueInputField] = {}
+    omitted_as_none: dict[str, object] = {}
+    for declared_field in fields(declaration):
+        if not declared_field.init:
+            continue
+        name = declared_field.name
+        mapped = _map_value_input_field(
+            hints[name],
+            owner_name=declaration.__name__,
+            field_name=name,
+            is_identifier=_value_field_is_identifier(
+                declaration.__name__, declared_field
+            ),
+        )
+        has_default = (
+            declared_field.default is not MISSING
+            or declared_field.default_factory is not MISSING
+        )
+        input_fields[name] = graphene.InputField(
+            mapped.type, required=not (mapped.nullable or has_default)
+        )
+        conversions[name] = mapped
+        if mapped.nullable and not has_default:
+            omitted_as_none[name] = None
+
+    if not input_fields:
+        message = f"{declaration.__name__} must declare an initializer field for GraphQL input."
+        raise TypeError(message)
+
+    def construct(values: dict[str, object]) -> GraphQLType:
+        kwargs = {
+            name: conversions[name].normalize(value) for name, value in values.items()
+        }
+        return declaration(**(omitted_as_none | kwargs))
+
+    def wrap_input(values: dict[str, object]) -> _GraphQLTypeInput:
+        # Delay constructors, manager lookups, and validation until the
+        # mutation's existing error and permission boundary is active.
+        return _GraphQLTypeInput(declaration, partial(construct, values))
+
+    generated = type(
+        input_name,
+        (graphene.InputObjectType,),
+        {"Meta": type("Meta", (), {"container": wrap_input})},
+    )
+    # Keep field names separate from Graphene's reserved class attributes.
+    generated._meta.fields.update(input_fields)  # type: ignore[attr-defined]
+    cache[declaration] = generated
+    return generated
+
+
 def graph_ql_mutation(
     _func: FuncT | type[MutationPermission] | None = None,
     permission: type[MutationPermission] | None = None,
@@ -381,7 +576,12 @@ def graph_ql_mutation(
     ``None`` unchanged, constructs mapping inputs with ``manager_class(**value)``,
     and constructs non-mapping inputs with ``manager_class(value)``. For
     ``list[Manager]`` and ``List[Manager]`` arguments, each list item follows
-    that same manager normalization before permission checks and resolver calls.
+    that same manager normalization. Concrete ``GraphQLType`` subclasses
+    generate ``<ClassName>Input`` objects, including when used as list elements
+    or nullable arguments. Their fields are recursively converted to native
+    Python values and passed to the dataclass constructor. Manager references
+    inside the input use the same normalization as direct manager arguments.
+    Conversion completes before permission checks and resolver calls.
     Other supported Python annotations are mapped through
     ``GraphQL._map_field_to_graphene_base_type``.