graphql-codegen 0.1.0__py3-none-any.whl

graphql_codegen/runtime/operation.py

@@ -0,0 +1,135 @@
+# Copied into each generated package, where this line says not to edit it.
+
+from collections.abc import Mapping
+from functools import cached_property
+from json import dumps
+from types import MappingProxyType
+from typing import Any, Final, Generic, TypeVar, final, override
+
+from ._literal import ExecutionErrorHandling, OperationType
+from ._reflection import Convert, build_parser, build_serializer
+from ._sigil import SIGIL
+from .error import ExecutionError
+
+_VARIABLES_KEY: Final = ',"variables":'
+_NO_INJECTIONS: Final[Mapping[str, frozenset[tuple[str, ...]]]] = MappingProxyType(
+    dict[str, frozenset[tuple[str, ...]]]()
+)
+
+# Declared, since PEP 695 infers variance from every method.
+# Covariant, so that an operation of one type, or its request, is also one of any type.
+_Type_co = TypeVar("_Type_co", bound=OperationType, covariant=True)
+# Both held by `variables_type` and taken by `__call__`.
+_Variables = TypeVar("_Variables", bound=Mapping[str, object])
+_Data_co = TypeVar("_Data_co", covariant=True)
+
+
+@final
+class Operation(Generic[_Type_co, _Variables, _Data_co]):
+    """A generated operation, parameterized by its type, what it sends, and what it returns, in the order things happen.
+
+    Its type is a parameter, so that clients tell operation types apart statically: a subscription client takes subscriptions only, and a merge takes operations of one type.
+    """
+
+    def __init__(
+        self,
+        *,
+        operation_type: _Type_co,
+        name: str,
+        document: str,
+        variables_type: type[_Variables],
+        injections: Mapping[str, frozenset[tuple[str, ...]]] = _NO_INJECTIONS,
+        data_type: type[_Data_co],
+    ) -> None:
+        """*document* has the merge sigil wherever its index in a merge goes, and *injections* the path of every object receiving each injector's value, by injector name, `()` being the variables themselves.
+
+        The key an injection writes is the injector's name, which the variables' type lacks, so that callers cannot pass it.
+        What crosses the wire is read off *variables_type* and *data_type* at runtime: they are the only description of it.
+        """
+        self._operation_type: Final = operation_type
+        self._name: Final = name
+        self._document: Final = document
+        self._variables_type: Final = variables_type
+        self._injections: Final = injections
+        self._data_type: Final = data_type
+
+    def __call__(self, variables: _Variables, /) -> "Request[_Type_co, _Data_co]":
+        """Return the request running this operation with *variables*, checked here, before anything runs.
+
+        Their type is already bound here, so every type checker checks them exactly, whereas from a function taking both an operation and its variables, some type checkers would infer a wider type.
+        """
+        return Request(operation=self, variables=variables, on_execution_error="raise")
+
+    @override
+    def __repr__(self) -> str:
+        # The operation, rather than its document.
+        return (
+            f"Operation(operation_type={self._operation_type!r}, name={self._name!r})"
+        )
+
+    @cached_property
+    def _data_parser(self) -> Convert | None:
+        """Only custom scalars with a codec and `@nonNull` fields cost anything at runtime."""
+        return build_parser(self._data_type, partial=False)
+
+    @cached_property
+    def _partial_data_parser(self) -> Convert | None:
+        return build_parser(self._data_type, partial=True)
+
+    @cached_property
+    def _variables_serializer(self) -> Convert | None:
+        return build_serializer(self._variables_type)
+
+    @cached_property
+    def _request_prefix(self) -> bytes:
+        """Serialized once, since the document's string escaping costs as much as the document is long."""
+        envelope = dumps(
+            {"operationName": self._name, "query": self._document.replace(SIGIL, "")}
+        )
+        return (envelope[:-1] + _VARIABLES_KEY).encode()
+
+    def _request_body(self, variables: Mapping[str, object], /) -> bytes:
+        # `json.dumps()`'s default separators are what make the concatenation valid JSON.
+        return self._request_prefix + dumps(variables).encode() + b"}"
+
+
+@final
+class Request(Generic[_Type_co, _Data_co]):
+    """An operation with the variable values its caller gives, not yet those the client injects, as a :class:`requests.Request` does not yet hold the headers its session adds.
+
+    It runs nothing: `ListBooks({"first": 10})` is a value that a client runs, synchronously or not.
+    """
+
+    __slots__ = ("_on_execution_error", "_operation", "_variables")
+
+    def __init__(
+        self,
+        *,
+        # The variables' type has served its purpose once they are checked.
+        operation: Operation[_Type_co, Any, _Data_co],
+        variables: Mapping[str, object],
+        on_execution_error: ExecutionErrorHandling,
+    ) -> None:
+        self._operation: Final = operation
+        self._variables: Final = variables
+        self._on_execution_error: Final = on_execution_error
+
+    @override
+    def __repr__(self) -> str:
+        return f"Request(operation={self._operation!r}, variables={self._variables!r}, on_execution_error={self._on_execution_error!r})"
+
+    def returning_error(
+        self,
+    ) -> "Request[_Type_co, _Data_co | ExecutionError[_Data_co]]":
+        """Return a copy of this request whose :class:`~.error.ExecutionError` a client returns in place of its data instead of raising it.
+
+        The returned error is typed by the request, and so is its :meth:`~.error.ExecutionError.parse_data`, which no `except` clause can express; a caller tells it apart from the data before use.
+        Every other error still raises, since it means that the request as a whole failed.
+
+        """
+        # A request's data type being covariant, one returning its data is one returning its data or its error.
+        return Request(
+            operation=self._operation,
+            variables=self._variables,
+            on_execution_error="return",
+        )

graphql_codegen/scalar.py

@@ -0,0 +1,59 @@
+from dataclasses import dataclass
+from functools import cached_property
+from typing import final
+
+from graphql_codegen._generator.dotted_name import Reference, parse_dotted_name
+from graphql_codegen._note import error_note
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class Codec:
+    """The functions converting a scalar's value between JSON and Python, such as a :class:`~datetime.datetime` sent as an ISO string."""
+
+    decode: str
+    """The dotted name of the function converting its JSON value to its Python one."""
+
+    encode: str
+    """The dotted name of the function converting its Python value to its JSON one."""
+
+    def __post_init__(self) -> None:
+        # Parsed eagerly, so that no codec holds a dotted name it cannot use.
+        _ = self._decode_reference, self._encode_reference
+
+    @cached_property
+    def _decode_reference(self) -> Reference:
+        with error_note("In `decode`."):
+            return parse_dotted_name(self.decode)
+
+    @cached_property
+    def _encode_reference(self) -> Reference:
+        with error_note("In `encode`."):
+            return parse_dotted_name(self.encode)
+
+
+@final
+@dataclass(frozen=True, kw_only=True)
+class Scalar:
+    """How a scalar is typed, and converted if its Python value differs from its JSON one.
+
+    Not only a custom scalar: a built-in one can be given a type of its own too, such as `ID` typed `my_app.UserId`.
+    """
+
+    type: str
+    """The dotted name of its Python type.
+
+    When :attr:`codec` is ``None``, it must describe the decoded JSON value: a builtin, such as :class:`int`, or a :class:`typing.NewType` or type alias of one, such as `my_app.Isbn = NewType("Isbn", str)`.
+    """
+
+    codec: Codec | None = None
+    """When ``None``, the value stays as JSON decodes it."""
+
+    def __post_init__(self) -> None:
+        # Parsed eagerly, so that no scalar holds a dotted name it cannot use.
+        _ = self._type_reference
+
+    @cached_property
+    def _type_reference(self) -> Reference:
+        with error_note("In `type`."):
+            return parse_dotted_name(self.type)