graphql-codegen 0.1.0__py3-none-any.whl

graphql_codegen/_generator/_imports.py

@@ -0,0 +1,166 @@
+import ast
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import assert_never, final
+
+from graphql_codegen._generator._ast_nodes import import_as
+from graphql_codegen._generator._naming import (
+    ABC,
+    BUILTINS,
+    COMPAT,
+    ENUM,
+    INJECTION,
+    INPUT,
+    OMITTED,
+    REFLECTION,
+    RUNTIME,
+    SCALAR,
+    TYPING,
+    SchemaSpellings,
+)
+from graphql_codegen._generator.spelling import ast_str
+
+SCHEMA_PACKAGE = "schema"
+DOCUMENT_PACKAGE = "document"
+SCALAR_MODULE = "_scalar"
+INJECTION_MODULE = "injection"
+RUNTIME_PACKAGE = "runtime"
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class PackageModule:
+    path: tuple[str, ...]
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class OutsideModule:
+    package: str
+
+
+type GeneratedModule = PackageModule | OutsideModule
+"""A generated module, by where it sits, which decides how it imports the package's own modules.
+
+- :class:`PackageModule`: relatively, so that the package works wherever it is written.
+- :class:`OutsideModule`: absolutely, since a relative import cannot leave its top-level package.
+
+"""
+
+
+def _import_from(
+    module: str | None, /, *, name: str, alias: str, level: int
+) -> ast.ImportFrom:
+    return ast.ImportFrom(
+        module=module, names=[ast.alias(name=name, asname=alias)], level=level
+    )
+
+
+def _from_package(
+    submodule: str | None, /, *, name: str, alias: str, module: GeneratedModule
+) -> ast.ImportFrom:
+    match module:
+        case PackageModule(path=path):
+            # How far up the package is.
+            return _import_from(submodule, name=name, alias=alias, level=len(path) + 1)
+        case OutsideModule(package=package):
+            return _import_from(
+                package if submodule is None else f"{package}.{submodule}",
+                name=name,
+                alias=alias,
+                level=0,
+            )
+        case _ as never:
+            assert_never(never)
+
+
+def helper_imports(
+    statements: Sequence[ast.stmt],
+    /,
+    *,
+    module: GeneratedModule,
+    schema_spellings: SchemaSpellings,
+) -> list[ast.stmt]:
+    used = {
+        node.id
+        for statement in statements
+        for node in ast.walk(statement)
+        if isinstance(node, ast.Name)
+    }
+    imports: list[ast.stmt] = []
+
+    for helper, module_name in (
+        (BUILTINS, "builtins"),
+        (ABC, "collections.abc"),
+        (TYPING, "typing"),
+    ):
+        if ast_str(helper) in used:
+            imports.append(import_as(module_name, helper))
+
+    # From the runtime's copy, so that the package needs `typing_extensions` only before Python 3.15.
+    if ast_str(COMPAT) in used:
+        imports.append(
+            _from_package(
+                RUNTIME_PACKAGE, name="_compat", alias=ast_str(COMPAT), module=module
+            )
+        )
+
+    if ast_str(INJECTION) in used:
+        imports.append(
+            _from_package(
+                RUNTIME_PACKAGE,
+                name="injection",
+                alias=ast_str(INJECTION),
+                module=module,
+            )
+        )
+
+    if ast_str(REFLECTION) in used:
+        imports.append(
+            _from_package(
+                RUNTIME_PACKAGE,
+                name="_reflection",
+                alias=ast_str(REFLECTION),
+                module=module,
+            )
+        )
+
+    if ast_str(RUNTIME) in used:
+        imports.append(
+            _from_package(
+                None, name=RUNTIME_PACKAGE, alias=ast_str(RUNTIME), module=module
+            )
+        )
+
+    if ast_str(OMITTED) in used:
+        imports.append(
+            _from_package(
+                RUNTIME_PACKAGE, name="OMITTED", alias=ast_str(OMITTED), module=module
+            )
+        )
+
+    for helper, schema_module in (
+        (ENUM, schema_spellings.enum_module),
+        (INPUT, schema_spellings.input_module),
+    ):
+        if ast_str(helper) in used:
+            imports.append(
+                # A module of the `schema` package reaches its siblings directly.
+                _import_from(None, name=schema_module, alias=ast_str(helper), level=1)
+                if module == PackageModule(path=(SCHEMA_PACKAGE,))
+                else _from_package(
+                    SCHEMA_PACKAGE,
+                    name=schema_module,
+                    alias=ast_str(helper),
+                    module=module,
+                ),
+            )
+
+    if ast_str(SCALAR) in used:
+        imports.append(
+            _from_package(
+                None, name=SCALAR_MODULE, alias=ast_str(SCALAR), module=module
+            )
+        )
+
+    return imports

graphql_codegen/_generator/_injector.py

@@ -0,0 +1,267 @@
+import ast
+from collections.abc import Mapping, Set as AbstractSet
+from functools import reduce
+from typing import cast
+
+from graphql import (
+    GraphQLError,
+    GraphQLInputObjectType,
+    GraphQLInputType,
+    GraphQLList,
+    GraphQLNonNull,
+    GraphQLSchema,
+    GraphQLType,
+    OperationDefinitionNode,
+    VariableDefinitionNode,
+    get_named_type,
+    is_list_type,
+    is_non_null_type,
+    type_from_ast,
+)
+
+from graphql_codegen._generator._annotation import AnnotationBuilder
+from graphql_codegen._generator._ast_nodes import (
+    docstring,
+    name,
+    qualified,
+    subscript,
+    union,
+)
+from graphql_codegen._generator._naming import ABC, INJECTION, OMITTED
+from graphql_codegen._generator._schema import as_non_null
+from graphql_codegen._generator._typed_dict import Key, emit_closed
+from graphql_codegen._generator.spelling import SettledSpelling
+
+
+def get_injections(
+    operation: OperationDefinitionNode,
+    /,
+    *,
+    schema: GraphQLSchema,
+    injector_names: AbstractSet[str],
+) -> dict[str, dict[tuple[str, ...], GraphQLInputType]]:
+    """An injected variable goes in the variables themselves, `()`.
+
+    An injected field goes in every input object holding it, at any depth, since a mutation takes the transaction it belongs to inside its input rather than beside it.
+    A static path can say neither "every element of this list" nor the unbounded depth of a recursive input type, so an injected field reached that way fails generation rather than being silently left out.
+    """
+    injections: dict[str, dict[tuple[str, ...], GraphQLInputType]] = {}
+
+    def holds_injected_field(
+        input_type: GraphQLInputObjectType, /, *, seen: set[str]
+    ) -> bool:
+        if input_type.name in seen:
+            return False
+
+        seen.add(input_type.name)
+        return any(
+            field_name in injector_names
+            or (
+                isinstance(
+                    named_type := get_named_type(field.type), GraphQLInputObjectType
+                )
+                and holds_injected_field(named_type, seen=seen)
+            )
+            for field_name, field in input_type.fields.items()
+        )
+
+    def visit_input(
+        input_type: GraphQLInputObjectType,
+        wrapped_type: GraphQLType,
+        /,
+        *,
+        path: tuple[str, ...],
+        ancestors: tuple[str, ...],
+        definition: VariableDefinitionNode,
+    ) -> None:
+        nullable_type = (
+            wrapped_type.of_type
+            if isinstance(wrapped_type, GraphQLNonNull)
+            else wrapped_type
+        )
+
+        if is_list_type(nullable_type) or input_type.name in ancestors:
+            if holds_injected_field(input_type, seen=set()):
+                raise GraphQLError(
+                    f"Cannot inject into `${path[0]}`: an injected field is reached through a list or a recursive input type, which no static path can express.",
+                    nodes=definition,
+                )
+            return
+
+        for field_name, field in input_type.fields.items():
+            if field_name in injector_names:
+                injections.setdefault(field_name, {})[path] = field.type
+                continue
+
+            named_type = get_named_type(field.type)
+
+            if isinstance(named_type, GraphQLInputObjectType):
+                visit_input(
+                    named_type,
+                    field.type,
+                    path=(*path, field_name),
+                    ancestors=(*ancestors, input_type.name),
+                    definition=definition,
+                )
+
+    for definition in operation.variable_definitions or ():
+        variable_name = definition.variable.name.value
+
+        variable_type = type_from_ast(schema, definition.type)
+        assert variable_type is not None, (
+            "Validation guarantees that a variable's type exists."
+        )
+
+        if variable_name in injector_names:
+            # Validation guarantees that a variable's type is an input type.
+            injections.setdefault(variable_name, {})[()] = cast(
+                "GraphQLInputType", variable_type
+            )
+            continue
+        named_type = get_named_type(variable_type)
+
+        if isinstance(named_type, GraphQLInputObjectType):
+            visit_input(
+                named_type,
+                variable_type,
+                path=(variable_name,),
+                ancestors=(),
+                definition=definition,
+            )
+
+    return injections
+
+
+def get_injected_types(
+    injections: Mapping[str, Mapping[str, Mapping[tuple[str, ...], GraphQLInputType]]],
+    /,
+    *,
+    injector_names: AbstractSet[str],
+) -> dict[str, GraphQLInputType]:
+    """An injector supplies one value for every position it is injected into, so they must all have the same type, nullability aside.
+
+    Its type is then the strictest: non-null wherever any position is, since a non-null value suits a nullable position too, while an injector cannot tell which position it is called for.
+    """
+    positions: dict[str, dict[str, str]] = {}
+    types: dict[str, list[GraphQLInputType]] = {}
+
+    for operation_name, operation_injections in injections.items():
+        for injector_name, targets in operation_injections.items():
+            for path, type_ in targets.items():
+                position = "$" + ".".join((*path, injector_name))
+                # Spelled without `!`, so that positions differing only by nullability agree.
+                spelling = str(type_).replace("!", "")
+                positions.setdefault(injector_name, {}).setdefault(
+                    spelling, f"`{position}` in `{operation_name}`"
+                )
+                types.setdefault(injector_name, []).append(type_)
+
+    for injector_name, by_type in positions.items():
+        if len(by_type) > 1:
+            raise GraphQLError(
+                f"Expected `{injector_name}` to have one type, nullability aside, wherever it is injected, but it is "
+                + " and ".join(
+                    f"`{type_}` at {position}" for type_, position in by_type.items()
+                )
+                + "."
+            )
+
+    # An injector injected nowhere, a misspelled one for instance, has no position to take its type from.
+    if nowhere := sorted(injector_names - types.keys()):
+        raise ValueError(
+            f"Expected `{nowhere[0]}` to be injected somewhere, but no operation sends a variable or an input field of that name."
+        )
+
+    return {
+        injector_name: reduce(_strictest, injector_types)
+        for injector_name, injector_types in types.items()
+    }
+
+
+def _strictest(left: GraphQLInputType, right: GraphQLInputType, /) -> GraphQLInputType:
+    non_null = isinstance(left, GraphQLNonNull) or isinstance(right, GraphQLNonNull)
+    left = left.of_type if isinstance(left, GraphQLNonNull) else left
+    right = right.of_type if isinstance(right, GraphQLNonNull) else right
+    merged = (
+        GraphQLList(_strictest(left.of_type, right.of_type))
+        if isinstance(left, GraphQLList) and isinstance(right, GraphQLList)
+        else left
+    )
+    return as_non_null(merged) if non_null else merged
+
+
+def emit_injector_module(
+    injected_types: Mapping[str, GraphQLInputType], /, *, annotations: AnnotationBuilder
+) -> list[ast.stmt]:
+    """The mapping of functions is a :class:`typing.TypedDict`, rather than keyword arguments, so that a name no keyword can spell is injected too, and a misspelled name fails type checking with every type checker.
+
+    It builds the runtime's private :class:`~graphql_codegen.runtime.injection._Injectors` rather than being given to a client, so that a client only calls injectors that were type checked.
+    """
+    functions_spelling, function_spelling = (
+        SettledSpelling("InjectorFunctions"),
+        SettledSpelling("injectors"),
+    )
+    # Local to the function, so that nothing can clash with it.
+    functions = SettledSpelling("functions")
+    keys: list[Key] = []
+
+    for injector_name, type_ in sorted(injected_types.items()):
+        value = annotations.build(
+            type_, position="input", object_annotation=None, bare_inputs=False
+        )
+
+        # A nullable input accepts omission too, while a non-null one accepts neither.
+        if not is_non_null_type(type_):
+            value = union(value, name(OMITTED))
+
+        keys.append(
+            Key(
+                name=injector_name,
+                annotation=subscript(
+                    qualified(ABC, "Callable"), ast.List(elts=[], ctx=ast.Load()), value
+                ),
+                required=False,
+                description="",
+            ),
+        )
+
+    return [
+        *emit_closed(
+            functions_spelling,
+            keys,
+            description="The functions supplying each injected value, by name.\n\nWhere the value may be null, one returning `OMITTED` leaves it out, and one returning `None` sends `null`.",
+            bare_names=frozenset({functions_spelling, function_spelling}),
+        ),
+        ast.FunctionDef(
+            name=function_spelling,
+            args=ast.arguments(
+                posonlyargs=[
+                    ast.arg(arg=functions, annotation=name(functions_spelling))
+                ],
+                args=[],
+                kwonlyargs=[],
+                kw_defaults=[],
+                defaults=[],
+            ),
+            body=[
+                docstring(
+                    "Return what a client calls to supply the injected values, each serialized as its type says."
+                ),
+                ast.Return(
+                    value=ast.Call(
+                        func=qualified(INJECTION, "_Injectors"),
+                        args=[name(functions)],
+                        keywords=[
+                            ast.keyword(
+                                arg="injector_functions_type",
+                                value=name(functions_spelling),
+                            )
+                        ],
+                    ),
+                ),
+            ],
+            decorator_list=[],
+            returns=qualified(INJECTION, "_Injectors"),
+            type_params=[],
+        ),
+    ]

graphql_codegen/_generator/_merge.py

@@ -0,0 +1,149 @@
+from dataclasses import replace
+from functools import cache
+from typing import Final
+
+from graphql import (
+    DocumentNode,
+    FieldNode,
+    FragmentDefinitionNode,
+    FragmentSpreadNode,
+    InlineFragmentNode,
+    NameNode,
+    Node,
+    OperationDefinitionNode,
+    OperationType,
+    SelectionNode,
+    SelectionSetNode,
+    VariableNode,
+    Visitor,
+    print_ast,
+    visit,
+)
+
+from graphql_codegen._generator._document import get_transitively_spread_fragments
+from graphql_codegen.runtime._sigil import SIGIL
+
+# No printed name can hold it, and a string escapes it, so it only ever stands for a sigil.
+_PLACEHOLDER: Final = "\x00"
+_ESCAPED_SIGIL: Final = "\\u" + f"{ord(SIGIL):04x}"
+
+
+class _References(Visitor):
+    def __init__(self) -> None:
+        super().__init__()
+        self.fragment_names: list[str] = []
+        self.uses_variables = False
+
+    def enter_fragment_spread(self, node: FragmentSpreadNode, *_args: object) -> None:
+        self.fragment_names.append(node.name.value)
+
+    def enter_variable(self, _node: VariableNode, *_args: object) -> None:
+        self.uses_variables = True
+
+
+def _references(node: Node, /) -> _References:
+    references = _References()
+    visit(node, references)
+    return references
+
+
+class _SuffixVariables(Visitor):
+    def enter_variable(self, node: VariableNode, *_args: object) -> VariableNode:
+        return VariableNode(name=NameNode(value=f"{node.name.value}{_PLACEHOLDER}"))
+
+
+def print_merge_template(document: DocumentNode, /) -> str:
+    """Print *document*, holding one operation and the fragments it uses as the server receives them, with the sigil wherever its index in a merge goes, so that merging at runtime is string replacement.
+
+    After the response name of each root field, as its alias, and after the name of each variable, in its definition and wherever it is used.
+    The sigil is written as a character no printed name or string can hold, then swapped in once a literal sigil in a string has been escaped, so that every sigil left is one.
+    A subscription, which selects a single root field, and an operation with directives of its own, which would apply to the whole merge, cannot be merged: they get no sigil.
+
+    Two things cannot keep their shape in a merge, and are inlined as inline fragments, which the server executes the same:
+
+    - a fragment spread at the root, since the fields it selects are root fields and need aliasing;
+    - a fragment using variables, since each operation of a merge suffixes its variables differently, while a fragment is defined once for all of them.
+    """
+    (operation,) = (
+        definition
+        for definition in document.definitions
+        if isinstance(definition, OperationDefinitionNode)
+    )
+
+    if operation.operation is OperationType.SUBSCRIPTION or operation.directives:
+        return print_ast(document).replace(SIGIL, _ESCAPED_SIGIL)
+
+    fragments = {
+        definition.name.value: definition
+        for definition in document.definitions
+        if isinstance(definition, FragmentDefinitionNode)
+    }
+
+    @cache
+    def uses_variables(fragment_name: str, /) -> bool:
+        references = _references(fragments[fragment_name])
+        return references.uses_variables or any(
+            map(uses_variables, references.fragment_names)
+        )
+
+    def rewrite(selection_set: SelectionSetNode, /, *, root: bool) -> SelectionSetNode:
+        selections: list[SelectionNode] = []
+
+        for selection in selection_set.selections:
+            match selection:
+                case FragmentSpreadNode() if root or uses_variables(
+                    selection.name.value
+                ):
+                    fragment = fragments[selection.name.value]
+                    selections.append(
+                        InlineFragmentNode(
+                            type_condition=fragment.type_condition,
+                            directives=selection.directives,
+                            selection_set=rewrite(fragment.selection_set, root=root),
+                        ),
+                    )
+                case FieldNode() if root:
+                    selections.append(
+                        replace(
+                            selection,
+                            alias=NameNode(
+                                value=f"{(selection.alias or selection.name).value}{_PLACEHOLDER}"
+                            ),
+                            selection_set=None
+                            if selection.selection_set is None
+                            else rewrite(selection.selection_set, root=False),
+                        ),
+                    )
+                case FieldNode(selection_set=SelectionSetNode() as field_selection_set):
+                    selections.append(
+                        replace(
+                            selection,
+                            selection_set=rewrite(field_selection_set, root=False),
+                        )
+                    )
+                case InlineFragmentNode():
+                    # The fields of an inline fragment at the root are root fields too.
+                    selections.append(
+                        replace(
+                            selection,
+                            selection_set=rewrite(selection.selection_set, root=root),
+                        )
+                    )
+                case _:
+                    selections.append(selection)
+
+        return SelectionSetNode(selections=tuple(selections))
+
+    templated = visit(
+        replace(operation, selection_set=rewrite(operation.selection_set, root=True)),
+        _SuffixVariables(),
+    )
+    text = print_ast(
+        DocumentNode(
+            definitions=(
+                templated,
+                *get_transitively_spread_fragments(templated, definitions=fragments),
+            )
+        )
+    )
+    return text.replace(SIGIL, _ESCAPED_SIGIL).replace(_PLACEHOLDER, SIGIL)

graphql_codegen/_generator/_naming.py

@@ -0,0 +1,80 @@
+from collections.abc import Collection, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Final, final
+
+from graphql_codegen._generator.spelling import (
+    PendingSpelling,
+    SettledSpelling,
+    settle_names,
+)
+
+COMPAT: Final = PendingSpelling("_compat")
+TYPING: Final = PendingSpelling("_typing")
+ABC: Final = PendingSpelling("_abc")
+BUILTINS: Final = PendingSpelling("_builtins")
+RUNTIME: Final = PendingSpelling("_runtime")
+ENUM: Final = PendingSpelling("_enum")
+INPUT: Final = PendingSpelling("_input")
+INJECTION: Final = PendingSpelling("_injection")
+REFLECTION: Final = PendingSpelling("_reflection")
+SCALAR: Final = PendingSpelling("_scalar")
+OMITTED: Final = PendingSpelling("_OMITTED")
+"""The runtime's sentinel, imported by name: pyright only takes a sentinel as a type when it is spelled as a bare name."""
+
+
+def nested_type_name(path: Sequence[str], /) -> str:
+    """Private, since the GraphQL way for code to name a shape is a fragment.
+
+    Prefixed by the root, so that a type checker message naming the type also names its operation or fragment.
+    """
+    return f"_{'_'.join(path)}"
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class OperationSpellings:
+    operation: SettledSpelling
+    variables: SettledSpelling
+    data: SettledSpelling
+
+
+def operation_spellings(
+    operations: Sequence[SettledSpelling], /, *, taken: Collection[SettledSpelling]
+) -> dict[SettledSpelling, OperationSpellings]:
+    """The operations keep theirs, so that a type is suffixed rather than an operation: `Get`'s data type is `GetData_1` in a module also holding an operation `GetData`."""
+    types = settle_names(
+        [
+            f"{operation}{suffix}"
+            for operation in operations
+            for suffix in ("Variables", "Data")
+        ],
+        taken={*operations, *taken},
+    )
+    return {
+        operation: OperationSpellings(
+            operation=operation,
+            variables=types[f"{operation}Variables"],
+            data=types[f"{operation}Data"],
+        )
+        for operation in operations
+    }
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class SchemaSpellings:
+    type_spellings: Mapping[str, SettledSpelling]
+
+    enum_module: SettledSpelling
+    input_module: SettledSpelling
+
+
+def schema_spellings(type_names: Collection[str], /) -> SchemaSpellings:
+    types = settle_names(sorted(type_names), taken=set())
+    # The package re-exports every type, so its modules must not be spelled like any of them.
+    modules = settle_names(["enum", "input"], taken=set(types.values()))
+    return SchemaSpellings(
+        type_spellings=types,
+        enum_module=modules["enum"],
+        input_module=modules["input"],
+    )