graphql-codegen 0.1.0__py3-none-any.whl

graphql_codegen/_generator/spelling.py

@@ -0,0 +1,168 @@
+import ast
+from collections.abc import Collection, Iterator, Mapping, Sequence
+from functools import cache
+from itertools import count
+from typing import Final, Self, assert_never, final
+
+_MARK: Final = "\x00"
+"""What starts a placeholder, and separates its creation counter from its preferred name: NUL, which no identifier holds and no text starts with, and which Python refuses in source, so that a placeholder left in a name fails to compile rather than go unnoticed."""
+
+_counter: Final = count()
+
+
+@cache
+def is_bindable(name: str, /) -> bool:
+    if not name.isidentifier():
+        return False
+
+    try:
+        # Asking Python itself instead of checking against a list of exceptions that could go stale.
+        compile(f"{name} = None", "<name>", "exec")
+    except SyntaxError:
+        return False
+
+    return True
+
+
+@final
+class PendingSpelling:
+    """Nothing prevents a schema or a document from using any name the generator could pick in advance, so none is safe.
+
+    An emitter therefore never writes a name it adds: it makes a pending spelling of the name it would prefer, and uses it wherever the name goes, its placeholder holding the place.
+    """
+
+    def __init__(self, preferred: str, /) -> None:
+        assert preferred.isidentifier(), f"Expected `{preferred}` to be an identifier."
+        # A class body would mangle a name starting with two underscores, unless it also ends with two, as `_GetData`'s nested `__GetData_x` would be when an operation is named `_Get`.
+        unmangled = (
+            f"_{preferred.lstrip('_')}"
+            if preferred.startswith("__") and not preferred.endswith("__")
+            else preferred
+        )
+        self._placeholder: Final = f"{_MARK}{next(_counter)}{_MARK}{unmangled}"
+
+
+@final
+class SettledSpelling(str):
+    __slots__ = ()
+
+    def __new__(cls, value: str, /) -> Self:
+        assert is_bindable(value), f"Expected Python to be able to bind `{value}`."
+        return super().__new__(cls, value)
+
+
+type Spelling = PendingSpelling | SettledSpelling
+"""How generated code writes a name.
+
+- :class:`PendingSpelling`: added by the generator, so decided by :func:`settle_module` once its module is complete.
+- :class:`SettledSpelling`: known up front, such as a public one, so decided at once by :func:`settle_names`.
+"""
+
+
+def ast_str(spelling: Spelling, /) -> str:
+    match spelling:
+        case SettledSpelling():
+            return spelling
+        case PendingSpelling():
+            return spelling._placeholder
+        case _ as never:
+            assert_never(never)
+
+
+def _is_placeholder(value: str, /) -> bool:
+    return value.startswith(_MARK)
+
+
+def _preferred(placeholder: str, /) -> str:
+    return placeholder.rsplit(_MARK, 1)[1]
+
+
+def _strings(node: ast.AST, /) -> Iterator[str]:
+    for _, value in ast.iter_fields(node):
+        values = value if isinstance(value, list) else [value]
+
+        for item in values:
+            if isinstance(item, str):
+                yield item
+            elif isinstance(item, ast.AST):
+                if isinstance(item, ast.Constant) and isinstance(item.value, str):
+                    yield item.value
+                else:
+                    yield from _strings(item)
+
+
+def _identifiers(module: ast.Module, /) -> Iterator[str]:
+    for child in ast.walk(module):
+        match child:
+            case ast.Name(id=bound):
+                pass
+            case ast.alias(name=imported, asname=alias):
+                bound = alias or imported.split(".")[0]
+            case ast.ClassDef(name=bound) | ast.FunctionDef(name=bound):
+                pass
+            case _:
+                continue
+
+        if not _is_placeholder(bound):
+            yield bound
+
+
+def _rewrite(module: ast.Module, spellings: Mapping[str, SettledSpelling], /) -> None:
+    # Lists of identifiers, as `global`, `nonlocal`, and keyword class patterns hold, are left: generated code writes none.
+    for node in ast.walk(module):
+        for field, value in ast.iter_fields(node):
+            if isinstance(value, str) and value in spellings:
+                setattr(node, field, spellings[value])
+
+
+def settle_module(module: ast.Module, /) -> None:
+    """The other names are fixed, since they come from GraphQL, so a clash is impossible rather than detected.
+
+    Collecting them widely, every name loaded, stored, or imported anywhere in the module, class body keys included, is what makes that hold without reasoning about scopes.
+    """
+    fixed = set(_identifiers(module))
+    # In creation order, which the counter after the first mark records.
+    placeholders = sorted(
+        {value for value in _strings(module) if _is_placeholder(value)},
+        key=lambda placeholder: int(placeholder.split(_MARK)[1]),
+    )
+    spellings: dict[str, SettledSpelling] = {}
+
+    for placeholder in placeholders:
+        spelling = next(
+            candidate
+            for candidate in candidates(_preferred(placeholder))
+            if candidate not in fixed
+        )
+        fixed.add(spelling)
+        spellings[placeholder] = spelling
+
+    _rewrite(module, spellings)
+
+
+def candidates(name: str, /) -> Iterator[SettledSpelling]:
+    yield SettledSpelling(name if is_bindable(name) else f"{name}_")
+    yield from (SettledSpelling(f"{name}_{suffix}") for suffix in count(1))
+
+
+def settle_names(
+    identifiers: Sequence[str], /, *, taken: Collection[SettledSpelling]
+) -> dict[str, SettledSpelling]:
+    assert all(identifier.isidentifier() for identifier in identifiers), (
+        f"Expected only identifiers, but got {identifiers}."
+    )
+    used = set(taken)
+    spellings: dict[str, SettledSpelling] = {}
+
+    for name in sorted(
+        identifiers,
+        # Names that can be bound as they are come first, so a renamed one never takes the name of a definition spelled that way.
+        key=lambda name: not is_bindable(name),
+    ):
+        spelling = next(
+            candidate for candidate in candidates(name) if candidate not in used
+        )
+        used.add(spelling)
+        spellings[name] = spelling
+
+    return {name: spellings[name] for name in identifiers}

graphql_codegen/_metadata.py

@@ -0,0 +1,11 @@
+from importlib.metadata import metadata
+from typing import Final
+
+METADATA: Final = metadata(__name__.partition(".")[0])
+"""This library's metadata, which `pyproject.toml` declares."""
+
+DISTRIBUTION_NAME: Final = METADATA["Name"]
+"""This library's name, which only `pyproject.toml` spells."""
+
+# Inspired by https://github.com/github-linguist/linguist/blob/5fbdfcb8133be2bed88bf3ce62b2335f50474525/lib/linguist/generated.rb#L345.
+GENERATED_FILE_COMMENT_PREFIX: Final = f"# Code generated by {DISTRIBUTION_NAME}"

graphql_codegen/_note.py

@@ -0,0 +1,12 @@
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+
+@contextmanager
+def error_note(note: str, /) -> Iterator[None]:
+    """Add *note* to an error raised inside, so that a function need not know where its caller found what it checks."""
+    try:
+        yield
+    except Exception as error:
+        error.add_note(note)
+        raise

graphql_codegen/config.py

@@ -0,0 +1,42 @@
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass, field
+from typing import final
+
+from graphql import GraphQLError, assert_name
+
+from graphql_codegen.document_sibling_module import DocumentSiblingModule
+from graphql_codegen.scalar import Scalar
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class Config:
+    document_sibling_module: DocumentSiblingModule | None = None
+    """When ``None``, each document's module is named after the document, in the generated package's `document` subpackage, which re-exports every operation and fragment."""
+
+    injector_names: Collection[str] = frozenset()
+    """The names of the variables and input fields an injector supplies, left out of the generated types and injected wherever an operation holds them.
+
+    Every variable and input field of a same name must have the same type, nullability aside.
+    """
+
+    non_null_directive_name: str | None = None
+    """The name of the client directive asserting that a nullable field is not null for this operation, stripped before a document goes on the wire."""
+
+    scalars: Mapping[str, Scalar] = field(default_factory=dict)
+    """The Python type of each scalar by GraphQL name."""
+
+    struct_interface_name: str | None = None
+    """The name of the interface every struct implements: an object type whose single field, of a custom scalar type, carries a JSON payload.
+
+    The payload is shaped like the input type named as the struct without the interface's name, such as ``"BookFilter"`` for ``f"BookFilter{struct_interface_name}"``.
+    """
+
+    def __post_init__(self) -> None:
+        if self.non_null_directive_name is not None:
+            try:
+                assert_name(self.non_null_directive_name)
+            except GraphQLError as error:
+                raise ValueError(
+                    f"Cannot name the client directive `{self.non_null_directive_name}`: {error.message}"
+                ) from error

graphql_codegen/document_sibling_module.py

@@ -0,0 +1,58 @@
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import PurePosixPath
+from typing import final
+
+from graphql_codegen.package_location import PackageLocation
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class DocumentSiblingModule:
+    """The module holding a document's operations and fragments, in the document's directory.
+
+    The schema types they reference deliberately stay in the generated package, so that their import paths never depend on which documents use them.
+    A fragment spread from another document is imported from its own document's module.
+    """
+
+    name: str
+    """Its name, such as ``_{document}_gql``, in which ``{document}`` is the document's file stem, the whole then settled as a module name."""
+
+    package_location: PackageLocation
+    """Where the package lives, which the module imports it from."""
+
+    def __post_init__(self) -> None:
+        # Parsed eagerly, so that no sibling module holds a name it cannot use.
+        _ = self._affixes
+
+    @cached_property
+    def _affixes(self) -> tuple[str, str]:
+        """What the name puts ``(before, after)`` ``{document}``."""
+        before, placeholder, after = self.name.partition("{document}")
+
+        if (
+            not placeholder
+            or "{document}" in after
+            or not f"{before}x{after}".isidentifier()
+        ):
+            raise ValueError(
+                f"Expected the module's name to be an identifier holding `{{document}}` once, such as `_{{document}}_gql`, but got `{self.name}`."
+            )
+
+        return before, after
+
+    def _module_name(self, document: PurePosixPath, /) -> str:
+        """The name of *document*'s module, before it is settled as a module name.
+
+        An underscore the name puts next to ``{document}`` merges with the stem's own.
+        """
+        before, after = self._affixes
+        stem = document.stem
+
+        # `_{document}_gql` with the stem `_cube_` makes `_cube_gql`, not `__cube__gql`.
+        if before.endswith("_"):
+            stem = stem.lstrip("_")
+        if after.startswith("_"):
+            stem = stem.rstrip("_")
+
+        return f"{before}{stem}{after}"

graphql_codegen/generate.py

@@ -0,0 +1,19 @@
+from pathlib import PurePosixPath
+from typing import Unpack
+
+from graphql import DocumentNode, GraphQLSchema
+
+from graphql_codegen._generator.package import PackageEmitter
+from graphql_codegen.config import Config
+from graphql_codegen.runtime._compat import TypedDict
+
+
+class _Params(TypedDict, closed=True):
+    document: DocumentNode
+    schema: GraphQLSchema
+    config: Config
+
+
+def generate(**args: Unpack[_Params]) -> dict[PurePosixPath, bytes]:
+    """Pure function returning the content of each file of the generated package by its path."""
+    return PackageEmitter(**args).emit()

graphql_codegen/package_location.py

@@ -0,0 +1,41 @@
+import posixpath
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import PurePosixPath
+from typing import final
+
+from graphql_codegen._generator.spelling import is_bindable
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class PackageLocation:
+    """Where the generated package lives."""
+
+    module_root: PurePosixPath
+    """Where the package's top-level package starts."""
+
+    package: str
+    """The package's dotted name, which a module outside it imports it by."""
+
+    def __post_init__(self) -> None:
+        # Parsed eagerly, so that no location holds a package it cannot use.
+        _ = self._parts
+
+    @cached_property
+    def _parts(self) -> tuple[str, ...]:
+        """The names the package's dotted name holds."""
+        parts = tuple(self.package.split("."))
+
+        if not all(is_bindable(part) for part in parts):
+            raise ValueError(
+                f"Expected the package to be a dotted name, such as `my_app._graphql`, but got `{self.package}`."
+            )
+
+        return parts
+
+    @property
+    def _package_directory(self) -> PurePosixPath:
+        return PurePosixPath(
+            posixpath.normpath(self.module_root.joinpath(*self._parts))
+        )

graphql_codegen/runtime/__init__.py

@@ -0,0 +1,20 @@
+# Copied into each generated package, where this line says not to edit it.
+
+from .client import (
+    AsyncClient as AsyncClient,
+    AsyncSubscriptionClient as AsyncSubscriptionClient,
+    Client as Client,
+    SubscriptionClient as SubscriptionClient,
+)
+from .error import (
+    ClientError as ClientError,
+    Error as Error,
+    ExecutionError as ExecutionError,
+    Location as Location,
+    ProtocolError as ProtocolError,
+    RequestError as RequestError,
+    ResponseError as ResponseError,
+    UnexpectedNullError as UnexpectedNullError,
+)
+from .injection import OMITTED as OMITTED
+from .operation import Operation as Operation, Request as Request

graphql_codegen/runtime/_compat.py

@@ -0,0 +1,27 @@
+# Copied into each generated package, where this line says not to edit it.
+
+import sys
+
+# Closed TypedDicts (PEP 728) and sentinels (PEP 661) are the last to reach the standard library.
+if sys.version_info >= (3, 15):
+    from typing import (
+        ReadOnly as ReadOnly,
+        TypedDict as TypedDict,
+        TypeVar as TypeVar,
+        get_type_hints as get_type_hints,
+        is_typeddict as is_typeddict,
+    )
+
+    # The class of what the builtin `sentinel()` returns.
+    SentinelType = sentinel  # noqa: F821
+else:
+    from typing_extensions import (
+        ReadOnly as ReadOnly,
+        Sentinel,
+        TypedDict as TypedDict,
+        TypeVar as TypeVar,
+        get_type_hints as get_type_hints,
+        is_typeddict as is_typeddict,
+    )
+
+    SentinelType = Sentinel

graphql_codegen/runtime/_literal.py

@@ -0,0 +1,18 @@
+# Copied into each generated package, where this line says not to edit it.
+
+from typing import Literal
+
+type OperationType = Literal["query", "mutation", "subscription"]
+"""The spec's `OperationType`.
+
+- ``"query"`` reads, and a client may run several at once.
+- ``"mutation"`` writes, and the server runs the root fields of several in order.
+- ``"subscription"`` answers with a stream of responses rather than one, which only a subscription client runs.
+"""
+
+type ExecutionErrorHandling = Literal["raise", "return"]
+"""What a client does with the :class:`~.error.ExecutionError` of the response to a request.
+
+- ``"raise"`` raises it, so that what a call returns is always complete data.
+- ``"return"`` returns it in place of the request's data, typed by the request, for a caller who can use partial data.
+"""

graphql_codegen/runtime/_merge.py

@@ -0,0 +1,153 @@
+# Copied into each generated package, where this line says not to edit it.
+
+from collections.abc import Mapping, Sequence
+from functools import cache
+from json import dumps
+from typing import Any, Final
+
+from ._literal import OperationType
+from ._sigil import SIGIL
+from .error import Error
+from .operation import Operation
+
+MERGED_OPERATION_NAME: Final = "MergedOperation"
+
+_INDEX_SEPARATOR: Final = "_"
+
+
+@cache
+def _template_parts(document: str, /) -> tuple[str, str, Mapping[str, str]]:
+    """The generator prints a template like any document: the operation first, its header on one line, then its root fields, then each fragment after a blank line.
+
+    Cached: the documents of a generated package are few and fixed.
+    """
+    operation, *fragment_definitions = document.split("\n\n")
+    header, *root_selections, _ = operation.split("\n")
+    # An operation holding the sigil has no directives, so its header ends with its variable definitions, if any.
+    variable_definitions = (
+        header[header.index("(") + 1 : header.rindex(")")] if "(" in header else ""
+    )
+    fragments = {
+        definition.split(" ", 2)[1]: definition for definition in fragment_definitions
+    }
+    return variable_definitions, "\n".join(root_selections), fragments
+
+
+def encode_body(
+    parts: Sequence[tuple[Operation[OperationType, Any, object], Mapping[str, object]]],
+    /,
+) -> bytes:
+    """Merging lets a server see several operations at once, such as mutations it can apply in one step, and saves round trips.
+
+    Each operation's variables and root fields are suffixed with its index in the merge, so that the operations cannot collide.
+    The generator writes a sigil wherever the index goes, so suffixing is plain string replacement.
+
+    A lone operation is sent as is, so that the server knows it by its own name.
+    """
+    if not parts:
+        raise ValueError("Cannot merge no operation.")
+
+    if len(parts) == 1:
+        ((operation, operation_variables),) = parts
+        return operation._request_body(operation_variables)
+
+    operation_types = {operation._operation_type for operation, _ in parts}
+
+    if len(operation_types) != 1:
+        raise ValueError(
+            f"Cannot merge operations of different types: {', '.join(sorted(operation_types))}.",
+        )
+
+    (operation_type,) = operation_types
+    variable_definitions: list[str] = []
+    selections: list[str] = []
+    fragments: dict[str, str] = {}
+    variables: dict[str, object] = {}
+
+    for index, (operation, operation_variables) in enumerate(parts):
+        if SIGIL not in operation._document:
+            raise ValueError(
+                f"Cannot merge `{operation._name}`: its document has no `{SIGIL}` where its index would go."
+            )
+
+        definitions, root_selections, operation_fragments = _template_parts(
+            operation._document
+        )
+        suffix = f"{_INDEX_SEPARATOR}{index}"
+
+        if definitions:
+            variable_definitions.append(definitions.replace(SIGIL, suffix))
+
+        selections.append(root_selections.replace(SIGIL, suffix))
+        fragments.update(operation_fragments)
+        variables.update(
+            {f"{name}{suffix}": value for name, value in operation_variables.items()}
+        )
+
+    signature = f"({', '.join(variable_definitions)})" if variable_definitions else ""
+    document = "\n\n".join(
+        [
+            "\n".join(
+                [
+                    f"{operation_type} {MERGED_OPERATION_NAME}{signature} {{",
+                    *selections,
+                    "}",
+                ]
+            ),
+            *fragments.values(),
+        ],
+    )
+    return dumps(
+        {
+            "operationName": MERGED_OPERATION_NAME,
+            "query": document,
+            "variables": variables,
+        },
+    ).encode()
+
+
+def _split_response_name(key: str, /) -> tuple[str, int]:
+    response_name, index = key.rsplit(_INDEX_SEPARATOR, 1)
+    return response_name, int(index)
+
+
+def split_merged_data(
+    data: Mapping[str, object], /, *, count: int
+) -> Sequence[Mapping[str, object]]:
+    """Preallocated, so that an operation whose every root field `@skip` left out still gets its own, empty, data rather than shifting the others'."""
+    if count == 1:
+        return [data]
+
+    split: list[dict[str, object]] = [{} for _ in range(count)]
+
+    for key, value in data.items():
+        response_name, index = _split_response_name(key)
+        split[index][response_name] = value
+
+    return split
+
+
+def split_merged_errors(
+    errors: Sequence[Error], /, *, count: int
+) -> Sequence[Sequence[Error]]:
+    """An error's path starts with the suffixed response name of the root field it concerns, which tells its operation.
+
+    An error without a path concerns them all.
+    """
+    if count == 1:
+        return [errors]
+
+    split: list[list[Error]] = [[] for _ in range(count)]
+
+    for error in errors:
+        path = error.get("path")
+
+        if not path or not isinstance(path[0], str):
+            for operation_errors in split:
+                operation_errors.append(error)
+            continue
+
+        response_name, index = _split_response_name(path[0])
+        split[index].append({**error, "path": [response_name, *path[1:]]})
+
+    return split