GitHub

atom_http_api

API reference for atom_http_api.

Atoms over a derived HttpApi client (Effect's effect/reactivity/AtomHttpApi).

make(tag, api=api, http_client=layer) gives an AtomHttpApiClient: a runtime whose layer provides tag with http_api.client.make(api) over the HttpClient the layer gives, query atoms calling an endpoint, query_of, a query as a function of its request parts (a wrong part is a type error there, and accepted by query), mutation function atoms, and mutate, a mutation as a function of its request parts::

class UsersApi(Tag[Client[Users]], key="UsersApi"): ...

client = atom_http_api.make(UsersApi, api=api, http_client=http_layer)
user = client.query_of(Users, Users.get_user)(params={"id": 1})
create = client.mutate(Users, Users.create)
yield from create(payload={"name": "x"}, reactivity_keys=["users"])

An HttpClientError or SchemaError of a call is a defect; the atoms fail with the endpoint's declared errors and its middleware's. A decoded-only query with a serialization_key is serializable (hydration), as AtomHttpApi:<group>:<endpoint>:<key>; so is a decoded-only mutation, as AtomHttpApi:mutation:[id,group,endpoint]. Equal arguments give the same atom.

Types

TypeDefinitionDescription
HttpClientLayertype HttpClientLayer = Layer[Any, Never, Any]

The layer giving the HttpClient (and the client side of the endpoints' middleware).

Classes

Functions

make

make[G: HttpApiGroup[Any], T](tag, *, api, http_client, transform_client=None, transform_response=None, base_url=None, runtime=runtime) -> AtomHttpApiClient[T, G]

Atoms over the client of api provided as tag (Effect's AtomHttpApi.Service): http_api.client.make(api, ...) with transform_client, transform_response and base_url, over the HttpClient of http_client (a layer, or a function of the atom context giving one). runtime is the runtime factory.

ParameterTypeDescription
tagProvides[api_client.Client[G], T]
apiHttpApi[G]
http_clientHttpClientLayer | Callable[[AtomContext], HttpClientLayer]
transform_clientCallable[[HttpClientService[HttpClientError, Never]], HttpClientService[Any, Any]] | None = None
transform_responseapi_client.TransformResponse | None = None
base_urlstr | None = None
runtimeRuntimeFactory = runtime

Returns AtomHttpApiClient[T, G]

def make[G: HttpApiGroup[Any], T](
    tag: Provides[api_client.Client[G], T],
    *,
    api: HttpApi[G],
    http_client: HttpClientLayer | Callable[[AtomContext], HttpClientLayer],
    transform_client: Callable[
        [HttpClientService[HttpClientError, Never]], HttpClientService[Any, Any]
    ]
    | None = None,
    transform_response: api_client.TransformResponse | None = None,
    base_url: str | None = None,
    runtime: RuntimeFactory = runtime,
) -> AtomHttpApiClient[T, G]:
    """Atoms over the client of ``api`` provided as ``tag`` (Effect's
    ``AtomHttpApi.Service``): ``http_api.client.make(api, ...)`` with
    ``transform_client``, ``transform_response`` and ``base_url``, over
    the ``HttpClient`` of ``http_client`` (a layer, or a function of the
    atom context giving one). ``runtime`` is the runtime factory."""
    client_layer: Layer[T, Never, Any] = layer_effect(
        tag,
        api_client.make(
            api,
            transform_client=transform_client,
            transform_response=transform_response,
            base_url=base_url,
        ),
    )

    def with_http(layer: HttpClientLayer) -> Layer[T]:
        return client_layer.pipe(provide(layer))

    if isinstance(http_client, Layer):
        atom_runtime = runtime(with_http(cast("HttpClientLayer", http_client)))
    else:
        make_http = http_client
        atom_runtime = runtime(lambda get: with_http(make_http(get)))
    return AtomHttpApiClient(tag, api, atom_runtime)