GitHub

resolver

API reference for resolver.

Batched lookups through a GraphQL client method (Effect's GraphQLResolver).

ordered matches results by position, find_by_id by key, and aliased repeats an operation under aliases in one request; request(resolver) turns any of them into key -> Effect::

get_repo = resolver.request(
    resolver.ordered(
        api.repo_nodes,
        variables=lambda ids: {"ids": ids},
        items=lambda data: data["nodes"],
        typename="Repository",
    )
)
repos = yield from fx.for_each(ids, get_repo, concurrency="unbounded")

Lookups made together become one call. A missing item (null, or of another typename) fails its lookup with NoSuchElementException; an error at [*path, i] fails only lookup i. Client middleware still run. batch_key keeps lookups with different services (a middleware's requirements) in separate batches, and lookups whose protocol URLs differ go in separate batches too; batch_n limits each batch.

items picks the list out of the operation's result by indexing its fields (lambda data: data["search"]["nodes"]), so lookups succeed with the list's item type; it is run once, on a stand-in, to learn the path. Effect's form, a path of field names, is kept, and its lookups succeed with Any.

Types

TypeDefinitionDescription
BatchKeytype BatchKey = Callable[[Context[Any]], Hashable]

Splits lookups into batches by the services of the fiber that made them, such as the user a middleware authenticates as.

Resolvertype Resolver[K, A, E, R] = RequestResolver[KeyRequest[K, A, E, R], E]
Itemstype Items[A, T] = Callable[[A], Sequence[T | None] | None]

Where a result's list is: lambda data: data["nodes"].

Classes

Functions

request

request[K, A, E, R](resolver) -> Callable[[K], Effect[A, E, R]]

The function that looks a key up through resolver.

ParameterTypeDescription
resolverResolver[K, A, E, R]

Returns Callable[[K], Effect[A, E, R]]

def request[K, A, E, R](resolver: Resolver[K, A, E, R], /) -> Callable[[K], Effect[A, E, R]]:
    """The function that looks a key up through ``resolver``."""
    resolve_url = _url_resolvers.get(resolver.batch_key)

    def get(key: K) -> Effect[A, E, R]:
        if resolve_url is None:
            return _queue(KeyRequest[K, A, E, R](key, None), resolver)
        return resolve_url.flat_map(lambda url: _queue(KeyRequest[K, A, E, R](key, url), resolver))

    return get

ordered

ordered[V, A, ME, MR, K, T](method: Method[V, A, ME, MR], *, variables: Callable[[Sequence[K]], V], items: Items[A, T], typename: str | None = None, batch_key: BatchKey | None = None) -> Resolver[K, T, GraphQLClientError | ME | NoSuchElementException, MR]
ordered[V, A, ME, MR, K](method: Method[V, A, ME, MR], *, variables: Callable[[Sequence[K]], V], path: Sequence[str], typename: str | None = None, batch_key: BatchKey | None = None) -> Resolver[K, Any, GraphQLClientError | ME | NoSuchElementException, MR]

Looks keys up by position: variables turns the batch's distinct keys into the operation's variables, and the list items picks (or the one at path) holds one item per key, in order (GitHub's nodes(ids:)). A null item, or one whose __typename is not typename, is a miss.

ParameterTypeDescription
method
variables
items= None
path= None
typename= None
batch_key= None
@overload
def ordered[V, A, ME, MR, K, T](
    method: Method[V, A, ME, MR],
    *,
    variables: Callable[[Sequence[K]], V],
    items: Items[A, T],
    typename: str | None = None,
    batch_key: BatchKey | None = None,
) -> Resolver[K, T, GraphQLClientError | ME | NoSuchElementException, MR]: ...
@overload
def ordered[V, A, ME, MR, K](
    method: Method[V, A, ME, MR],
    *,
    variables: Callable[[Sequence[K]], V],
    path: Sequence[str],
    typename: str | None = None,
    batch_key: BatchKey | None = None,
) -> Resolver[K, Any, GraphQLClientError | ME | NoSuchElementException, MR]: ...
def ordered(
    method: Method[Any, Any, Any, Any],
    *,
    variables: Callable[[Sequence[Any]], Any],
    items: Items[Any, Any] | None = None,
    path: Sequence[str] | None = None,
    typename: str | None = None,
    batch_key: BatchKey | None = None,
) -> Resolver[Any, Any, Any, Any]:
    """Looks keys up by position: ``variables`` turns the batch's distinct
    keys into the operation's variables, and the list ``items`` picks (or
    the one at ``path``) holds one item per key, in order (GitHub's
    ``nodes(ids:)``). A null item, or one whose ``__typename`` is not
    ``typename``, is a miss."""
    found_at = _path_of(items, path)
    codec = Codec(method.operation)

    def run_all(entries: Sequence[_AnyEntry]) -> Effect[None, Any, Any]:
        return _call_batch(method, entries, variables).flat_map(
            lambda batch: _complete_ordered(codec, batch, found_at, typename)
        )

    return _make_resolver(method, batch_key, run_all)

find_by_id

find_by_id[V, A, ME, MR, K, T](method: Method[V, A, ME, MR], *, variables: Callable[[Sequence[K]], V], items: Items[A, T], key: Callable[[T], K], typename: str | None = None, batch_key: BatchKey | None = None) -> Resolver[K, T, GraphQLClientError | ME | NoSuchElementException, MR]
find_by_id[V, A, ME, MR, K](method: Method[V, A, ME, MR], *, variables: Callable[[Sequence[K]], V], path: Sequence[str], key: Callable[[Any], K], typename: str | None = None, batch_key: BatchKey | None = None) -> Resolver[K, Any, GraphQLClientError | ME | NoSuchElementException, MR]

Looks keys up by key: the list items picks (or the one at path) may hold the items in any order (a search). A key no item has is a miss; any error fails the batch.

ParameterTypeDescription
method
variables
key
items= None
path= None
typename= None
batch_key= None
@overload
def find_by_id[V, A, ME, MR, K, T](
    method: Method[V, A, ME, MR],
    *,
    variables: Callable[[Sequence[K]], V],
    items: Items[A, T],
    key: Callable[[T], K],
    typename: str | None = None,
    batch_key: BatchKey | None = None,
) -> Resolver[K, T, GraphQLClientError | ME | NoSuchElementException, MR]: ...
@overload
def find_by_id[V, A, ME, MR, K](
    method: Method[V, A, ME, MR],
    *,
    variables: Callable[[Sequence[K]], V],
    path: Sequence[str],
    key: Callable[[Any], K],
    typename: str | None = None,
    batch_key: BatchKey | None = None,
) -> Resolver[K, Any, GraphQLClientError | ME | NoSuchElementException, MR]: ...
def find_by_id(
    method: Method[Any, Any, Any, Any],
    *,
    variables: Callable[[Sequence[Any]], Any],
    key: Callable[[Any], Any],
    items: Items[Any, Any] | None = None,
    path: Sequence[str] | None = None,
    typename: str | None = None,
    batch_key: BatchKey | None = None,
) -> Resolver[Any, Any, Any, Any]:
    """Looks keys up by ``key``: the list ``items`` picks (or the one at
    ``path``) may hold the items in any order (a search). A key no item
    has is a miss; any error fails the batch."""
    path = _path_of(items, path)
    codec = Codec(method.operation)

    def complete(batch: _Batch) -> Effect[None, Any]:
        if batch.result.errors:
            return _batch_error(codec, batch.result)
        found = _found(codec, batch, path)
        if not isinstance(found, FoundList):
            return found
        pending = {frozen(k): target for k, target in zip(batch.keys, batch.targets, strict=True)}
        for item in found.items:
            if not _matches(item, typename):
                continue
            target = pending.pop(frozen(key(item)), None)
            if target is not None:
                target(Success(item))
        return _complete_all(list(pending.values()))

    def run_all(entries: Sequence[_AnyEntry]) -> Effect[None, Any, Any]:
        return _call_batch(method, entries, variables).flat_map(complete)

    return _make_resolver(method, batch_key, run_all)

aliased

aliased[V, A, ME, MR](method, *, batch_key=None) -> Resolver[V, A, GraphQLClientError | ME, MR]

Looks up each set of variables with one request repeating the operation under aliases (_0_repository:repository(...)), at most 10 per request. Lookups whose encoded variables are equal share a slice. Over a make_test client, each slice calls the method. Raises ValueError for an operation without a document template or one that cannot be sliced.

ParameterTypeDescription
methodMethod[V, A, ME, MR]
batch_keyBatchKey | None = None

Returns Resolver[V, A, GraphQLClientError | ME, MR]

def aliased[V, A, ME, MR](
    method: Method[V, A, ME, MR],
    *,
    batch_key: BatchKey | None = None,
) -> Resolver[V, A, GraphQLClientError | ME, MR]:
    """Looks up each set of variables with one request repeating the
    operation under aliases (``_0_repository:repository(...)``), at most
    10 per request. Lookups whose encoded variables are equal share a
    slice. Over a ``make_test`` client, each slice calls the method.
    Raises ``ValueError`` for an operation without a document template or
    one that cannot be sliced."""
    operation = method.operation
    template = operation.template
    if template is None:
        raise ValueError(
            f"GraphQLResolver.aliased: operation {operation.name} has no document template"
        )
    unsliceable = unsliceable_reason(template)
    if unsliceable is not None:
        raise ValueError(
            f"GraphQLResolver.aliased: cannot batch operation {operation.name}: {unsliceable}"
        )
    codec = Codec(operation)
    execute = None if method.raw is None else method.raw.execute
    call = cast("Callable[[object], Effect[A, Any, Any]]", method)

    def send(slices: list[_Slice]) -> Effect[None, Any, Any]:
        if execute is None:
            return for_each(slices, lambda s: _complete_slice(s, call(s.variables))).as_void()
        if not slices:
            return fx.void
        prefixes = [f"_{i}_" for i in range(len(slices))]
        variables = {
            prefix + name: value
            for prefix, s in zip(prefixes, slices, strict=True)
            for name, value in cast("dict[str, object]", s.encoded or {}).items()
        }
        batched = GraphQLRequest(
            kind=operation.kind,
            query=render_slices(operation.kind, operation.name, template, prefixes),
            operation_name=operation.name,
            variables=variables,
        )

        def split(result: ExecutionResult) -> Effect[None, Any, Any]:
            results = split_slices(result, template, prefixes)
            if results is None:
                return codec.fail_response(result)
            return for_each(
                list(zip(slices, results, strict=True)),
                lambda pair: _complete_slice(pair[0], codec.decode_strict(pair[1])),
            ).as_void()

        return execute(batched).flat_map(split)

    def run_all(entries: Sequence[_AnyEntry]) -> Effect[None, Any, Any]:
        encoded = for_each(entries, lambda entry: codec.encode_variables(entry.request.key).exit())
        return encoded.flat_map(lambda exits: send(_slices_of(entries, exits)))

    return _make_resolver(method, batch_key, run_all).batch_n(10)