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#
| Attribute | Type | Description |
|---|---|---|
default_subscription_retry | Schedule[Duration, GraphQLClientError] | 500ms, then x1.5 each retry, capped at 5s and never shorter than the
error's |
Types#
| Type | Definition | Description |
|---|---|---|
TestHandler | type 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.
| Parameter | Type | Description |
|---|---|---|
schedule | Schedule[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).
| Parameter | Type | Description |
|---|---|---|
group | GroupClass[G, T, OT] | |
subscription_retry | Schedule[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 builtpages#
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.
| Parameter | Type | Description |
|---|---|---|
method | Method[V, A, ME, MR] | |
variables | V | |
connection | Callable[[A], C | None] | |
options | PageOptions | 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.
| Parameter | Type | Description |
|---|---|---|
method | Method[V, A, ME, MR] | |
variables | V | |
connection | Callable[[A], NodesConnection[N] | None] | |
options | PageOptions | 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) -> GA 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.
| Parameter | Type | Description |
|---|---|---|
group | GroupClass[G, Any, Any] | |
handlers | TestHandler = {} |
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.
| Parameter | Type | Description |
|---|---|---|
tag | Provides[G, I] | |
group | GroupClass[G, Any, Any] | |
handlers | TestHandler = {} |
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))