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#
| Type | Definition | Description |
|---|---|---|
TransformResponse | type TransformResponse = Callable[[Effect[Any, Any, Any]], Effect[Any, Any, Any]] |
Classes#
Functions#
get_group#
get_group[G: HttpApiGroup[Any, Any]](client, group) -> GThe 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.
| Parameter | Type | Description |
|---|---|---|
client | Client[G] | |
group | type[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.
| Parameter | Type | Description |
|---|---|---|
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 |
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.
| Parameter | Type | Description |
|---|---|---|
api | HttpApi[G] | |
http_client | HttpClientService[Any, Any] | |
transform_response | TransformResponse | None = None | |
base_url | str | 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).
| Parameter | Type | Description |
|---|---|---|
api | ApiWith[G] | |
group | type[G] | |
http_client | HttpClientService[Any, Any] | |
transform_response | TransformResponse | None = None | |
base_url | str | 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).
| Parameter | Type | Description |
|---|---|---|
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 |
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.
| Parameter | Type | Description |
|---|---|---|
api | HttpApi[Any] | |
group | AnyGroup | |
endpoint | HttpApiEndpoint[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.
| Parameter | Type | Description |
|---|---|---|
value | object |
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.
| Parameter | Type | Description |
|---|---|---|
path | str | |
schema | Top | 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_urlurl_builder#
url_builder(api, *, base_url=None) -> UrlBuilderThe URLs of api's endpoints (see UrlBuilder).
| Parameter | Type | Description |
|---|---|---|
api | HttpApi[Any] | |
base_url | str | 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)