graphql-codegen 0.1.0__py3-none-any.whl

graphql_codegen/runtime/client.py

@@ -0,0 +1,384 @@
+# Copied into each generated package, where this line says not to edit it.
+
+from collections.abc import AsyncGenerator, Callable, Generator, Sequence
+from contextlib import aclosing, closing
+from typing import Any, Final, Generic, Literal, final, overload
+
+from ._compat import TypeVar
+from ._prepare import prepare, prepare_requests
+from ._transport import (
+    AsyncSubscriptionTransport,
+    AsyncTransport,
+    SubscriptionTransport,
+    Transport,
+)
+from .injection import _Injectors
+from .operation import Request
+
+# A client's transport, whose signature types the arguments each call accepts: none, unless it says otherwise.
+# Covariant, so that a client over a transport is a client over any `Protocol` the transport satisfies.
+# Legacy `TypeVar`s, since a default for a PEP 695 type parameter needs Python 3.13.
+_Transport_co = TypeVar(
+    "_Transport_co", bound=Transport[...], covariant=True, default=Transport[[]]
+)
+_AsyncTransport_co = TypeVar(
+    "_AsyncTransport_co",
+    bound=AsyncTransport[...],
+    covariant=True,
+    default=AsyncTransport[[]],
+)
+_SubscriptionTransport_co = TypeVar(
+    "_SubscriptionTransport_co",
+    bound=SubscriptionTransport[...],
+    covariant=True,
+    default=SubscriptionTransport[[]],
+)
+_AsyncSubscriptionTransport_co = TypeVar(
+    "_AsyncSubscriptionTransport_co",
+    bound=AsyncSubscriptionTransport[...],
+    covariant=True,
+    default=AsyncSubscriptionTransport[[]],
+)
+
+
+def _response_stream[Data](
+    bodies: Generator[bytes, None, None], parse: Callable[[bytes], Data], /
+) -> Generator[Data, None, None]:
+    # Closing the response stream, or an error in one of its responses, closes the transport's.
+    with closing(bodies):
+        for body in bodies:
+            yield parse(body)
+
+
+async def _async_response_stream[Data](
+    bodies: AsyncGenerator[bytes, None], parse: Callable[[bytes], Data], /
+) -> AsyncGenerator[Data, None]:
+    async with aclosing(bodies):
+        async for body in bodies:
+            yield parse(body)
+
+
+@final
+class Client(Generic[_Transport_co]):
+    """Run query and mutation requests over *transport*, each call accepting the transport's parameters.
+
+    Several operations of one type run merged, in one call to the transport: a tuple of up to 6 returns a tuple typed position by position, and any other sequence a tuple of their common data type.
+    A response with errors raises a :class:`ResponseError`, and a merge an :exc:`ExceptionGroup` of a :class:`ExecutionError` per operation its errors concern, or the unsplit error when its data is null.
+    A request from :meth:`~Request.returning_error` gets its :class:`ExecutionError` back in place of its data instead, unless the call raises for another.
+
+    The transport's parameters are read off its signature and checked, so that the library never has to know what they are::
+
+        def transport(body: bytes, /, *, timeout: float | None = None) -> bytes: ...
+
+        client = Client(transport)
+        client(ListBooks({"first": 10}), timeout=5.0)
+
+    Code taking a client names its type after the transport's signature, written once as a :class:`typing.Protocol`, which the transport a client is built from is checked against::
+
+        class Transport(Protocol):
+            def __call__(self, body: bytes, /, *, timeout: float | None = None) -> bytes: ...
+
+        Client = runtime.Client[Transport]
+
+        def describe(isbn: ISBN, /, *, client: Client) -> str: ...
+
+        describe(isbn, client=Client(transport))
+
+    A plain alias rather than a `type` statement, since only the former can be called to build a client.
+    A client is generic over its transport rather than over its parameters, because a :class:`typing.ParamSpec`'s value cannot be spelled with keyword parameters, and PEP 692 only unpacks a concrete :class:`typing.TypedDict`, never a type parameter.
+    """
+
+    def __init__(
+        self,
+        transport: _Transport_co,
+        /,
+        *,
+        injectors: _Injectors | None = None,
+    ) -> None:
+        self.transport: Final = transport
+        self.injectors: Final = injectors
+
+    @overload
+    def __call__[**Params, Type: Literal["query", "mutation"], Data](
+        self: "Client[Transport[Params]]",
+        request: Request[Type, Data],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> Data: ...
+    @overload
+    def __call__[**Params, Type: (Literal["query"], Literal["mutation"]), D1, D2](
+        self: "Client[Transport[Params]]",
+        requests: tuple[Request[Type, D1], Request[Type, D2]],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2]: ...
+    @overload
+    def __call__[**Params, Type: (Literal["query"], Literal["mutation"]), D1, D2, D3](
+        self: "Client[Transport[Params]]",
+        requests: tuple[Request[Type, D1], Request[Type, D2], Request[Type, D3]],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2, D3]: ...
+    @overload
+    def __call__[
+        **Params,
+        Type: (Literal["query"], Literal["mutation"]),
+        D1,
+        D2,
+        D3,
+        D4,
+    ](
+        self: "Client[Transport[Params]]",
+        requests: tuple[
+            Request[Type, D1], Request[Type, D2], Request[Type, D3], Request[Type, D4]
+        ],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2, D3, D4]: ...
+    @overload
+    def __call__[
+        **Params,
+        Type: (Literal["query"], Literal["mutation"]),
+        D1,
+        D2,
+        D3,
+        D4,
+        D5,
+    ](
+        self: "Client[Transport[Params]]",
+        requests: tuple[
+            Request[Type, D1],
+            Request[Type, D2],
+            Request[Type, D3],
+            Request[Type, D4],
+            Request[Type, D5],
+        ],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2, D3, D4, D5]: ...
+    @overload
+    def __call__[
+        **Params,
+        Type: (Literal["query"], Literal["mutation"]),
+        D1,
+        D2,
+        D3,
+        D4,
+        D5,
+        D6,
+    ](
+        self: "Client[Transport[Params]]",
+        requests: tuple[
+            Request[Type, D1],
+            Request[Type, D2],
+            Request[Type, D3],
+            Request[Type, D4],
+            Request[Type, D5],
+            Request[Type, D6],
+        ],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2, D3, D4, D5, D6]: ...
+    @overload
+    def __call__[**Params, Type: (Literal["query"], Literal["mutation"]), Data](
+        self: "Client[Transport[Params]]",
+        requests: Sequence[Request[Type, Data]],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[Data, ...]: ...
+    def __call__(self, requests: Any, /, *args: Any, **kwargs: Any) -> Any:
+        prepared = prepare_requests(requests, injectors=self.injectors)
+        return (
+            ()
+            if prepared is None
+            else prepared.parse(self.transport(bytes(prepared), *args, **kwargs))
+        )
+
+
+@final
+class AsyncClient(Generic[_AsyncTransport_co]):
+    def __init__(
+        self,
+        transport: _AsyncTransport_co,
+        /,
+        *,
+        injectors: _Injectors | None = None,
+    ) -> None:
+        self.transport: Final = transport
+        self.injectors: Final = injectors
+
+    @overload
+    async def __call__[**Params, Type: Literal["query", "mutation"], Data](
+        self: "AsyncClient[AsyncTransport[Params]]",
+        request: Request[Type, Data],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> Data: ...
+    @overload
+    async def __call__[
+        **Params,
+        Type: (Literal["query"], Literal["mutation"]),
+        D1,
+        D2,
+    ](
+        self: "AsyncClient[AsyncTransport[Params]]",
+        requests: tuple[Request[Type, D1], Request[Type, D2]],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2]: ...
+    @overload
+    async def __call__[
+        **Params,
+        Type: (Literal["query"], Literal["mutation"]),
+        D1,
+        D2,
+        D3,
+    ](
+        self: "AsyncClient[AsyncTransport[Params]]",
+        requests: tuple[Request[Type, D1], Request[Type, D2], Request[Type, D3]],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2, D3]: ...
+    @overload
+    async def __call__[
+        **Params,
+        Type: (Literal["query"], Literal["mutation"]),
+        D1,
+        D2,
+        D3,
+        D4,
+    ](
+        self: "AsyncClient[AsyncTransport[Params]]",
+        requests: tuple[
+            Request[Type, D1], Request[Type, D2], Request[Type, D3], Request[Type, D4]
+        ],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2, D3, D4]: ...
+    @overload
+    async def __call__[
+        **Params,
+        Type: (Literal["query"], Literal["mutation"]),
+        D1,
+        D2,
+        D3,
+        D4,
+        D5,
+    ](
+        self: "AsyncClient[AsyncTransport[Params]]",
+        requests: tuple[
+            Request[Type, D1],
+            Request[Type, D2],
+            Request[Type, D3],
+            Request[Type, D4],
+            Request[Type, D5],
+        ],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2, D3, D4, D5]: ...
+    @overload
+    async def __call__[
+        **Params,
+        Type: (Literal["query"], Literal["mutation"]),
+        D1,
+        D2,
+        D3,
+        D4,
+        D5,
+        D6,
+    ](
+        self: "AsyncClient[AsyncTransport[Params]]",
+        requests: tuple[
+            Request[Type, D1],
+            Request[Type, D2],
+            Request[Type, D3],
+            Request[Type, D4],
+            Request[Type, D5],
+            Request[Type, D6],
+        ],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[D1, D2, D3, D4, D5, D6]: ...
+    @overload
+    async def __call__[**Params, Type: (Literal["query"], Literal["mutation"]), Data](
+        self: "AsyncClient[AsyncTransport[Params]]",
+        requests: Sequence[Request[Type, Data]],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> tuple[Data, ...]: ...
+    async def __call__(self, requests: Any, /, *args: Any, **kwargs: Any) -> Any:
+        prepared = prepare_requests(requests, injectors=self.injectors)
+        return (
+            ()
+            if prepared is None
+            else prepared.parse(await self.transport(bytes(prepared), *args, **kwargs))
+        )
+
+
+@final
+class SubscriptionClient(Generic[_SubscriptionTransport_co]):
+    """Run subscription requests over *transport*, returning their response stream, which closing unsubscribes.
+
+    A response with errors raises out of the stream.
+    """
+
+    def __init__(
+        self,
+        transport: _SubscriptionTransport_co,
+        /,
+        *,
+        injectors: _Injectors | None = None,
+    ) -> None:
+        self.transport: Final = transport
+        self.injectors: Final = injectors
+
+    def __call__[**Params, Data](
+        self: "SubscriptionClient[SubscriptionTransport[Params]]",
+        request: Request[Literal["subscription"], Data],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> Generator[Data, None, None]:
+        prepared = prepare(request, injectors=self.injectors)
+        return _response_stream(
+            self.transport(bytes(prepared), *args, **kwargs), prepared.parse
+        )
+
+
+@final
+class AsyncSubscriptionClient(Generic[_AsyncSubscriptionTransport_co]):
+    def __init__(
+        self,
+        transport: _AsyncSubscriptionTransport_co,
+        /,
+        *,
+        injectors: _Injectors | None = None,
+    ) -> None:
+        self.transport: Final = transport
+        self.injectors: Final = injectors
+
+    def __call__[**Params, Data](
+        self: "AsyncSubscriptionClient[AsyncSubscriptionTransport[Params]]",
+        request: Request[Literal["subscription"], Data],
+        /,
+        *args: Params.args,
+        **kwargs: Params.kwargs,
+    ) -> AsyncGenerator[Data, None]:
+        prepared = prepare(request, injectors=self.injectors)
+        return _async_response_stream(
+            self.transport(bytes(prepared), *args, **kwargs), prepared.parse
+        )

graphql_codegen/runtime/error.py

@@ -0,0 +1,135 @@
+# Copied into each generated package, where this line says not to edit it.
+
+from collections.abc import Callable, Mapping, Sequence
+from copy import deepcopy
+from typing import Final, Generic, NotRequired, Required, cast, final, override
+
+from ._compat import TypedDict, TypeVar
+
+
+class Location(TypedDict):
+    line: Required[int]
+    column: Required[int]
+
+
+class Error(TypedDict):
+    """An error as a server sends it, in the spec's shape, which graphql-core's :class:`~graphql.GraphQLFormattedError` follows too.
+
+    Not graphql-core's :class:`~graphql.GraphQLError`, because four of its eight attributes (:attr:`~graphql.GraphQLError.nodes`, :attr:`~graphql.GraphQLError.source`, :attr:`~graphql.GraphQLError.positions`, and :attr:`~graphql.GraphQLError.original_error`) are server-side execution state a client cannot fill, and importing it would put graphql-core in the runtime for nothing.
+    """
+
+    message: Required[str]
+    locations: NotRequired[Sequence[Location]]
+    path: NotRequired[Sequence[str | int]]
+    extensions: NotRequired[object]
+
+
+class ClientError(Exception):
+    """Base of every error a generated client raises.
+
+    A transport's own errors, such as a timeout or an HTTP status, pass through as they are: the client does not know what carries its requests.
+    Not :func:`typing.final`: it exists so a caller can catch anything this library raises with one `except`.
+    """
+
+
+class ResponseError(ClientError):
+    """The response carried errors, in either of the two shapes the spec gives such a response.
+
+    A response carrying any error raises, so that the data a client returns never holds a `null` standing for an error.
+    Not :func:`typing.final`: it exists so a caller can catch both shapes with one `except`.
+    """
+
+    def __init__(
+        self, errors: Sequence[Error], /, *, extensions: Mapping[str, object] | None
+    ) -> None:
+        assert errors, "Cannot raise without at least one error."
+        self.errors: Final = tuple(errors)
+        self.extensions: Final = extensions
+        super().__init__("; ".join(error["message"] for error in self.errors))
+
+
+@final
+class RequestError(ResponseError):
+    """The response is the spec's request error result: the request failed before execution, so it has no data.
+
+    A syntax error, a validation failure, or an invalid variable value, for instance.
+    """
+
+
+# The type of an execution error's parsed data: the operation's data type when a client returns the error, typed by its request, and a plain mapping when `except` catches it, since that names no operation.
+# A legacy `TypeVar`, since a default for a PEP 695 type parameter needs Python 3.13.
+_Data_co = TypeVar("_Data_co", covariant=True, default=Mapping[str, object])
+
+
+@final
+class ExecutionError(ResponseError, Generic[_Data_co]):
+    """The server raised errors executing the request, but sent the rest of the data.
+
+    A field that raised is `null`, as is its nearest nullable parent if it is non-null.
+    """
+
+    data: Final[Mapping[str, object] | None]
+
+    def parse_data(self) -> _Data_co | None:
+        """Return the data converted as in a response without errors, in a fresh copy.
+
+        A `@nonNull` field that raised moves its `null` up to its nearest nullable parent, as the server does for a non-null field.
+        A custom scalar's codec may raise on a value it cannot decode.
+        """
+        if self.data is None:
+            return None
+
+        data = deepcopy(self.data)
+
+        if self._partial_data_parser is not None:
+            try:
+                self._partial_data_parser(data)
+            except UnexpectedNullError:
+                return None
+
+        # Nothing is validated: the data is trusted to match its type, as in a response without errors.
+        return cast(_Data_co, data)
+
+    def __init__(
+        self,
+        errors: Sequence[Error],
+        /,
+        *,
+        data: Mapping[str, object] | None,
+        extensions: Mapping[str, object] | None,
+        partial_data_parser: Callable[[object], object] | None,
+    ) -> None:
+        super().__init__(errors, extensions=extensions)
+        self.data = data
+        self._partial_data_parser: Final = partial_data_parser
+
+
+@final
+class ProtocolError(ClientError):
+    """The response was not a GraphQL response.
+
+    Usually an HTML error page from a proxy.
+    Without this the caller would get a bare :exc:`json.JSONDecodeError` from somewhere inside the client.
+    """
+
+
+@final
+class UnexpectedNullError(ClientError):
+    """A field marked `@nonNull` was null.
+
+    The schema declares the field nullable, so only the client can assert otherwise.
+
+    The path names the exact value, list indices included: it is completed on the way up by each enclosing object and list, which costs nothing unless the error is raised.
+    """
+
+    def __init__(self, path: list[str | int], /) -> None:
+        self.path: Final = path
+        super().__init__()
+
+    @override
+    def __str__(self) -> str:
+        formatted = "".join(
+            f"[{segment}]" if isinstance(segment, int) else f".{segment}"
+            for segment in self.path
+        ).removeprefix(".")
+        return f"Expected `{formatted}` to not be null."

graphql_codegen/runtime/injection.py

@@ -0,0 +1,107 @@
+# Copied into each generated package, where this line says not to edit it.
+
+import sys
+from collections.abc import Callable, Mapping
+from typing import Final, cast, final
+
+from ._reflection import Convert, build_injector_serializers
+
+if sys.version_info >= (3, 15):
+    OMITTED = sentinel("OMITTED")  # noqa: F821
+else:
+    from typing_extensions import Sentinel
+
+    OMITTED = Sentinel("OMITTED")
+"""What an injector returns to leave its value out rather than send ``null``.
+
+The spec tells the two apart: a nullable input accepts both, a non-null one neither, and a server may treat them differently.
+"""
+
+
+type _Injector = Callable[[], object | OMITTED]
+
+
+@final
+class _Injectors:
+    """Built by the ``injectors()`` function of a generated package's ``injection`` module, from a mapping the package's types check.
+
+    Not a mapping itself, so that a client cannot be given injectors that skipped that check: only a client calls it.
+    """
+
+    def __init__(
+        self, functions: Mapping[str, object], /, *, injector_functions_type: object
+    ) -> None:
+        self._functions: Final = {
+            name: cast(_Injector, function) for name, function in functions.items()
+        }
+        self._serializers: Final = build_injector_serializers(injector_functions_type)
+
+    def _inject(
+        self,
+        variables: Mapping[str, object],
+        /,
+        *,
+        injections: Mapping[str, frozenset[tuple[str, ...]]],
+    ) -> Mapping[str, object]:
+        """Calling the injectors is the one impure step, each once, so that every path of a request receives the same value."""
+        values = {
+            name: function()
+            for name, function in self._functions.items()
+            if name in injections
+        }
+        return _inject_values(
+            variables, values, serializers=self._serializers, injections=injections
+        )
+
+
+def _inject_values(
+    variables: Mapping[str, object],
+    values: Mapping[str, object],
+    /,
+    *,
+    serializers: Mapping[str, Convert | None],
+    injections: Mapping[str, frozenset[tuple[str, ...]]],
+) -> Mapping[str, object]:
+    for name, value in values.items():
+        if value is OMITTED:
+            continue
+
+        serialize = serializers[name]
+        serialized = value if serialize is None else serialize(value)
+
+        for path in injections[name]:
+            injected = _inject_into(variables, path, key=name, value=serialized)
+
+            if injected is not None:
+                variables = injected
+
+    return variables
+
+
+def _inject_into(
+    container: Mapping[str, object],
+    path: tuple[str, ...],
+    /,
+    *,
+    key: str,
+    value: object,
+) -> dict[str, object] | None:
+    """Copied along the path, since the caller may reuse what it passed.
+
+    ``None`` when an object on the path is absent or null, as a nullable input the caller left out is: there is nothing to inject into.
+    """
+    if not path:
+        return {**container, key: value}
+
+    head, *rest = path
+    child = container.get(head)
+
+    if child is None:
+        return None
+
+    # The generator only emits paths through input objects.
+    assert isinstance(child, Mapping), (
+        f"Expected `{head}` to hold an input object to inject `{key}` into."
+    )
+    injected = _inject_into(child, tuple(rest), key=key, value=value)
+    return None if injected is None else {**container, head: injected}