GitHub

API reference for client.

Clients derived from an HttpApi (Effect's HttpApiClient).

make(api) gives a Client; get_group(client, Users) is the Users group whose endpoint attributes are client methods::

api_client = yield from http_api.client.make(api, base_url="http://localhost:3000")
user = yield from get_group(api_client, Users).get_user(params={"id": 1})

A method encodes the request parts with the endpoint's schemas, runs the client middleware, sends the request and decodes the response: a declared success is the value, a declared error the failure, any other status an HttpClientError.

Types

TypeDefinitionDescription
TransformResponsetype TransformResponse = Callable[[Effect[Any, Any, Any]], Effect[Any, Any, Any]]

Classes

Functions

get_group

get_group[G: HttpApiGroup[Any, Any]](client, group) -> G

The group group of client: its endpoint attributes are client methods. A group the client's API lacks is a type error.

A function, not a method: pyright solves a method's type variables from self first, so client[Users] on a client of Users | Status would be typed Users | Status.

ParameterTypeDescription
clientClient[G]
grouptype[G]

Returns G

def get_group[G: HttpApiGroup[Any, Any]](client: Client[G], group: type[G], /) -> G:
    """The group ``group`` of ``client``: its endpoint attributes are client
    methods. A group the client's API lacks is a type error.

    A function, not a method: pyright solves a method's type variables from
    ``self`` first, so ``client[Users]`` on a client of ``Users | Status``
    would be typed ``Users | Status``."""
    return cast("G", client._groups[cast("AnyGroup", group).origin])  # pyright: ignore[reportPrivateUsage]

make

make[G](api, *, transform_client=None, transform_response=None, base_url=None) -> Effect[Client[G], Never, HttpClient]

The client of api sending through the HttpClient service (transform_client changes it first). The client middleware of the endpoints are read from the context; one not provided is left out.

ParameterTypeDescription
apiHttpApi[G]
transform_clientCallable[[HttpClientService[HttpClientError, Never]], HttpClientService[Any, Any]] | None = None
transform_responseTransformResponse | None = None
base_urlstr | Url | None = None

Returns Effect[Client[G], Never, HttpClient]

def make[G](
    api: HttpApi[G],
    *,
    transform_client: Callable[
        [HttpClientService[HttpClientError, Never]], HttpClientService[Any, Any]
    ]
    | None = None,
    transform_response: TransformResponse | None = None,
    base_url: str | Url | None = None,
) -> Effect[Client[G], Never, HttpClient]:
    """The client of ``api`` sending through the ``HttpClient`` service
    (``transform_client`` changes it first). The client middleware of
    the endpoints are read from the context; one not provided is left
    out."""

    def with_client(http: HttpClientService[HttpClientError, Never]) -> Effect[Client[G]]:
        client = http if transform_client is None else transform_client(http)
        return make_with(
            api, http_client=client, transform_response=transform_response, base_url=base_url
        )

    return HttpClient().flat_map(with_client)

make_with

make_with[G](api, *, http_client, transform_response=None, base_url=None) -> Effect[Client[G]]

make with the given HTTP client.

ParameterTypeDescription
apiHttpApi[G]
http_clientHttpClientService[Any, Any]
transform_responseTransformResponse | None = None
base_urlstr | Url | None = None

Returns Effect[Client[G]]

def make_with[G](
    api: HttpApi[G],
    *,
    http_client: HttpClientService[Any, Any],
    transform_response: TransformResponse | None = None,
    base_url: str | Url | None = None,
) -> Effect[Client[G]]:
    """``make`` with the given HTTP client."""

    def build(services: Context[Any]) -> Client[G]:
        methods: dict[AnyGroup, dict[str, Any]] = {g: {} for g in api.groups.values()}
        options = _Options(http_client, transform_response, base_url)
        for reflected, call in _reflect_calls(api, services, options):
            methods[reflected.group][reflected.endpoint.identifier] = EndpointClient(call)
        return Client({g.origin: _group_client(g, m) for g, m in methods.items()})

    return context().map(build)

group

group[G: HttpApiGroup[Any, Any]](api, group, *, http_client, transform_response=None, base_url=None) -> Effect[G]

The client of one group of api (a group it lacks is a type error).

ParameterTypeDescription
apiApiWith[G]
grouptype[G]
http_clientHttpClientService[Any, Any]
transform_responseTransformResponse | None = None
base_urlstr | Url | None = None

Returns Effect[G]

def group[G: HttpApiGroup[Any, Any]](
    api: ApiWith[G],
    group: type[G],
    *,
    http_client: HttpClientService[Any, Any],
    transform_response: TransformResponse | None = None,
    base_url: str | Url | None = None,
) -> Effect[G]:
    """The client of one group of ``api`` (a group it lacks is a type
    error)."""
    declared = cast("AnyGroup", group)
    the_api = api_of(api)

    def build(services: Context[Any]) -> G:
        calls = _reflect_calls(
            the_api,
            services,
            _Options(http_client, transform_response, base_url),
            predicate=lambda g, _e: g.identifier == declared.identifier,
        )
        methods: dict[str, Any] = {
            reflected.endpoint.identifier: EndpointClient(call) for reflected, call in calls
        }
        return cast("G", _group_client(the_api.groups[declared.identifier], methods))

    return context().map(build)

endpoint

endpoint[P, Q, B, CB, H, S1, CS, E, M](api, group, endpoint, *, http_client, transform_client=None, transform_response=None, base_url=None) -> Effect[EndpointClient[P, Q, CB, H, CS, E, Any]]

The client method of one endpoint of api (transform_client changes http_client first).

ParameterTypeDescription
apiHttpApi[Any]
groupAnyGroup
endpointHttpApiEndpoint[P, Q, B, CB, H, S1, CS, E, M]
http_clientHttpClientService[Any, Any]
transform_clientCallable[[HttpClientService[Any, Any]], HttpClientService[Any, Any]] | None = None
transform_responseTransformResponse | None = None
base_urlstr | Url | None = None

Returns Effect[EndpointClient[P, Q, CB, H, CS, E, Any]]

def endpoint[P, Q, B, CB, H, S1, CS, E, M](
    api: HttpApi[Any],
    group: AnyGroup,
    endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E, M],
    *,
    http_client: HttpClientService[Any, Any],
    transform_client: Callable[[HttpClientService[Any, Any]], HttpClientService[Any, Any]]
    | None = None,
    transform_response: TransformResponse | None = None,
    base_url: str | Url | None = None,
) -> Effect[EndpointClient[P, Q, CB, H, CS, E, Any]]:
    """The client method of one endpoint of ``api`` (``transform_client``
    changes ``http_client`` first)."""
    sending = http_client if transform_client is None else transform_client(http_client)

    def build(services: Context[Any]) -> EndpointClient[P, Q, CB, H, CS, E, Any]:
        [(_reflected, call)] = _reflect_calls(
            api,
            services,
            _Options(sending, transform_response, base_url),
            predicate=lambda g, e: (
                g.identifier == group.identifier and e.identifier == endpoint.identifier
            ),
        )
        return EndpointClient(call)

    return context().map(build)

decode_response

decode_response[P, Q, B, CB, H, S1, CS, E, M](api, group, endpoint) -> DecodeResponse[CS, E]

Decodes raw responses of endpoint of group as its client method does in "decoded-only" mode (Effect's decodeResponse), for a response read with response_only() whose body comes later (long polling). A declared error fails with the decoded error, an undeclared status with an HttpClientError (DecodeError). The body is read when the effect runs, so run it in the response's scope. Middleware and transform_response are not applied. Building it walks the API: build it once per endpoint.

ParameterTypeDescription
apiHttpApi[Any]
groupAnyGroup
endpointHttpApiEndpoint[P, Q, B, CB, H, S1, CS, E, M]

Returns DecodeResponse[CS, E]

def decode_response[P, Q, B, CB, H, S1, CS, E, M](
    api: HttpApi[Any],
    group: AnyGroup,
    endpoint: HttpApiEndpoint[P, Q, B, CB, H, S1, CS, E, M],
) -> DecodeResponse[CS, E]:
    """Decodes raw responses of ``endpoint`` of ``group`` as its client
    method does in ``"decoded-only"`` mode (Effect's ``decodeResponse``),
    for a response read with ``response_only()`` whose body comes later
    (long polling). A declared error fails with the decoded error, an
    undeclared status with an ``HttpClientError`` (``DecodeError``). The
    body is read when the effect runs, so run it in the response's scope.
    Middleware and ``transform_response`` are not applied. Building it
    walks the API: build it once per endpoint."""
    reflected: list[ReflectedEndpoint] = []
    reflect(
        api,
        on_group=lambda _g, _a: None,
        on_endpoint=reflected.append,
        predicate=lambda g, e: (
            g.identifier == group.identifier and e.identifier == endpoint.identifier
        ),
    )
    if not reflected:
        raise ValueError(
            f'HttpApiEndpoint "{group.identifier}.{endpoint.identifier}" not found in '
            f'HttpApi "{api.identifier}"'
        )
    return DecodeResponse(_response_decoder(reflected[0]))

is_upgraded

is_upgraded(value) -> TypeIs[api_schema.Upgraded[Any]]

value (a client method's result) is an upgraded connection (Effect's isUpgraded): an endpoint declaring an upgrade beside ordinary successes gives one or the other.

ParameterTypeDescription
valueobject

Returns TypeIs[api_schema.Upgraded[Any]]

def is_upgraded(value: object) -> TypeIs[api_schema.Upgraded[Any]]:
    """``value`` (a client method's result) is an upgraded connection
    (Effect's ``isUpgraded``): an endpoint declaring an upgrade beside
    ordinary successes gives one or the other."""
    return isinstance(value, api_schema.Upgraded)

compile_path

compile_path(path, schema) -> Callable[[Mapping[str, Any]], str]

The URL of path with the given encoded parameters. A missing required parameter, or one that is a dot segment, is an error.

ParameterTypeDescription
pathstr
schemaTop | None

Returns Callable[[Mapping[str, Any]], str]

def compile_path(path: str, schema: Top | None) -> Callable[[Mapping[str, Any]], str]:
    """The URL of ``path`` with the given encoded parameters. A missing
    required parameter, or one that is a dot segment, is an error."""
    if schema is None or ":" not in path:
        return lambda _params: path
    names = _path.param_names(schema)

    def make_url(params: Mapping[str, Any]) -> str:
        def replace(key: str, optional: bool) -> str | None:
            value = params.get(key)
            if value in (".", ".."):
                # Dot segments survive encoding and would be resolved by URL normalization.
                raise ValueError(f"Invalid path parameter: {key}")
            if value is not None:
                return quote(str(value), safe="!'()*-._~")
            if optional:
                return None
            raise ValueError(f"Missing path parameter: {key}")

        return _path.replace_params(path, names, replace)

    return make_url

url_builder

url_builder(api, *, base_url=None) -> UrlBuilder

The URLs of api's endpoints (see UrlBuilder).

ParameterTypeDescription
apiHttpApi[Any]
base_urlstr | Url | None = None

Returns UrlBuilder

def url_builder(api: HttpApi[Any], *, base_url: str | Url | None = None) -> UrlBuilder:
    """The URLs of ``api``'s endpoints (see ``UrlBuilder``)."""
    return UrlBuilder(api, base_url)