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#
| Type | Definition | Description |
|---|---|---|
Phase | type Phase = Literal['request', 'response'] | |
Send | type 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 |
Postprocess | type Postprocess[E, R] = Callable[[Effect[HttpClientRequest, E, R]], Effect[HttpClientResponse, E, R]] | |
Preprocess | type Preprocess[E, R] = Callable[[HttpClientRequest], Effect[HttpClientRequest, E, R]] | |
RetryOn | type 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).
| Parameter | Type | Description |
|---|---|---|
handler | Callable[[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.
| Parameter | Type | Description |
|---|---|---|
exit | Exit[HttpClientResponse, object] | |
context | ClassifyContext | 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.
| Parameter | Type | Description |
|---|---|---|
send | Send |
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) -> boolA timeout, a transport failure, or a transient status.
| Parameter | Type | Description |
|---|---|---|
error | object |
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| Parameter | Type | Description |
|---|---|---|
response | HttpClientResponse |
Returns bool
def is_transient_response(response: HttpClientResponse) -> bool:
return response.status in _TRANSIENT_STATUSESwith_retry_after#
with_retry_after[O, E, R](schedule) -> Schedule[O, Any, E, R]schedule, waiting at least each input's Retry-After.
| Parameter | Type | Description |
|---|---|---|
schedule | Schedule[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.
| Parameter | Type | Description |
|---|---|---|
tag | Tags[T] | |
f | Callable[[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]| Parameter | Type | Description |
|---|---|---|
url | UrlInput | |
options | Unpack[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.
| Parameter | Type | Description |
|---|---|---|
request | HttpClientRequest |
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]| Parameter | Type | Description |
|---|---|---|
url | UrlInput | |
options | Unpack[RequestOptions] = {} |
Returns Effect[HttpClientResponse, HttpClientError, HttpClient]
def get(
url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, HttpClientError, HttpClient]:
return execute(_request.get(url, **options))head#
head(url, **options) -> Effect[HttpClientResponse, HttpClientError, HttpClient]| Parameter | Type | Description |
|---|---|---|
url | UrlInput | |
options | Unpack[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]| Parameter | Type | Description |
|---|---|---|
postprocess | Callable[[Effect[HttpClientRequest, Any, Any]], Effect[HttpClientResponse, E, R]] | |
preprocess | Callable[[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]| Parameter | Type | Description |
|---|---|---|
url | UrlInput | |
options | Unpack[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]| Parameter | Type | Description |
|---|---|---|
url | UrlInput | |
options | Unpack[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]| Parameter | Type | Description |
|---|---|---|
url | UrlInput | |
options | Unpack[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]| Parameter | Type | Description |
|---|---|---|
url | UrlInput | |
options | Unpack[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]| Parameter | Type | Description |
|---|---|---|
url | UrlInput | |
options | Unpack[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.
| Parameter | Type | Description |
|---|---|---|
f | Callable[[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]