GitHub

API reference for client.

A typed GraphQL client from a group (Effect's GraphQLClient).

make(Group) reads the GraphQLProtocol and the group's middleware services and gives an instance of the group whose operations are methods. A query or mutation method gives an Effect, a subscription method a Stream retried by subscription_retry while its failures are retryable (default_subscription_retry: 500ms, then x1.5 up to 5s, never shorter than a retry_after). pages / items follow cursor connections; make_test / layer_test stand a client in for tests.

Values

AttributeTypeDescription
default_subscription_retrySchedule[Duration, GraphQLClientError]

500ms, then x1.5 each retry, capped at 5s and never shorter than the error's retry_after.

Types

TypeDefinitionDescription
TestHandlertype TestHandler = Callable[[Any, TestCallOptions], Effect[Any, Any] | Stream[Any, Any]]

A test handler: the caller's variables and options in, the result (a stream, for a subscription) out.

Classes

Functions

retryable_only

retryable_only[O, E, R](schedule) -> Schedule[O | None, object, E, R]

schedule stepped only by retryable GraphQLClientErrors; any other failure (a middleware's, a fatal one) stops it.

ParameterTypeDescription
scheduleSchedule[O, GraphQLClientError, E, R]

Returns Schedule[O | None, object, E, R]

def retryable_only[O, E, R](
    schedule: Schedule[O, GraphQLClientError, E, R],
) -> Schedule[O | None, object, E, R]:
    """``schedule`` stepped only by retryable ``GraphQLClientError``s; any
    other failure (a middleware's, a fatal one) stops it."""

    def guard(
        step: StepFn[O, GraphQLClientError, E, R],
    ) -> StepFn[O | None, object, E, R]:
        def guarded(now: float, input: object) -> Pull[tuple[O | None, Duration], E, O | None, R]:
            if isinstance(input, GraphQLClientError) and input.is_retryable:
                return step(now, input)
            return done(None)

        return guarded

    return from_step(to_step(schedule).map(guard))

make

make[G, T, OT](group, *, subscription_retry=None) -> Effect[G, Never, GraphQLProtocol | T | OT]

A client of group's operations, sending through the GraphQLProtocol and running the middleware services the context holds (the group's and its operations' own).

ParameterTypeDescription
groupGroupClass[G, T, OT]
subscription_retrySchedule[object, GraphQLClientError, Any, Any] | None = None

Returns Effect[G, Never, GraphQLProtocol | T | OT]

def make[G, T, OT](
    group: GroupClass[G, T, OT],
    *,
    subscription_retry: Schedule[object, GraphQLClientError, Any, Any] | None = None,
) -> Effect[G, Never, GraphQLProtocol | T | OT]:
    """A client of ``group``'s operations, sending through the
    ``GraphQLProtocol`` and running the middleware services the context
    holds (the group's and its operations' own)."""
    cls = cast("type[GraphQLGroup[Any, Any]]", group)
    retry = retryable_only(
        default_subscription_retry if subscription_retry is None else subscription_retry
    )
    added = group_middlewares(cls)

    def build(protocol: GraphQLProtocolService, context: Context[Any]) -> G:
        methods: dict[AnyOperation, object] = {}
        for operation in operations_of(cls):
            middlewares = [context.get_unsafe(tag) for tag in (*added, *operation.middlewares)]
            chain = _Chain(operation, Codec(operation), middlewares, protocol)
            methods[operation] = _make_method(chain, retry)
        return cast("G", cls(methods))

    built: Effect[G, Never, Any] = GraphQLProtocol().flat_map(
        lambda protocol: fx.context().map(lambda context: build(protocol, context))
    )
    return built

pages

pages[V, A, ME, MR, C: Connection](method, *, variables, connection, options=None) -> Stream[C, GraphQLClientError | ME, MR]

Each page of the connection method's result holds, sending its endCursor as the after variable until hasNextPage is false. The operation must declare an optional $after: String. A null connection on the first page is an empty stream; on a later one, or a cursor that is null or does not advance, a PaginationError.

ParameterTypeDescription
methodMethod[V, A, ME, MR]
variablesV
connectionCallable[[A], C | None]
optionsPageOptions | None = None

Returns Stream[C, GraphQLClientError | ME, MR]

def pages[V, A, ME, MR, C: Connection](
    method: Method[V, A, ME, MR],
    *,
    variables: V,
    connection: Callable[[A], C | None],
    options: PageOptions | None = None,
) -> Stream[C, GraphQLClientError | ME, MR]:
    """Each page of the ``connection`` ``method``'s result holds, sending
    its ``endCursor`` as the ``after`` variable until ``hasNextPage`` is
    false. The operation must declare an optional ``$after: String``. A
    null connection on the first page is an empty stream; on a later one,
    or a cursor that is null or does not advance, a ``PaginationError``."""
    given = PageOptions() if options is None else options
    call = cast("Callable[..., Effect[A, GraphQLClientError | ME, MR]]", method)
    name = method.operation.name
    first = cast("Mapping[str, object]", variables)

    def page(
        after: str | None,
    ) -> Effect[tuple[Iterable[C], Option[str]], GraphQLClientError | ME, MR]:
        def fail(description: str) -> Effect[Never, GraphQLClientError]:
            reason = PaginationError(description=description, cursor=after)
            return fx.fail(GraphQLClientError(operation=name, reason=reason))

        def next_page(result: A) -> Effect[tuple[Iterable[C], Option[str]], GraphQLClientError]:
            found = connection(result)
            if found is None:
                if after is None:
                    return fx.succeed(((), None))
                return fail("The connection was null on a page after the first")
            info = found["pageInfo"]
            end = info["endCursor"]
            if not info["hasNextPage"]:
                return fx.succeed(((found,), None))
            if end is None:
                return fail("hasNextPage is true but endCursor is null")
            if end == after:
                return fail(f'endCursor "{end}" did not advance')
            return fx.succeed(((found,), Some(end)))

        sent = first if after is None else {**first, "after": after}
        return call(
            sent, headers=given.headers, url_params=given.url_params, context=given.context
        ).flat_map(next_page)

    return stream.paginate(None, page)

items

items[V, A, ME, MR, N](method, *, variables, connection, options=None) -> Stream[N, GraphQLClientError | ME, MR]

The nodes of every page (pages), null entries included.

ParameterTypeDescription
methodMethod[V, A, ME, MR]
variablesV
connectionCallable[[A], NodesConnection[N] | None]
optionsPageOptions | None = None

Returns Stream[N, GraphQLClientError | ME, MR]

def items[V, A, ME, MR, N](
    method: Method[V, A, ME, MR],
    *,
    variables: V,
    connection: Callable[[A], NodesConnection[N] | None],
    options: PageOptions | None = None,
) -> Stream[N, GraphQLClientError | ME, MR]:
    """The ``nodes`` of every page (``pages``), null entries included."""
    connections = pages(method, variables=variables, connection=connection, options=options)
    return connections.flat_map(lambda found: stream.from_iterable(found["nodes"] or ()))

make_test

make_test[G](group, **handlers) -> G

A client of group whose methods call handlers (keyed by the group's attribute names) instead of a transport; an operation without a handler dies with an UnimplementedError. partial=True gives the handler's value with no errors.

ParameterTypeDescription
groupGroupClass[G, Any, Any]
handlersTestHandler = {}

Returns G

def make_test[G](group: GroupClass[G, Any, Any], /, **handlers: TestHandler) -> G:
    """A client of ``group`` whose methods call ``handlers`` (keyed by the
    group's attribute names) instead of a transport; an operation without
    a handler dies with an ``UnimplementedError``. ``partial=True`` gives
    the handler's value with no errors."""
    cls = cast("type[GraphQLGroup[Any, Any]]", group)
    declared = {name: _raw_attribute(cls, name) for name in handlers}
    unknown = [
        name for name, op in declared.items() if not isinstance(op, (Operation, Subscription))
    ]
    if unknown:
        raise ValueError(f"make_test: {cls.__qualname__} has no operations {unknown!r}")
    methods: dict[AnyOperation, object] = {}
    for operation in operations_of(cls):
        handler = next((handlers[n] for n, op in declared.items() if op is operation), None)
        methods[operation] = _test_method(operation, handler)
    return cast("G", cls(methods))

layer_test

layer_test[G, I](tag, group, **handlers) -> Layer[I]

A layer providing make_test(group, **handlers) as tag's service.

ParameterTypeDescription
tagProvides[G, I]
groupGroupClass[G, Any, Any]
handlersTestHandler = {}

Returns Layer[I]

def layer_test[G, I](
    tag: Provides[G, I], group: GroupClass[G, Any, Any], /, **handlers: TestHandler
) -> Layer[I]:
    """A layer providing ``make_test(group, **handlers)`` as ``tag``'s
    service."""
    return layer_succeed(tag, make_test(group, **handlers))