GitHub

HttpClientService

API reference for HttpClientService.

class HttpClientService[E, R = Never]

A client failing with E and needing R: preprocess turns a request into the request to send, postprocess sends it.

The combinators are methods, but for catch_tag (which removes some types from the errors) and transform_response: functions used with .pipe.

Attributes

AttributeTypeDescription
preprocessCallable[[HttpClientRequest], Effect[HttpClientRequest, Any, Any]]

The function turning each request into the request to send (adding headers, a base URL and so on); execute runs it before postprocess.

postprocessCallable[[Effect[HttpClientRequest, Any, Any]], Effect[HttpClientResponse, E, R]]

The function sending the preprocessed request (an effect producing it) and giving the response, failing with E.

Functions

__init__

__init__(postprocess, preprocess) -> None
ParameterTypeDescription
postprocessCallable[[Effect[HttpClientRequest, Any, Any]], Effect[HttpClientResponse, E, R]]
preprocessCallable[[HttpClientRequest], Effect[HttpClientRequest, Any, Any]]
def __init__(
    self,
    postprocess: Callable[
        [Effect[HttpClientRequest, Any, Any]], Effect[HttpClientResponse, E, R]
    ],
    preprocess: Callable[[HttpClientRequest], Effect[HttpClientRequest, Any, Any]],
) -> None:
    self._postprocess = postprocess
    self._preprocess = preprocess

pipe

pipe[B](f) -> B

f(self): applies a curried combinator such as catch_tag or transform_response.

ParameterTypeDescription
fCallable[[HttpClientService[E, R]], B]

Returns B

def pipe[B](self, f: Callable[[HttpClientService[E, R]], B], /) -> B:
    """``f(self)``: applies a curried combinator such as
    ``catch_tag`` or ``transform_response``."""
    return f(self)

execute

execute(request) -> Effect[HttpClientResponse, E, R]

Sends request through preprocess and postprocess and succeeds with the response, whatever its status (filter it with filter_status_ok). Fails with E (HttpClientError for the HttpClient service) when the request cannot be built or sent.

ParameterTypeDescription
requestHttpClientRequest

Returns Effect[HttpClientResponse, E, R]

def execute(self, request: HttpClientRequest) -> Effect[HttpClientResponse, E, R]:
    """Sends ``request`` through ``preprocess`` and ``postprocess``
    and succeeds with the response, whatever its status (filter it with
    ``filter_status_ok``). Fails with ``E`` (``HttpClientError`` for the
    ``HttpClient`` service) when the request cannot be built or sent."""
    return self._postprocess(self._preprocess(request))

get

get(url, **options) -> Effect[HttpClientResponse, E, R]

execute of a GET request to url, built with options (headers, URL params, body, ...).

ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, E, R]

def get(
    self, url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, E, R]:
    """``execute`` of a ``GET`` request to ``url``, built with
    ``options`` (headers, URL params, body, ...)."""
    return self.execute(_request.get(url, **options))

post

post(url, **options) -> Effect[HttpClientResponse, E, R]

execute of a POST request to url, built with options (headers, URL params, body, ...).

ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, E, R]

def post(
    self, url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, E, R]:
    """``execute`` of a ``POST`` request to ``url``, built with
    ``options`` (headers, URL params, body, ...)."""
    return self.execute(_request.post(url, **options))

put

put(url, **options) -> Effect[HttpClientResponse, E, R]

execute of a PUT request to url, built with options (headers, URL params, body, ...).

ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, E, R]

def put(
    self, url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, E, R]:
    """``execute`` of a ``PUT`` request to ``url``, built with
    ``options`` (headers, URL params, body, ...)."""
    return self.execute(_request.put(url, **options))

patch

patch(url, **options) -> Effect[HttpClientResponse, E, R]

execute of a PATCH request to url, built with options (headers, URL params, body, ...).

ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, E, R]

def patch(
    self, url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, E, R]:
    """``execute`` of a ``PATCH`` request to ``url``, built with
    ``options`` (headers, URL params, body, ...)."""
    return self.execute(_request.patch(url, **options))

delete

delete(url, **options) -> Effect[HttpClientResponse, E, R]

execute of a DELETE request to url, built with options (headers, URL params, body, ...).

ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, E, R]

def delete(
    self, url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, E, R]:
    """``execute`` of a ``DELETE`` request to ``url``, built with
    ``options`` (headers, URL params, body, ...)."""
    return self.execute(_request.delete(url, **options))
head(url, **options) -> Effect[HttpClientResponse, E, R]

execute of a HEAD request to url, built with options (headers, URL params, body, ...).

ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, E, R]

def head(
    self, url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, E, R]:
    """``execute`` of a ``HEAD`` request to ``url``, built with
    ``options`` (headers, URL params, body, ...)."""
    return self.execute(_request.head(url, **options))

options

options(url, **options) -> Effect[HttpClientResponse, E, R]

execute of a OPTIONS request to url, built with options (headers, URL params, body, ...).

ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, E, R]

def options(
    self, url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, E, R]:
    """``execute`` of a ``OPTIONS`` request to ``url``, built with
    ``options`` (headers, URL params, body, ...)."""
    return self.execute(_request.options(url, **options))

query

query(url, **options) -> Effect[HttpClientResponse, E, R]

execute of a QUERY request to url, built with options (headers, URL params, body, ...).

ParameterTypeDescription
urlUrlInput
optionsUnpack[RequestOptions] = {}

Returns Effect[HttpClientResponse, E, R]

def query(
    self, url: UrlInput, **options: Unpack[RequestOptions]
) -> Effect[HttpClientResponse, E, R]:
    """``execute`` of a ``QUERY`` request to ``url``, built with
    ``options`` (headers, URL params, body, ...)."""
    return self.execute(_request.query(url, **options))

transform

transform[E1 = Never, R1 = Never](f) -> HttpClientService[E | E1, R | R1]

Wrap sending each request: f(sending, request).

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

Returns HttpClientService[E | E1, R | R1]

def transform[E1 = Never, R1 = Never](
    self,
    f: Callable[
        [Effect[HttpClientResponse, E, R], HttpClientRequest],
        Effect[HttpClientResponse, E1, R1],
    ],
) -> HttpClientService[E | E1, R | R1]:
    """Wrap sending each request: ``f(sending, request)``."""
    post = self._postprocess
    return HttpClientService(
        lambda requests: requests.flat_map(lambda request: f(post(succeed(request)), request)),
        self._preprocess,
    )

filter_or_else

filter_or_else[E2 = Never, R2 = Never](predicate, or_else) -> HttpClientService[E | E2, R | R2]

This client, replacing each response that fails predicate with the effect or_else(response).

ParameterTypeDescription
predicateCallable[[HttpClientResponse], bool]
or_elseCallable[[HttpClientResponse], Effect[HttpClientResponse, E2, R2]]

Returns HttpClientService[E | E2, R | R2]

def filter_or_else[E2 = Never, R2 = Never](
    self,
    predicate: Callable[[HttpClientResponse], bool],
    or_else: Callable[[HttpClientResponse], Effect[HttpClientResponse, E2, R2]],
) -> HttpClientService[E | E2, R | R2]:
    """This client, replacing each response that fails
    ``predicate`` with the effect ``or_else(response)``."""
    return self._on_response(lambda eff: eff.filter_or_else(predicate, or_else))

filter_or_fail

filter_or_fail[E2](predicate, or_fail_with) -> HttpClientService[E | E2, R]

This client, failing with or_fail_with(response) for each response that fails predicate.

ParameterTypeDescription
predicateCallable[[HttpClientResponse], bool]
or_fail_withCallable[[HttpClientResponse], E2]

Returns HttpClientService[E | E2, R]

def filter_or_fail[E2](
    self,
    predicate: Callable[[HttpClientResponse], bool],
    or_fail_with: Callable[[HttpClientResponse], E2],
) -> HttpClientService[E | E2, R]:
    """This client, failing with ``or_fail_with(response)`` for each
    response that fails ``predicate``."""
    return self._on_response(lambda eff: eff.filter_or_fail(predicate, or_fail_with))

filter_status

filter_status(f) -> HttpClientService[E | HttpClientError, R]

Fail with a StatusCodeError unless f(status).

ParameterTypeDescription
fCallable[[int], bool]

Returns HttpClientService[E | HttpClientError, R]

def filter_status(self, f: Callable[[int], bool]) -> HttpClientService[E | HttpClientError, R]:
    """Fail with a ``StatusCodeError`` unless ``f(status)``."""
    check = _response.filter_status(f)
    return self._on_response(lambda eff: eff.flat_map(check))

filter_status_ok

filter_status_ok() -> HttpClientService[E | HttpClientError, R]

Fail with a StatusCodeError unless the status is 2xx.

Returns HttpClientService[E | HttpClientError, R]

def filter_status_ok(self) -> HttpClientService[E | HttpClientError, R]:
    """Fail with a ``StatusCodeError`` unless the status is 2xx."""
    return self._on_response(lambda eff: eff.flat_map(_response.filter_status_ok))

map_request

map_request(f) -> HttpClientService[E, R]

Change each request after the client's own preprocessing.

ParameterTypeDescription
fCallable[[HttpClientRequest], HttpClientRequest]

Returns HttpClientService[E, R]

def map_request(
    self, f: Callable[[HttpClientRequest], HttpClientRequest]
) -> HttpClientService[E, R]:
    """Change each request after the client's own preprocessing."""
    pre = self._preprocess
    return HttpClientService(self._postprocess, lambda request: pre(request).map(f))

map_request_effect

map_request_effect[E2 = Never, R2 = Never](f) -> HttpClientService[E | E2, R | R2]

Change each request with the effect f after the client's own preprocessing; f's failure fails the request.

ParameterTypeDescription
fCallable[[HttpClientRequest], Effect[HttpClientRequest, E2, R2]]

Returns HttpClientService[E | E2, R | R2]

def map_request_effect[E2 = Never, R2 = Never](
    self, f: Callable[[HttpClientRequest], Effect[HttpClientRequest, E2, R2]]
) -> HttpClientService[E | E2, R | R2]:
    """Change each request with the effect ``f`` after the client's
    own preprocessing; ``f``'s failure fails the request."""
    pre = self._preprocess
    post: Any = self._postprocess
    return HttpClientService(post, lambda request: pre(request).flat_map(f))

map_request_input

map_request_input(f) -> HttpClientService[E, R]

Change each request before the client's own preprocessing.

ParameterTypeDescription
fCallable[[HttpClientRequest], HttpClientRequest]

Returns HttpClientService[E, R]

def map_request_input(
    self, f: Callable[[HttpClientRequest], HttpClientRequest]
) -> HttpClientService[E, R]:
    """Change each request before the client's own preprocessing."""
    pre = self._preprocess
    return HttpClientService(self._postprocess, lambda request: pre(f(request)))

map_request_input_effect

map_request_input_effect[E2 = Never, R2 = Never](f) -> HttpClientService[E | E2, R | R2]

Change each request with the effect f before the client's own preprocessing; f's failure fails the request.

ParameterTypeDescription
fCallable[[HttpClientRequest], Effect[HttpClientRequest, E2, R2]]

Returns HttpClientService[E | E2, R | R2]

def map_request_input_effect[E2 = Never, R2 = Never](
    self, f: Callable[[HttpClientRequest], Effect[HttpClientRequest, E2, R2]]
) -> HttpClientService[E | E2, R | R2]:
    """Change each request with the effect ``f`` before the
    client's own preprocessing; ``f``'s failure fails the request."""
    pre = self._preprocess
    post: Any = self._postprocess
    return HttpClientService(post, lambda request: f(request).flat_map(pre))

tap_request

tap_request[E2 = Never, R2 = Never](f) -> HttpClientService[E | E2, R | R2]

Run f on each preprocessed request before it is sent, keeping the request; f's failure fails the request.

ParameterTypeDescription
fCallable[[HttpClientRequest], Effect[object, E2, R2]]

Returns HttpClientService[E | E2, R | R2]

def tap_request[E2 = Never, R2 = Never](
    self, f: Callable[[HttpClientRequest], Effect[object, E2, R2]]
) -> HttpClientService[E | E2, R | R2]:
    """Run ``f`` on each preprocessed request before it is sent,
    keeping the request; ``f``'s failure fails the request."""
    pre = self._preprocess
    post: Any = self._postprocess
    return HttpClientService(post, lambda request: pre(request).tap(f))

tap

tap[E2 = Never, R2 = Never](f) -> HttpClientService[E | E2, R | R2]

Run f on each response, keeping the response; f's failure fails the request.

ParameterTypeDescription
fCallable[[HttpClientResponse], Effect[object, E2, R2]]

Returns HttpClientService[E | E2, R | R2]

def tap[E2 = Never, R2 = Never](
    self, f: Callable[[HttpClientResponse], Effect[object, E2, R2]]
) -> HttpClientService[E | E2, R | R2]:
    """Run ``f`` on each response, keeping the response; ``f``'s
    failure fails the request."""
    return self._on_response(lambda eff: eff.tap(f))

tap_error

tap_error[E2 = Never, R2 = Never](f) -> HttpClientService[E | E2, R | R2]

Run f on each typed failure, keeping the failure; f's own failure replaces it.

ParameterTypeDescription
fCallable[[E], Effect[object, E2, R2]]

Returns HttpClientService[E | E2, R | R2]

def tap_error[E2 = Never, R2 = Never](
    self, f: Callable[[E], Effect[object, E2, R2]]
) -> HttpClientService[E | E2, R | R2]:
    """Run ``f`` on each typed failure, keeping the failure;
    ``f``'s own failure replaces it."""
    return self._on_response(lambda eff: eff.tap_error(f))

catch_all

catch_all[E2 = Never, R2 = Never](f) -> HttpClientService[E2, R | R2]

Recover from every typed failure with f.

ParameterTypeDescription
fCallable[[E], Effect[HttpClientResponse, E2, R2]]

Returns HttpClientService[E2, R | R2]

def catch_all[E2 = Never, R2 = Never](
    self, f: Callable[[E], Effect[HttpClientResponse, E2, R2]]
) -> HttpClientService[E2, R | R2]:
    """Recover from every typed failure with ``f``."""
    return self._on_response(lambda eff: eff.catch_all(f))

retry

retry[EE = Never, RR = Never](policy: Schedule[object, E, EE, RR], /) -> HttpClientService[E | EE, R | RR]
retry[EE = Never, RR = Never](*, schedule: Schedule[object, E, EE, RR] | None = None, times: int | None = None, while_: Callable[[E], bool | Effect[bool, EE, RR]] | None = None, until: Callable[[E], bool | Effect[bool, EE, RR]] | None = None) -> HttpClientService[E | EE, R | RR]

Retry sending on typed failure (Effect.retry).

ParameterTypeDescription
policy= None
schedule= None
times= None
while_= None
until= None
@overload
def retry[EE = Never, RR = Never](
    self, policy: Schedule[object, E, EE, RR], /
) -> HttpClientService[E | EE, R | RR]: ...
@overload
def retry[EE = Never, RR = Never](
    self,
    /,
    *,
    schedule: Schedule[object, E, EE, RR] | None = None,
    times: int | None = None,
    while_: Callable[[E], bool | Effect[bool, EE, RR]] | None = None,
    until: Callable[[E], bool | Effect[bool, EE, RR]] | None = None,
) -> HttpClientService[E | EE, R | RR]: ...
def retry(
    self,
    policy: Schedule[Any, Any, Any, Any] | None = None,
    /,
    *,
    schedule: Schedule[Any, Any, Any, Any] | None = None,
    times: int | None = None,
    while_: Callable[[Any], Any] | None = None,
    until: Callable[[Any], Any] | None = None,
) -> HttpClientService[Any, Any]:
    """Retry sending on typed failure (``Effect.retry``)."""
    if policy is not None:
        return self._on_response(lambda eff: eff.retry(policy))
    return self._on_response(
        lambda eff: eff.retry(schedule=schedule, times=times, while_=while_, until=until)
    )

retry_transient

retry_transient[ES = Never, RS = Never](schedule: Schedule[object, Any, ES, RS], /) -> HttpClientService[E | ES, R | RS]
retry_transient[ES = Never, RS = Never](*, retry_on: RetryOn = 'errors-and-responses', while_: Callable[[E | ES], bool] | None = None, schedule: Schedule[object, Any, ES, RS] | None = None, times: int | None = None) -> HttpClientService[E | ES, R | RS]

Retry transient failures (timeouts, transport errors, 408, 429, 500, 502, 503 and 504 statuses) and repeat on transient responses, waiting at least each response's Retry-After. retry_on limits it to errors or to responses; while_ adds errors to retry.

ParameterTypeDescription
policy= None
retry_on= 'errors-and-responses'
while_= None
schedule= None
times= None
@overload
def retry_transient[ES = Never, RS = Never](
    self, schedule: Schedule[object, Any, ES, RS], /
) -> HttpClientService[E | ES, R | RS]: ...
@overload
def retry_transient[ES = Never, RS = Never](
    self,
    /,
    *,
    retry_on: RetryOn = "errors-and-responses",
    while_: Callable[[E | ES], bool] | None = None,
    schedule: Schedule[object, Any, ES, RS] | None = None,
    times: int | None = None,
) -> HttpClientService[E | ES, R | RS]: ...
def retry_transient(
    self,
    policy: Schedule[Any, Any, Any, Any] | None = None,
    /,
    *,
    retry_on: RetryOn = "errors-and-responses",
    while_: Callable[[Any], bool] | None = None,
    schedule: Schedule[Any, Any, Any, Any] | None = None,
    times: int | None = None,
) -> HttpClientService[Any, Any]:
    """Retry transient failures (timeouts, transport errors, 408, 429,
    500, 502, 503 and 504 statuses) and repeat on transient responses, waiting at least
    each response's ``Retry-After``. ``retry_on`` limits it to errors
    or to responses; ``while_`` adds errors to retry."""
    from pyfect.http.client._retry import retry_transient

    return self._on_response(
        retry_transient(
            policy if policy is not None else schedule,
            retry_on="errors-and-responses" if policy is not None else retry_on,
            while_=None if policy is not None else while_,
            times=None if policy is not None else times,
        )
    )

timeout

timeout(duration) -> HttpClientService[E | HttpClientError, R]

Fail a request that gets no response within duration with an HttpClientError whose reason is a TransportError caused by a TimeoutException (which retry_transient retries). The request is interrupted, so it is aborted unless with_scope holds it. Applied before retry_transient each attempt gets its own budget; after it, the budget bounds the whole retry loop.

ParameterTypeDescription
durationDurationInput

Returns HttpClientService[E | HttpClientError, R]

def timeout(self, duration: DurationInput) -> HttpClientService[E | HttpClientError, R]:
    """Fail a request that gets no response within ``duration`` with an
    ``HttpClientError`` whose reason is a ``TransportError`` caused by a
    ``TimeoutException`` (which ``retry_transient`` retries). The request
    is interrupted, so it is aborted unless ``with_scope`` holds it.
    Applied before ``retry_transient`` each attempt gets its own budget;
    after it, the budget bounds the whole retry loop."""
    from pyfect.http.client._timeout import timeout

    return self.transform(timeout(duration))

with_rate_limiter

with_rate_limiter(*, limiter, window, limit, key, algorithm='fixed-window', tokens=1, times=None, response_headers=None, disable_response_inspection=False, disable_adaptive_learning=False) -> HttpClientService[E | RateLimiterError, R]

Send each request through limiter: limit requests (each costing tokens, at least 1) per window for each key, waiting when over it. The rate limit headers of responses update the limit and window, and a reported remaining budget of zero holds requests until its reset. A 429 response (or HttpClientError wrapping one) is retried through the limiter after its Retry-After, times times at most (unbounded by default), and teaches the limiter's adaptive pacing for the key. disable_response_inspection ignores the headers (429s are still retried; times=0 stops that); disable_adaptive_learning only stops the pacing.

ParameterTypeDescription
limiterRateLimiterService
windowDurationInput
limitfloat
keystr | Callable[[HttpClientRequest], str]
algorithmAlgorithm = 'fixed-window'
tokensfloat | Callable[[HttpClientRequest], float] = 1
timesint | None = None
response_headersRateLimitHeaders | None = None
disable_response_inspectionbool = False
disable_adaptive_learningbool = False

Returns HttpClientService[E | RateLimiterError, R]

def with_rate_limiter(
    self,
    *,
    limiter: RateLimiterService,
    window: DurationInput,
    limit: float,
    key: str | Callable[[HttpClientRequest], str],
    algorithm: Algorithm = "fixed-window",
    tokens: float | Callable[[HttpClientRequest], float] = 1,
    times: int | None = None,
    response_headers: RateLimitHeaders | None = None,
    disable_response_inspection: bool = False,
    disable_adaptive_learning: bool = False,
) -> HttpClientService[E | RateLimiterError, R]:
    """Send each request through ``limiter``: ``limit`` requests (each
    costing ``tokens``, at least 1) per ``window`` for each ``key``,
    waiting when over it. The rate limit headers of responses update the
    limit and window, and a reported remaining budget of zero holds
    requests until its reset. A ``429`` response (or ``HttpClientError``
    wrapping one) is retried through the limiter after its
    ``Retry-After``, ``times`` times at most (unbounded by default), and
    teaches the limiter's adaptive pacing for the key.
    ``disable_response_inspection`` ignores the headers (429s are still
    retried; ``times=0`` stops that); ``disable_adaptive_learning`` only
    stops the pacing."""
    from pyfect.http.client._rate_limit import RateLimitOptions, with_rate_limiter

    options = RateLimitOptions(
        limiter=limiter,
        window=window,
        limit=limit,
        key=key,
        algorithm=algorithm,
        tokens=tokens,
        times=times,
        response_headers={} if response_headers is None else response_headers,
        disable_response_inspection=disable_response_inspection,
        disable_adaptive_learning=disable_adaptive_learning,
    )
    return self.transform(with_rate_limiter(options))

with_circuit_breaker

with_circuit_breaker[R2 = Never](*, breaker, key=None, classify=None) -> HttpClientService[E | CircuitBreakerError, R | R2]

Send each request through breaker's circuit for key (default the request's origin, or its raw URL when it has none), each outcome counted by classify (default circuit_breaker_classifier). Apply it after with_rate_limiter and retry_transient so the breaker sees their final outcome; retry_transient never retries a CircuitBreakerError.

ParameterTypeDescription
breakerCircuitBreakerService
keystr | Callable[[HttpClientRequest], str] | None = None
classifyClassifier[HttpClientResponse, E, R2] | None = None

Returns HttpClientService[E | CircuitBreakerError, R | R2]

def with_circuit_breaker[R2 = Never](
    self,
    *,
    breaker: CircuitBreakerService,
    key: str | Callable[[HttpClientRequest], str] | None = None,
    classify: Classifier[HttpClientResponse, E, R2] | None = None,
) -> HttpClientService[E | CircuitBreakerError, R | R2]:
    """Send each request through ``breaker``'s circuit for ``key``
    (default the request's origin, or its raw URL when it has none),
    each outcome counted by ``classify`` (default
    ``circuit_breaker_classifier``). Apply it after ``with_rate_limiter``
    and ``retry_transient`` so the breaker sees their final outcome;
    ``retry_transient`` never retries a ``CircuitBreakerError``."""
    from pyfect.http.client._circuit_breaker import with_circuit_breaker

    return self.transform(with_circuit_breaker(breaker, key, classify))

with_cookies_ref

with_cookies_ref(ref) -> HttpClientService[E, R]

Keep the cookies each response sets in ref (cookies.merge_into_array for the response URL) and send each request the ones cookies.to_request_cookie_header selects for its final URL, after later changes such as prepend_url; with follow_redirects applied after it, on every hop. Expiry reads the Clock.

ParameterTypeDescription
refRef[tuple[Cookie, ...]]

Returns HttpClientService[E, R]

def with_cookies_ref(self, ref: Ref[tuple[Cookie, ...]]) -> HttpClientService[E, R]:
    """Keep the cookies each response sets in ``ref``
    (``cookies.merge_into_array`` for the response URL) and send each
    request the ones ``cookies.to_request_cookie_header`` selects for its
    final URL, after later changes such as ``prepend_url``; with
    ``follow_redirects`` applied after it, on every hop. Expiry reads the
    ``Clock``."""
    from pyfect.clock import current_time_millis
    from pyfect.http.cookies import merge_into_array, to_request_cookie_header

    pre = self._preprocess
    post = self._postprocess

    def add_cookies(request: HttpClientRequest) -> Effect[HttpClientRequest]:
        def with_header(jar: tuple[Cookie, ...], now: float) -> Effect[HttpClientRequest]:
            header = to_request_cookie_header(jar, request.url, now)
            if header is None:
                return succeed(request)
            return succeed(request.set_header("cookie", header))

        return ref.get().zip_with(current_time_millis(), with_header).flatten()

    def store(
        requests: Effect[HttpClientRequest, Any, Any],
    ) -> Effect[HttpClientResponse, E, R]:
        return post(requests.flat_map(add_cookies)).tap(
            lambda response: current_time_millis().flat_map(
                lambda now: ref.update(
                    lambda jar: merge_into_array(jar, response.url, response.cookies, now)
                )
            )
        )

    return HttpClientService(store, pre)

with_scope

with_scope() -> HttpClientService[E, R | Scope]

Attach every request the client sends to the current Scope, which aborts them when it closes (Effect's withScope). Ownership follows the execution, not the request: every redirect hop, retry and request rewritten by middleware, whichever side of follow_redirects, with_cookies_ref or retry_transient this is on. Running one response effect concurrently under different scopes gives each run its own owner. A request sent after the scope closed is aborted before the transport starts it, and one interrupted before its response is aborted at once; a response's body stays readable until the scope closes. Requests middleware sends with another client while this one executes are attached too; the innermost with_scope owns them.

Returns HttpClientService[E, R | Scope]

def with_scope(self) -> HttpClientService[E, R | Scope]:
    """Attach every request the client sends to the current ``Scope``, which aborts them
    when it closes (Effect's ``withScope``). Ownership follows the execution, not the
    request: every redirect hop, retry and request rewritten by middleware, whichever side
    of ``follow_redirects``, ``with_cookies_ref`` or ``retry_transient`` this is on.
    Running one response effect concurrently under different scopes gives each run its
    own owner. A request sent after the scope closed is aborted before the transport
    starts it, and one interrupted before its response is aborted at once; a response's
    body stays readable until the scope closes. Requests middleware sends with another
    client while this one executes are attached too; the innermost ``with_scope`` owns
    them."""
    from pyfect.http.client._make import scoped

    return self._on_response(scoped)

follow_redirects

follow_redirects(max_redirects=10) -> HttpClientService[E, R]

Follow 3xx responses with a Location, up to max_redirects hops. 303 (and 301 / 302 after a POST) switch to GET without a body; a hop to another origin drops the credentials headers.

ParameterTypeDescription
max_redirectsint = 10

Returns HttpClientService[E, R]

def follow_redirects(self, max_redirects: int = 10) -> HttpClientService[E, R]:
    """Follow 3xx responses with a ``Location``, up to ``max_redirects``
    hops. 303 (and 301 / 302 after a ``POST``) switch to ``GET`` without
    a body; a hop to another origin drops the credentials headers."""
    from pyfect.http.client._redirects import follow_redirects

    return follow_redirects(self, max_redirects)