graphql-codegen 0.1.0__py3-none-any.whl

graphql_codegen/_generator/_operation.py

@@ -0,0 +1,223 @@
+import ast
+from collections.abc import Collection, Mapping, Sequence, Set as AbstractSet
+from dataclasses import replace
+from typing import Final
+
+from graphql import (
+    REMOVE,
+    DirectiveNode,
+    DocumentNode,
+    ExecutableDefinitionNode,
+    FragmentDefinitionNode,
+    GraphQLSchema,
+    OperationDefinitionNode,
+    StringValueNode,
+    VariableDefinitionNode,
+    Visitor,
+    is_non_null_type,
+    type_from_ast,
+    visit,
+)
+
+from graphql_codegen._generator._annotation import AnnotationBuilder
+from graphql_codegen._generator._ast_nodes import (
+    constant,
+    documented,
+    name,
+    qualified,
+    subscript,
+)
+from graphql_codegen._generator._naming import (
+    BUILTINS,
+    RUNTIME,
+    TYPING,
+    OperationSpellings,
+)
+from graphql_codegen._generator._typed_dict import Key, emit_closed
+
+
+def description_text(description: StringValueNode | None, /) -> str:
+    return "" if description is None else description.value
+
+
+def _undescribed[Node: ExecutableDefinitionNode | VariableDefinitionNode](
+    node: Node, /
+) -> Node | None:
+    if node.description is None:
+        return None
+
+    return replace(node, description=None)
+
+
+class _StripForServer(Visitor):
+    """Remove what the server does not need: this library's directives, and descriptions.
+
+    The spec says descriptions must not affect execution, so on the wire they would only cost bytes, and a server whose parser predates them would reject the whole request.
+    They become docstrings instead.
+
+    Block strings are printed as ordinary ones, with the same value, so that no token spans lines, since the runtime slices a merge template at blank lines, and so that a sigil in a string can be escaped, which a block string cannot do.
+    """
+
+    def __init__(self, directive_names: AbstractSet[str], /) -> None:
+        super().__init__()
+        self._directive_names: Final = directive_names
+
+    def enter_directive(self, node: DirectiveNode, *_args: object) -> object:
+        return REMOVE if node.name.value in self._directive_names else None
+
+    def enter_string_value(self, node: StringValueNode, *_args: object) -> object:
+        if not node.block:
+            return None
+
+        return replace(node, block=False)
+
+    def enter_operation_definition(
+        self, node: OperationDefinitionNode, *_args: object
+    ) -> object:
+        return _undescribed(node)
+
+    def enter_fragment_definition(
+        self, node: FragmentDefinitionNode, *_args: object
+    ) -> object:
+        return _undescribed(node)
+
+    def enter_variable_definition(
+        self, node: VariableDefinitionNode, *_args: object
+    ) -> object:
+        return _undescribed(node)
+
+
+def strip_for_server(
+    operation: OperationDefinitionNode,
+    /,
+    *,
+    fragments: Sequence[FragmentDefinitionNode],
+    client_directive_names: AbstractSet[str],
+) -> DocumentNode:
+    document = DocumentNode(definitions=(operation, *fragments))
+    result = visit(document, _StripForServer(client_directive_names))
+    assert isinstance(result, DocumentNode)
+    return result
+
+
+def emit_variables_type(
+    operation: OperationDefinitionNode,
+    /,
+    *,
+    spellings: OperationSpellings,
+    schema: GraphQLSchema,
+    annotations: AnnotationBuilder,
+    injector_names: AbstractSet[str],
+) -> list[ast.stmt]:
+    """A variable is :data:`typing.Required` only when it is non-null *and* has no default, for the same reason as an input field: a default makes it optional for the client, and the document carries the default so Python never needs to."""
+    keys: list[Key] = []
+
+    for definition in operation.variable_definitions or ():
+        variable_name = definition.variable.name.value
+
+        if variable_name in injector_names:
+            # Injected: the client inserts it, so a caller must not be able to.
+            continue
+
+        variable_type = type_from_ast(schema, definition.type)
+        assert variable_type is not None, (
+            "Validation guarantees that a variable's type exists."
+        )
+        keys.append(
+            Key(
+                name=variable_name,
+                annotation=annotations.build(
+                    variable_type,
+                    position="input",
+                    object_annotation=None,
+                    bare_inputs=False,
+                ),
+                required=is_non_null_type(variable_type)
+                and definition.default_value is None,
+                description=description_text(definition.description),
+            ),
+        )
+
+    return emit_closed(
+        spellings.variables,
+        keys,
+        description="",
+        bare_names=frozenset(),
+    )
+
+
+def _frozenset(elements: Sequence[ast.expr], /) -> ast.expr:
+    return ast.Call(
+        func=qualified(BUILTINS, "frozenset"),
+        args=[ast.Set(elts=list(elements))],
+        keywords=[],
+    )
+
+
+def emit_operation_constant(
+    operation: OperationDefinitionNode,
+    /,
+    *,
+    graphql_name: str,
+    spellings: OperationSpellings,
+    document: str,
+    injections: Mapping[str, Collection[tuple[str, ...]]],
+) -> list[ast.stmt]:
+    """The operation's description is the constant's docstring, since the constant is what callers reach for.
+
+    It is annotated although its type parameters could be inferred from the call: pyrefly widens an inferred `Literal['mutation']` to :class:`str` in a list comprehension passed to the clients' overloads, which then match none.
+    The document is inlined rather than given a constant of its own: a triple quoted literal reads as GraphQL wherever it sits.
+    """
+    # In the order of the class's fields, which is the order things happen in.
+    keywords = [
+        ast.keyword(arg="operation_type", value=constant(operation.operation.value)),
+        # The GraphQL name, which is what the server knows the operation by.
+        ast.keyword(arg="name", value=constant(graphql_name)),
+        ast.keyword(arg="document", value=constant(document)),
+        # What crosses the wire is read off the variables and data types at runtime: they are the only description of it.
+        ast.keyword(arg="variables_type", value=name(spellings.variables)),
+    ]
+
+    if injections:
+        keywords.append(
+            ast.keyword(
+                arg="injections",
+                value=ast.Dict(
+                    keys=[constant(injector_name) for injector_name in injections],
+                    values=[
+                        _frozenset(
+                            [
+                                ast.Tuple(
+                                    elts=[constant(part) for part in target],
+                                    ctx=ast.Load(),
+                                )
+                                for target in targets
+                            ],
+                        )
+                        for targets in injections.values()
+                    ],
+                ),
+            ),
+        )
+
+    keywords.append(ast.keyword(arg="data_type", value=name(spellings.data)))
+
+    # Not annotated `Final`: pyright would then reject the package re-exporting it from the module named like it.
+    return documented(
+        ast.AnnAssign(
+            target=ast.Name(id=spellings.operation, ctx=ast.Store()),
+            annotation=subscript(
+                qualified(RUNTIME, "Operation"),
+                subscript(
+                    qualified(TYPING, "Literal"), constant(operation.operation.value)
+                ),
+                name(spellings.variables),
+                name(spellings.data),
+            ),
+            value=ast.Call(
+                func=qualified(RUNTIME, "Operation"), args=[], keywords=keywords
+            ),
+            simple=1,
+        ),
+        text=description_text(operation.description),
+    )

graphql_codegen/_generator/_scalar.py

@@ -0,0 +1,76 @@
+import ast
+from collections.abc import Mapping
+from typing import assert_never
+
+from graphql import GraphQLScalarType, GraphQLSchema
+
+from graphql_codegen._generator._ast_nodes import name, qualified, subscript, type_alias
+from graphql_codegen._generator._naming import BUILTINS, REFLECTION, TYPING
+from graphql_codegen._generator.dotted_name import Builtin, Import, Reference
+from graphql_codegen._generator.spelling import (
+    PendingSpelling,
+    SettledSpelling,
+    ast_str,
+)
+from graphql_codegen.scalar import Scalar
+
+
+def check_scalars(scalars: Mapping[str, Scalar], /, *, schema: GraphQLSchema) -> None:
+    for scalar_name in sorted(scalars):
+        if not isinstance(schema.type_map.get(scalar_name), GraphQLScalarType):
+            # A config value naming nothing in the schema, not a mistyped one.
+            raise ValueError(f"Expected `{scalar_name}` to be a scalar of the schema.")  # noqa: TRY004
+
+
+def emit_scalars(
+    scalars: Mapping[str, Scalar], /, *, spellings: Mapping[str, SettledSpelling]
+) -> list[ast.stmt]:
+    imported: dict[Import, PendingSpelling] = {}
+
+    def reference(path: Reference, /) -> ast.expr:
+        match path:
+            case Builtin(name=builtin_name):
+                return qualified(BUILTINS, builtin_name)
+            case Import(name=imported_name):
+                return name(
+                    imported.setdefault(path, PendingSpelling(f"_{imported_name}"))
+                )
+            case _ as never:
+                assert_never(never)
+
+    body: list[ast.stmt] = []
+
+    for scalar_name, scalar in sorted(scalars.items()):
+        if scalar.codec is None:
+            value = reference(scalar._type_reference)
+        else:
+            value = subscript(
+                qualified(TYPING, "Annotated"),
+                reference(scalar._type_reference),
+                ast.Call(
+                    func=qualified(REFLECTION, "Codec"),
+                    args=[],
+                    keywords=[
+                        ast.keyword(
+                            arg="decode",
+                            value=reference(scalar.codec._decode_reference),
+                        ),
+                        ast.keyword(
+                            arg="encode",
+                            value=reference(scalar.codec._encode_reference),
+                        ),
+                    ],
+                ),
+            )
+
+        body.append(type_alias(spellings[scalar_name], value))
+
+    imports = [
+        ast.ImportFrom(
+            module=import_.module,
+            names=[ast.alias(name=import_.name, asname=ast_str(spelling))],
+            level=import_.level,
+        )
+        for import_, spelling in imported.items()
+    ]
+    return [*imports, *body]

graphql_codegen/_generator/_schema.py

@@ -0,0 +1,46 @@
+from graphql import (
+    DirectiveLocation,
+    GraphQLDirective,
+    GraphQLNonNull,
+    GraphQLNullableType,
+    GraphQLSchema,
+    validate_schema,
+)
+
+
+def prepare_schema(
+    schema: GraphQLSchema, /, *, non_null_directive_name: str | None
+) -> GraphQLSchema:
+    """Declares the client directive, if any, so that documents using it validate."""
+    if non_null_directive_name is not None:
+        schema = _declare_directive(schema, name=non_null_directive_name)
+
+    # The schema operations are validated against, whose result graphql-core's `validate()` then reuses.
+    if errors := validate_schema(schema):
+        raise ExceptionGroup("The schema is invalid", errors)
+
+    return schema
+
+
+def _declare_directive(schema: GraphQLSchema, /, *, name: str) -> GraphQLSchema:
+    if schema.get_directive(name) is not None:
+        raise ValueError(
+            f"Expected the schema to declare no `@{name}`, the name of the client directive."
+        )
+
+    directive = GraphQLDirective(
+        name,
+        locations=[DirectiveLocation.FIELD],
+        description="Assert that this field is not null, even though the schema allows it to be.",
+    )
+
+    # A new dictionary on each call, so setting a key of it leaves *schema* alone.
+    kwargs = schema.to_kwargs()
+    kwargs["directives"] = (*schema.directives, directive)
+    return GraphQLSchema(**kwargs)
+
+
+def as_non_null[Nullable: GraphQLNullableType](
+    type_: Nullable | GraphQLNonNull[Nullable], /
+) -> GraphQLNonNull[Nullable]:
+    return type_ if isinstance(type_, GraphQLNonNull) else GraphQLNonNull(type_)

graphql_codegen/_generator/_schema_type.py

@@ -0,0 +1,334 @@
+import ast
+from collections.abc import Mapping, Set as AbstractSet
+
+from graphql import (
+    DocumentNode,
+    FieldNode,
+    GraphQLEnumType,
+    GraphQLInputField,
+    GraphQLInputObjectType,
+    GraphQLNamedType,
+    GraphQLSchema,
+    TypeInfo,
+    TypeInfoVisitor,
+    Undefined,
+    VariableDefinitionNode,
+    Visitor,
+    get_named_type,
+    is_non_null_type,
+    type_from_ast,
+    visit,
+)
+
+from graphql_codegen._generator._annotation import AnnotationBuilder
+from graphql_codegen._generator._ast_nodes import (
+    constant,
+    documented,
+    module,
+    name,
+    qualified,
+    subscript,
+    type_alias,
+    union,
+)
+from graphql_codegen._generator._naming import TYPING, SchemaSpellings
+from graphql_codegen._generator._schema import as_non_null
+from graphql_codegen._generator._structs import StructTypes, get_struct_input_name
+from graphql_codegen._generator._typed_dict import Key, emit_closed
+from graphql_codegen._generator.spelling import (
+    PendingSpelling,
+    SettledSpelling,
+    ast_str,
+)
+
+
+def _is_required(field: GraphQLInputField, /) -> bool:
+    """In GraphQL a non-null input field with a default is optional for the client: the `!` constrains the value, not whether one must be sent.
+
+    Reading `!` alone would force callers to pass values the server would happily supply.
+    """
+    # graphql-core holds a default given as a Python value in `default_value`, and one given as a GraphQL literal, as SDL gives it, in `default`.
+    return (
+        is_non_null_type(field.type)
+        and field.default_value is Undefined
+        and field.default is None
+    )
+
+
+def _reached[Type: GraphQLNamedType](
+    schema: GraphQLSchema, kind: type[Type], /, *, schema_spellings: SchemaSpellings
+) -> list[Type]:
+    return [
+        type_
+        for type_ in schema.type_map.values()
+        if isinstance(type_, kind) and type_.name in schema_spellings.type_spellings
+    ]
+
+
+def get_reached_type_names(
+    document: DocumentNode,
+    /,
+    *,
+    schema: GraphQLSchema,
+    struct_types: StructTypes | None,
+    injector_names: AbstractSet[str],
+) -> frozenset[str]:
+    """Only the enums and input types *document* sends or receives, so that the generated code grows with the documents rather than with the schema.
+
+    An input type is reached through a variable, and reaches the types of its fields in turn, a `@oneOf` input's members included.
+    An enum is reached like an input type, or when a field of its type is selected.
+    The input type of a struct payload is reached when the payload is selected, since the payload has its shape.
+    An injected field reaches nothing, since it is removed from its input type.
+    """
+    pending: list[GraphQLNamedType] = []
+    type_info = TypeInfo(schema)
+
+    class _Visitor(Visitor):
+        def enter_variable_definition(
+            self, node: VariableDefinitionNode, *_args: object
+        ) -> None:
+            variable_type = type_from_ast(schema, node.type)
+            assert variable_type is not None, (
+                "Validation guarantees that a variable's type exists."
+            )
+            pending.append(get_named_type(variable_type))
+
+        def enter_field(self, node: FieldNode, *_args: object) -> None:
+            field_type = type_info.get_type()
+            parent_type = type_info.get_parent_type()
+            assert field_type is not None and parent_type is not None, (
+                "Validation guarantees that a selected field exists."
+            )
+
+            pending.append(get_named_type(field_type))
+            struct_input_name = get_struct_input_name(
+                parent_type,
+                node.name.value,
+                struct_types=struct_types,
+            )
+
+            if struct_input_name is not None:
+                pending.append(schema.type_map[struct_input_name])
+
+    visit(document, TypeInfoVisitor(type_info, _Visitor()))
+
+    reached: set[str] = set()
+
+    while pending:
+        named_type = pending.pop()
+
+        if (
+            named_type.name in reached
+            or named_type.name.startswith("__")
+            or not isinstance(named_type, GraphQLEnumType | GraphQLInputObjectType)
+        ):
+            continue
+
+        reached.add(named_type.name)
+
+        if isinstance(named_type, GraphQLInputObjectType):
+            pending.extend(
+                get_named_type(field.type)
+                for field_name, field in named_type.fields.items()
+                if field_name not in injector_names
+            )
+
+    return frozenset(reached)
+
+
+def emit_enums(
+    schema: GraphQLSchema, /, *, schema_spellings: SchemaSpellings
+) -> list[ast.stmt]:
+    """Closed, with no `"%future added value"` sentinel and no per-enum openness config, which costs far less here than in a validating generator.
+
+    A validating client turns a member it has not heard of into a hard failure, so a server adding one breaks every older client.
+    Nothing is validated here, so an unknown member reaches the caller as the string the server sent, and the `Literal` is guidance: a `match` may keep a catch-all arm, which really runs, or `assert_never`, which a type checker enforces.
+    """
+    return [
+        statement
+        for enum_type in _reached(
+            schema, GraphQLEnumType, schema_spellings=schema_spellings
+        )
+        for statement in documented(
+            type_alias(
+                schema_spellings.type_spellings[enum_type.name],
+                subscript(
+                    qualified(TYPING, "Literal"),
+                    *(constant(member) for member in enum_type.values),
+                ),
+            ),
+            text=enum_type.description or "",
+        )
+    ]
+
+
+def _emit_one_of(
+    input_type: GraphQLInputObjectType,
+    /,
+    *,
+    fields: Mapping[str, GraphQLInputField],
+    annotations: AnnotationBuilder,
+    spelling: SettledSpelling,
+    bare_names: frozenset[str],
+) -> list[ast.stmt]:
+    """`closed=True` makes a type checker reject a value with two keys, the only enforcement there is, since nothing is validated at runtime.
+
+    `total=` could never express it: it governs whether *declared* keys are required, never whether *undeclared* ones are allowed.
+    """
+    body: list[ast.stmt] = []
+    member_spellings: list[PendingSpelling] = []
+
+    for field_name, field in fields.items():
+        member_spelling = PendingSpelling(f"_{spelling}_{field_name}")
+        member_spellings.append(member_spelling)
+        body.extend(
+            emit_closed(
+                member_spelling,
+                [
+                    Key(
+                        name=field_name,
+                        # The spec declares every member nullable but rejects a null one, so the member that is set can never be `None`.
+                        annotation=annotations.build(
+                            as_non_null(field.type),
+                            position="input",
+                            bare_inputs=True,
+                            object_annotation=None,
+                        ),
+                        description=field.description or "",
+                        required=True,
+                    ),
+                ],
+                description="",
+                bare_names=bare_names,
+            ),
+        )
+
+    assert member_spellings, f"`{input_type.name}` is `@oneOf` but has no field."
+    body.extend(
+        documented(
+            type_alias(
+                spelling,
+                union(*(name(member_spelling) for member_spelling in member_spellings)),
+            ),
+            text=input_type.description or "",
+        ),
+    )
+    return body
+
+
+def emit_inputs(
+    schema: GraphQLSchema,
+    /,
+    *,
+    annotations: AnnotationBuilder,
+    schema_spellings: SchemaSpellings,
+    injector_names: AbstractSet[str],
+) -> list[ast.stmt]:
+    """Input types are not a DAG: the schema has reference cycles, all passing through the nullable members of a `@oneOf` input, which the spec permits since only *non-null* cycles are unsatisfiable.
+
+    One module with postponed annotations lets them name each other freely.
+    """
+    input_types = _reached(
+        schema, GraphQLInputObjectType, schema_spellings=schema_spellings
+    )
+    bare_names = frozenset(
+        schema_spellings.type_spellings[input_type.name] for input_type in input_types
+    )
+    body: list[ast.stmt] = []
+
+    for input_type in input_types:
+        fields = {
+            field_name: field
+            for field_name, field in input_type.fields.items()
+            # An injected field is set by the client, so a caller must not be able to.
+            if field_name not in injector_names
+        }
+
+        if input_type.is_one_of:
+            body.extend(
+                _emit_one_of(
+                    input_type,
+                    fields=fields,
+                    annotations=annotations,
+                    spelling=schema_spellings.type_spellings[input_type.name],
+                    bare_names=bare_names,
+                ),
+            )
+            continue
+
+        body.extend(
+            emit_closed(
+                schema_spellings.type_spellings[input_type.name],
+                [
+                    Key(
+                        name=field_name,
+                        annotation=annotations.build(
+                            field.type,
+                            position="input",
+                            bare_inputs=True,
+                            object_annotation=None,
+                        ),
+                        required=_is_required(field),
+                        description=field.description or "",
+                    )
+                    for field_name, field in fields.items()
+                ],
+                description=input_type.description or "",
+                bare_names=bare_names,
+            ),
+        )
+
+    return [*_defer_functional_references(body, input_names=bare_names), *body]
+
+
+def _defer_functional_references(
+    body: list[ast.stmt], /, *, input_names: frozenset[SettledSpelling]
+) -> list[ast.stmt]:
+    """Postponed evaluation only covers annotations: the values of a functional TypedDict are an ordinary dict, evaluated when the statement runs, so an input it names that is defined later, or the type itself, would not exist yet.
+
+    Each such name is referenced through a `type` alias instead, whose value is evaluated lazily.
+    """
+    aliases: dict[SettledSpelling, PendingSpelling] = {}
+
+    for statement in body:
+        if not (
+            isinstance(statement, ast.Assign) and isinstance(statement.value, ast.Call)
+        ):
+            continue
+
+        for node in ast.walk(statement.value):
+            if isinstance(node, ast.Name) and node.id in input_names:
+                alias = aliases.setdefault(
+                    SettledSpelling(node.id), PendingSpelling(f"_{node.id}_Ref")
+                )
+                node.id = ast_str(alias)
+
+    return [
+        type_alias(alias, name(input_name)) for input_name, alias in aliases.items()
+    ]
+
+
+def emit_schema_package(
+    schema: GraphQLSchema, /, *, schema_spellings: SchemaSpellings
+) -> ast.Module:
+    """Re-export every enum and input type of the package, which share GraphQL's single type name space, by a star import of each module.
+
+    It leaves out names starting with an underscore: every helper alias and nested type, and any GraphQL type named that way, which the typing spec keeps private anyway and which its public module still holds.
+
+    """
+    exports = {
+        schema_spellings.enum_module: _reached(
+            schema, GraphQLEnumType, schema_spellings=schema_spellings
+        ),
+        schema_spellings.input_module: _reached(
+            schema, GraphQLInputObjectType, schema_spellings=schema_spellings
+        ),
+    }
+    return module(
+        [
+            ast.ImportFrom(module=module_name, names=[ast.alias(name="*")], level=1)
+            for module_name, types in exports.items()
+            # An empty `from ... import` is a syntax error.
+            if types
+        ],
+    )