GitHub

API reference for client.

HTTP clients (Effect's HttpClient).

HttpClient is the service; httpx_client.layer provides one backed by httpx (the pyfect-dev[httpx] extra), and layer_test one answering from a function. A client is a value: its methods send requests and build new clients::

from pyfect.http import client, response

@fx.fn
def get_todo(todo_id: int):
    http = (yield from client.HttpClient()).filter_status_ok().retry_transient(times=3)
    res = yield from http.get(f"https://api.example.com/todos/{todo_id}")
    return (yield from response.schema_body_json(Todo)(res))

Every request runs in a client span with the HTTP semantic attributes and sends traceparent / b3 headers; interrupting a request aborts it. transform_response and catch_tag, which change the error type through a function of it, are used with .pipe.

Re-exports

Types

TypeDefinitionDescription
Phasetype Phase = Literal['request', 'response']
Sendtype Send = Callable[[HttpClientRequest, _url.Url, AbortSignal, Fiber[Any, Any]], Effect[HttpClientResponse, HttpClientError]]

What a client backend implements: send the request to the URL (built from its url, url_params and hash), stopping when the signal aborts.

Postprocesstype Postprocess[E, R] = Callable[[Effect[HttpClientRequest, E, R]], Effect[HttpClientResponse, E, R]]
Preprocesstype Preprocess[E, R] = Callable[[HttpClientRequest], Effect[HttpClientRequest, E, R]]
RetryOntype RetryOn = Literal['errors-only', 'response-only', 'errors-and-responses']

Classes

Functions

layer_test

layer_test(handler) -> Layer[HttpClient]

An HttpClient answering each request with handler (built with make, so URLs, tracing and interruption behave as with a real backend).

ParameterTypeDescription
handlerCallable[[HttpClientRequest], Effect[HttpClientResponse, HttpClientError]]

Returns Layer[HttpClient]

def layer_test(
    handler: Callable[[HttpClientRequest], Effect[HttpClientResponse, HttpClientError]],
) -> Layer[HttpClient]:
    """An ``HttpClient`` answering each request with ``handler`` (built
    with ``make``, so URLs, tracing and interruption behave as with a real
    backend)."""
    return layer_succeed(HttpClient, make(lambda request, _url, _signal, _fiber: handler(request)))

circuit_breaker_classifier

circuit_breaker_classifier(exit, context=None) -> Effect[Outcome]

The default with_circuit_breaker classifier, the same for the probe (context) as for any call. A failure: a timeout, a transport error, or a 408, 500, 502, 503 or 504 status (returned or wrapped in an HttpClientError), with the response's Retry-After (the longest of several) as the hint. Ignored: a 429 (left to with_rate_limiter), other HttpClientError reasons, other errors and defects. Any other status is a success. Of several errors, a failing one wins over a successful one, which wins over the ignored ones.

ParameterTypeDescription
exitExit[HttpClientResponse, object]
contextClassifyContext | None = None

Returns Effect[Outcome]

def circuit_breaker_classifier(
    exit: Exit[HttpClientResponse, object], context: ClassifyContext | None = None
) -> Effect[Outcome]:
    """The default ``with_circuit_breaker`` classifier, the same for the
    probe (``context``) as for any call. A failure: a
    timeout, a transport error, or a 408, 500, 502, 503 or 504 status
    (returned or wrapped in an ``HttpClientError``), with the response's
    ``Retry-After`` (the longest of several) as the hint. Ignored: a 429
    (left to ``with_rate_limiter``), other ``HttpClientError`` reasons,
    other errors and defects. Any other status is a success. Of several
    errors, a failing one wins over a successful one, which wins over the
    ignored ones."""
    return now_nanos().map(lambda nanos: _classify(exit, nanos // 1_000_000))

make

make(send) -> HttpClientService[HttpClientError]

A client sending each request with send. It builds the URL (failing with an InvalidUrlError), runs each request in a client span with HTTP attributes and trace headers, and aborts the request's signal when it is interrupted or its unread response is dropped.

ParameterTypeDescription
sendSend

Returns HttpClientService[HttpClientError]

def make(send: Send) -> HttpClientService[HttpClientError]:
    """A client sending each request with ``send``. It builds the URL
    (failing with an ``InvalidUrlError``), runs each request in a client
    span with HTTP attributes and trace headers, and aborts the request's
    signal when it is interrupted or its unread response is dropped."""

    def postprocess(
        requests: Effect[HttpClientRequest, Any, Any],
    ) -> Effect[HttpClientResponse, HttpClientError]:
        return requests.flat_map(
            lambda request: _WithFiber(lambda fiber: _send(send, request, fiber))
        )

    return HttpClientService(postprocess, succeed)

is_transient_error

is_transient_error(error) -> bool

A timeout, a transport failure, or a transient status.

ParameterTypeDescription
errorobject

Returns bool

def is_transient_error(error: object) -> bool:
    """A timeout, a transport failure, or a transient status."""
    if isinstance(error, TimeoutException):
        return True
    if not isinstance(error, HttpClientError):
        return False
    reason = error.reason
    return isinstance(reason, TransportError) or (
        isinstance(reason, StatusCodeError) and is_transient_response(reason.response)
    )

is_transient_response

is_transient_response(response) -> bool
ParameterTypeDescription
responseHttpClientResponse

Returns bool

def is_transient_response(response: HttpClientResponse) -> bool:
    return response.status in _TRANSIENT_STATUSES

with_retry_after

with_retry_after[O, E, R](schedule) -> Schedule[O, Any, E, R]

schedule, waiting at least each input's Retry-After.

ParameterTypeDescription
scheduleSchedule[O, Any, E, R]

Returns Schedule[O, Any, E, R]

def with_retry_after[O, E, R](schedule: Schedule[O, Any, E, R]) -> Schedule[O, Any, E, R]:
    """``schedule``, waiting at least each input's ``Retry-After``."""

    def wrap(step: StepFn[O, Any, E, R]) -> StepFn[O, Any, E, R]:
        def run(now: float, input: Any) -> Pull[tuple[O, Duration], E, O, R]:
            retry_after = retry_after_of(input, now)
            if retry_after is None:
                return step(now, input)
            return step(now, input).map(lambda result: (result[0], max(result[1], retry_after)))

        return run

    return from_step(to_step(schedule).map(wrap))

catch_tag

catch_tag[T, E2 = Never, R2 = Never](tag, f) -> _CatchTag[T, E2, R2]

Recover from the failures that are instances of tag and remove them from the client's errors. Use with .pipe.

ParameterTypeDescription
tagTags[T]
fCallable[[T], Effect[HttpClientResponse, E2, R2]]

Returns _CatchTag[T, E2, R2]

def catch_tag[T, E2 = Never, R2 = Never](
    tag: Tags[T], f: Callable[[T], Effect[HttpClientResponse, E2, R2]]
) -> _CatchTag[T, E2, R2]:
    """Recover from the failures that are instances of ``tag`` and remove
    them from the client's errors. Use with ``.pipe``."""
    return _CatchTag(tag, f)

delete

delete(url, **options) -> Effect[HttpClientResponse, HttpClientError, HttpClient]
ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, HttpClientError, HttpClient]

def delete(
    url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
    return execute(_request.delete(url, **options))

execute

execute(request) -> Effect[HttpClientResponse, HttpClientError, HttpClient]

Send request with the HttpClient service.

ParameterTypeDescription
requestHttpClientRequest

Returns Effect[HttpClientResponse, HttpClientError, HttpClient]

def execute(request: HttpClientRequest) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
    """Send ``request`` with the ``HttpClient`` service."""
    return HttpClient().flat_map(lambda client: client.execute(request))

get

get(url, **options) -> Effect[HttpClientResponse, HttpClientError, HttpClient]
ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, HttpClientError, HttpClient]

def get(
    url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
    return execute(_request.get(url, **options))
head(url, **options) -> Effect[HttpClientResponse, HttpClientError, HttpClient]
ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, HttpClientError, HttpClient]

def head(
    url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
    return execute(_request.head(url, **options))

make_with

make_with[E, R](postprocess, preprocess) -> HttpClientService[E, R]
ParameterTypeDescription
postprocessCallable[[Effect[HttpClientRequest, Any, Any]], Effect[HttpClientResponse, E, R]]
preprocessCallable[[HttpClientRequest], Effect[HttpClientRequest, Any, Any]]

Returns HttpClientService[E, R]

def make_with[E, R](
    postprocess: Callable[[Effect[HttpClientRequest, Any, Any]], Effect[HttpClientResponse, E, R]],
    preprocess: Callable[[HttpClientRequest], Effect[HttpClientRequest, Any, Any]],
) -> HttpClientService[E, R]:
    return HttpClientService(postprocess, preprocess)

options

options(url, **options) -> Effect[HttpClientResponse, HttpClientError, HttpClient]
ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, HttpClientError, HttpClient]

def options(
    url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
    return execute(_request.options(url, **options))

patch

patch(url, **options) -> Effect[HttpClientResponse, HttpClientError, HttpClient]
ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, HttpClientError, HttpClient]

def patch(
    url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
    return execute(_request.patch(url, **options))

post

post(url, **options) -> Effect[HttpClientResponse, HttpClientError, HttpClient]
ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, HttpClientError, HttpClient]

def post(
    url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
    return execute(_request.post(url, **options))

put

put(url, **options) -> Effect[HttpClientResponse, HttpClientError, HttpClient]
ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, HttpClientError, HttpClient]

def put(
    url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
    return execute(_request.put(url, **options))

query

query(url, **options) -> Effect[HttpClientResponse, HttpClientError, HttpClient]
ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, HttpClientError, HttpClient]

def query(
    url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
    return execute(_request.query(url, **options))

transform_response

transform_response[E, R, E1 = Never, R1 = Never](f) -> Callable[[HttpClientService[E, R]], HttpClientService[E1, R1]]

Replace sending with f(sending); f decides the error type. Use with .pipe.

ParameterTypeDescription
fCallable[[Effect[HttpClientResponse, E, R]], Effect[HttpClientResponse, E1, R1]]

Returns Callable[[HttpClientService[E, R]], HttpClientService[E1, R1]]

def transform_response[E, R, E1 = Never, R1 = Never](
    f: Callable[[Effect[HttpClientResponse, E, R]], Effect[HttpClientResponse, E1, R1]],
) -> Callable[[HttpClientService[E, R]], HttpClientService[E1, R1]]:
    """Replace sending with ``f(sending)``; ``f`` decides the error type.
    Use with ``.pipe``."""
    return lambda client: client._on_response(f)  # pyright: ignore[reportPrivateUsage]