graphql-codegen 0.1.0__py3-none-any.whl

graphql_codegen/_generator/_selection.py

@@ -0,0 +1,246 @@
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Final, cast, final
+
+from graphql import (
+    BooleanValueNode,
+    DirectiveNode,
+    FieldNode,
+    FragmentDefinitionNode,
+    FragmentSpreadNode,
+    GraphQLCompositeType,
+    GraphQLIncludeDirective,
+    GraphQLOutputType,
+    GraphQLSchema,
+    GraphQLSkipDirective,
+    InlineFragmentNode,
+    OperationDefinitionNode,
+    SelectionSetNode,
+    TypeInfo,
+    is_type_sub_type_of,
+    type_from_ast,
+)
+
+
+def inclusion(directives: Sequence[DirectiveNode], /) -> bool | None:
+    """Whether `@skip` and `@include` include a selection, or ``None`` when a variable decides.
+
+    graphql-core's :func:`~graphql.execution.collect_fields.should_include_node` needs the variables' values, which only exist at runtime.
+    A directive without its `if` argument, which validation reports, decides nothing either.
+    """
+    included: bool | None = True
+
+    for directive in directives:
+        name = directive.name.value
+
+        if name not in {GraphQLSkipDirective.name, GraphQLIncludeDirective.name}:
+            continue
+
+        value = next(
+            (
+                argument.value
+                for argument in directive.arguments or ()
+                if argument.name.value == "if"
+            ),
+            None,
+        )
+
+        if not isinstance(value, BooleanValueNode):
+            included = None
+        elif value.value == (name == GraphQLSkipDirective.name):
+            return False
+
+    return included
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class SelectedField:
+    name: str
+    alias: str | None
+    type: GraphQLOutputType
+    parent_type: GraphQLCompositeType
+    directive_names: frozenset[str]
+    description: str
+    selection_set: "SelectionSet | None"
+    skippable: bool
+
+    @property
+    def response_name(self) -> str:
+        return self.alias or self.name
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class TypeCondition:
+    type: GraphQLCompositeType
+    selection_set: "SelectionSet"
+    skippable: bool
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class SelectionSet:
+    """A selection set, resolved, with the selections under a type condition kept apart.
+
+    ``fields`` holds what is selected on every value, ``conditions`` what is selected only on some, and ``fragment_names`` the fragments spread here.
+    All three are in document order, which keeps emission deterministic.
+    Spreads are recorded rather than expanded, so that emission can reuse the fragment's own type as a base class.
+    """
+
+    type: GraphQLCompositeType
+    fields: tuple[SelectedField, ...]
+    conditions: tuple[TypeCondition, ...]
+    fragment_names: tuple[str, ...]
+    description: str
+
+
+@final
+class SelectionResolver:
+    """Resolve the type of every field an operation or a fragment selects.
+
+    This is the part a generator inferring types itself easily gets wrong, on `interface` chains notably, and graphql-core supplies all of it, so nothing here infers a type:
+
+    - :class:`~graphql.TypeInfo` tracks, during a recursive descent calling its :meth:`~graphql.TypeInfo.enter` and :meth:`~graphql.TypeInfo.leave`, the definition of each field, meta fields included, and the type each selection set selects on;
+    - :func:`~graphql.is_type_sub_type_of` tells whether a fragment's type condition holds for every value of a type.
+
+    What is left is what graphql-core leaves to its caller: following fragment spreads, and `@skip` and `@include`, whose variables only have values at runtime.
+    """
+
+    def __init__(
+        self,
+        fragment_definitions: Mapping[str, FragmentDefinitionNode],
+        /,
+        *,
+        schema: GraphQLSchema,
+    ) -> None:
+        self._fragment_definitions: Final = fragment_definitions
+        self._schema: Final = schema
+
+    def resolve(
+        self, definition: OperationDefinitionNode | FragmentDefinitionNode, /
+    ) -> SelectionSet:
+        type_info = TypeInfo(self._schema)
+        # Entering the definition pushes the operation's root type, or the fragment's type condition.
+        type_info.enter(definition)
+        selection_set = self._resolve_selection_set(
+            definition.selection_set, type_info=type_info
+        )
+        type_info.leave(definition)
+        return selection_set
+
+    def _resolve_selection_set(
+        self, node: SelectionSetNode, /, *, type_info: TypeInfo
+    ) -> SelectionSet:
+        # Entering it makes the type it selects on the parent type of what it selects.
+        type_info.enter(node)
+        parent_type = type_info.get_parent_type()
+        assert parent_type is not None, (
+            "Validation guarantees that a selection set selects on a composite type."
+        )
+        fields: list[SelectedField] = []
+        conditions: list[TypeCondition] = []
+        fragment_names: list[str] = []
+
+        for selection in node.selections:
+            # `None` rather than empty when the selection has none.
+            included = inclusion(selection.directives or ())
+
+            # Never in the response, so not in the type either.
+            if included is False:
+                continue
+
+            skippable = included is None
+
+            match selection:
+                case FieldNode():
+                    fields.append(
+                        self._resolve_field(
+                            selection, type_info=type_info, skippable=skippable
+                        )
+                    )
+                case InlineFragmentNode():
+                    type_info.enter(selection)
+                    # Its type condition, or, without one, the enclosing type.
+                    selection_set = self._resolve_selection_set(
+                        selection.selection_set, type_info=type_info
+                    )
+                    type_info.leave(selection)
+                    conditions.append(
+                        TypeCondition(
+                            type=selection_set.type,
+                            selection_set=selection_set,
+                            skippable=skippable,
+                        )
+                    )
+                case FragmentSpreadNode():
+                    # `TypeInfo` does not follow a spread: the fragment is resolved on its own, by name.
+                    fragment_name = selection.name.value
+                    fragment_type = cast(
+                        "GraphQLCompositeType",
+                        type_from_ast(
+                            self._schema,
+                            self._fragment_definitions[fragment_name].type_condition,
+                        ),
+                    )
+
+                    if not skippable and is_type_sub_type_of(
+                        self._schema, parent_type, fragment_type
+                    ):
+                        # Its type condition holds for every value selected here, so the fragment's type stands in, as a base class.
+                        fragment_names.append(fragment_name)
+                    else:
+                        # One on a narrower type is a branch, as an inline fragment is, and so is a skippable one, since standing in would declare its keys present.
+                        conditions.append(
+                            TypeCondition(
+                                type=fragment_type,
+                                selection_set=SelectionSet(
+                                    type=fragment_type,
+                                    fragment_names=(fragment_name,),
+                                    fields=(),
+                                    conditions=(),
+                                    description="",
+                                ),
+                                skippable=skippable,
+                            ),
+                        )
+                case _:  # pragma: no cover
+                    raise TypeError(f"Unexpected selection: {selection}")
+
+        type_info.leave(node)
+        return SelectionSet(
+            type=parent_type,
+            fields=tuple(fields),
+            conditions=tuple(conditions),
+            fragment_names=tuple(fragment_names),
+            description=parent_type.description or "",
+        )
+
+    def _resolve_field(
+        self, node: FieldNode, /, *, type_info: TypeInfo, skippable: bool
+    ) -> SelectedField:
+        type_info.enter(node)
+        parent_type = type_info.get_parent_type()
+        # `__typename` included: `TypeInfo` knows the meta fields.
+        field_definition = type_info.get_field_def()
+        assert parent_type is not None and field_definition is not None, (
+            "Validation guarantees that a selected field exists."
+        )
+        selection_set = (
+            None
+            if node.selection_set is None
+            else self._resolve_selection_set(node.selection_set, type_info=type_info)
+        )
+        type_info.leave(node)
+        return SelectedField(
+            name=node.name.value,
+            alias=node.alias.value if node.alias else None,
+            type=field_definition.type,
+            parent_type=parent_type,
+            directive_names=frozenset(
+                directive.name.value for directive in node.directives or ()
+            ),
+            description=field_definition.description or "",
+            selection_set=selection_set,
+            skippable=skippable,
+        )

graphql_codegen/_generator/_structs.py

@@ -0,0 +1,87 @@
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import final
+
+from graphql import (
+    GraphQLError,
+    GraphQLInputObjectType,
+    GraphQLInterfaceType,
+    GraphQLNamedType,
+    GraphQLScalarType,
+    GraphQLSchema,
+    get_named_type,
+    is_specified_scalar_type,
+)
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class StructTypes:
+    payload_field_name: str
+
+    input_type_names: Mapping[str, str]
+    """The name of the input type each struct type's payload is shaped like, by the struct type's name."""
+
+
+def parse_struct_types(
+    schema: GraphQLSchema, struct_interface_name: str, /
+) -> StructTypes:
+    """The interface has a single field, the payload, of a custom scalar type, since the payload is opaque on the wire.
+
+    Every object type implementing it is named after an input type followed by the interface's name: `BookFilterStruct` has the shape of `input BookFilter`, which lets one definition be both sent and received.
+    """
+    interface = schema.type_map.get(struct_interface_name)
+
+    if not isinstance(interface, GraphQLInterfaceType):
+        # A config value naming nothing in the schema, not a mistyped one.
+        raise ValueError(f"Found no interface named `{struct_interface_name}`.")  # noqa: TRY004
+
+    match list(interface.fields.items()):
+        case [(payload_field_name, payload_field)] if isinstance(
+            payload_type := get_named_type(payload_field.type), GraphQLScalarType
+        ) and not is_specified_scalar_type(payload_type):
+            pass
+        case _:
+            raise GraphQLError(
+                f"Expected `{struct_interface_name}` to have a single field, the payload, of a custom scalar type.",
+                nodes=interface.ast_node,
+            )
+
+    input_type_names: dict[str, str] = {}
+
+    for object_type in schema.get_possible_types(interface):
+        input_name = object_type.name.removesuffix(struct_interface_name)
+
+        if input_name == object_type.name or not isinstance(
+            schema.type_map.get(input_name), GraphQLInputObjectType
+        ):
+            raise GraphQLError(
+                f"Expected `{object_type.name}`, which implements `{struct_interface_name}`, to be named after an input type followed by `{struct_interface_name}`.",
+                nodes=object_type.ast_node,
+            )
+
+        input_type_names[object_type.name] = input_name
+
+    return StructTypes(
+        payload_field_name=payload_field_name, input_type_names=input_type_names
+    )
+
+
+def get_struct_input_name(
+    parent_type: GraphQLNamedType,
+    field_name: str,
+    /,
+    *,
+    struct_types: StructTypes | None,
+) -> str | None:
+    """The wire type of a struct's payload is an opaque scalar, so without this it would be :class:`object`.
+
+    The payload stays under its `value` key rather than replacing the struct, although a struct only ever has that one key.
+    Moving it up would make every response holding a struct pay for a conversion, even one whose payload otherwise needs none, and the data's type would stop mirroring the document, which selects `value`, all for little convenience.
+
+    Once the [Struct RFC](https://github.com/graphql/graphql-wg/blob/main/rfcs/Struct.md) lands, a struct field is selected without a selection set, so the wrapper disappears from the document itself.
+    """
+    if struct_types is None or field_name != struct_types.payload_field_name:
+        return None
+
+    return struct_types.input_type_names.get(parent_type.name)

graphql_codegen/_generator/_typed_dict.py

@@ -0,0 +1,154 @@
+import ast
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import final
+
+from graphql_codegen._generator._ast_nodes import (
+    class_definition,
+    constant,
+    documented,
+    name,
+    qualified,
+    subscript,
+)
+from graphql_codegen._generator._naming import COMPAT, TYPING
+from graphql_codegen._generator.spelling import Spelling, ast_str, is_bindable
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class Key:
+    name: str
+    annotation: ast.expr
+    required: bool
+    description: str
+
+
+def _functional(
+    type_spelling: Spelling, keys: Sequence[Key], /, *, closed: bool
+) -> ast.Assign:
+    """The string passed as the first argument must match the variable it is assigned to, or `ty` reports `mismatched-type-name`."""
+    return ast.Assign(
+        targets=[ast.Name(id=ast_str(type_spelling), ctx=ast.Store())],
+        value=ast.Call(
+            func=qualified(COMPAT, "TypedDict"),
+            args=[
+                # Spelled like the target, placeholder included, so both get the same name.
+                constant(ast_str(type_spelling)),
+                ast.Dict(
+                    keys=[constant(key.name) for key in keys],
+                    values=[_annotation(key, closed=closed) for key in keys],
+                ),
+            ],
+            keywords=[ast.keyword(arg="closed", value=ast.Constant(value=True))]
+            if closed
+            else [],
+        ),
+    )
+
+
+def _is_class_attribute_safe(key: str, /, *, bare_names: frozenset[str]) -> bool:
+    """A name Python cannot bind cannot be, a name starting with `__` would be mangled, and a public name the module references unqualified would be shadowed by the key in the class scope.
+
+    No name the generator adds can clash with a key, since :func:`~graphql_codegen._spelling.settle_module` settles none like any name the module holds.
+    """
+    return is_bindable(key) and not key.startswith("__") and key not in bare_names
+
+
+def _annotation(key: Key, /, *, closed: bool) -> ast.expr:
+    """The key's annotation, saying whether it must be present: explicitly in a closed TypedDict, where reading what a caller must send matters, and only when it may be absent in an open one."""
+    if closed:
+        return subscript(
+            qualified(TYPING, "Required" if key.required else "NotRequired"),
+            key.annotation,
+        )
+
+    return (
+        key.annotation
+        if key.required
+        else subscript(qualified(TYPING, "NotRequired"), key.annotation)
+    )
+
+
+def _declaration(key: Key, /, *, closed: bool) -> list[ast.stmt]:
+    return documented(
+        ast.AnnAssign(
+            target=ast.Name(id=key.name, ctx=ast.Store()),
+            annotation=_annotation(key, closed=closed),
+            simple=1,
+        ),
+        text=key.description,
+    )
+
+
+def emit_closed(
+    type_spelling: Spelling,
+    keys: Sequence[Key],
+    /,
+    *,
+    description: str,
+    bare_names: frozenset[str],
+) -> list[ast.stmt]:
+    """Emit a closed TypedDict, as an input or variables type is, in class syntax unless a key cannot be declared in a class body, and then in functional syntax altogether, since a closed TypedDict cannot be extended with keys by a subclass."""
+    if all(_is_class_attribute_safe(key.name, bare_names=bare_names) for key in keys):
+        return [
+            class_definition(
+                type_spelling,
+                bases=[qualified(COMPAT, "TypedDict")],
+                keywords={"closed": ast.Constant(value=True)},
+                body=[
+                    statement
+                    for key in keys
+                    for statement in _declaration(key, closed=True)
+                ],
+                docstring_text=description,
+            ),
+        ]
+
+    return documented(_functional(type_spelling, keys, closed=True), text=description)
+
+
+def emit_data(
+    type_spelling: Spelling,
+    keys: Sequence[Key],
+    /,
+    *,
+    bases: Sequence[ast.expr],
+    closed: bool,
+    functional_base_spelling: Spelling,
+    description: str,
+) -> list[ast.stmt]:
+    """Emit a data type in class syntax, inheriting the keys a class body cannot declare from a functional base, so that it can still inherit fragments too.
+
+    The functional base is open, since the class extends it.
+    """
+    # A data module references no public name unqualified.
+    safe = [
+        key
+        for key in keys
+        if _is_class_attribute_safe(key.name, bare_names=frozenset())
+    ]
+    unsafe = [key for key in keys if key not in safe]
+    statements: list[ast.stmt] = []
+    all_bases = list(bases)
+
+    if unsafe:
+        statements.append(
+            _functional(functional_base_spelling, unsafe, closed=False),
+        )
+        all_bases.insert(0, name(functional_base_spelling))
+
+    statements.append(
+        class_definition(
+            type_spelling,
+            bases=all_bases or [qualified(COMPAT, "TypedDict")],
+            body=[
+                statement
+                for key in safe
+                for statement in _declaration(key, closed=False)
+            ],
+            docstring_text=description,
+            keywords={"closed": ast.Constant(value=True)} if closed else {},
+        ),
+    )
+    return statements

graphql_codegen/_generator/dotted_name.py

@@ -0,0 +1,48 @@
+import builtins
+from dataclasses import dataclass
+from typing import final
+
+from graphql_codegen._generator.spelling import is_bindable
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class Builtin:
+    name: str
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class Import:
+    level: int
+    """Like :attr:`ast.ImportFrom.level`: 0 for an absolute path, and 2 or more for one relative to the directory the package is written to."""
+
+    module: str | None
+    name: str
+
+
+type Reference = Builtin | Import
+
+
+def parse_dotted_name(dotted_name: str, /) -> Reference:
+    """A bare name, such as :class:`int`, is a builtin.
+
+    A dotted name is absolute, or starts with `..` to be relative to the directory the package is written to: `..scalars.decode` is `scalars.decode` next to it.
+    A dotted name starting with one dot would name a module of the generated package, which is not the project's to write in.
+    """
+    level = len(dotted_name) - len(dotted_name.lstrip("."))
+    *modules, last = dotted_name[level:].split(".")
+
+    if (
+        level == 1
+        or not all(is_bindable(part) for part in (*modules, last))
+        or (level == 0 and not modules and not hasattr(builtins, last))
+    ):
+        raise ValueError(
+            f"Expected an absolute dotted name, such as `datetime.datetime`, a dotted name relative to the package's directory, such as `..scalars.decode`, or a builtin, such as `int`, but got `{dotted_name}`."
+        )
+
+    if level == 0 and not modules:
+        return Builtin(name=last)
+
+    return Import(level=level, module=".".join(modules) or None, name=last)