Skip to main content
Version: Next

HttpClient

Base class for synchronous HTTP clients used by ApifyClient.

Concrete clients inherit its request preparation, retry, and error handling, and implement the transport, error-classification, and lifecycle hooks. Only send_request has to be implemented, the other hooks have defaults. Replacing call itself also remains supported, and then the transport and retry-classification hooks are bypassed. Helper methods from HttpClientBase remain available for request preparation, URL building, and parameter parsing.

The client's default headers from self._headers have to go out with every request, otherwise the Authorization header never reaches the API. The inherited call merges them into the per-request headers through _prepare_request_call, so only a client that replaces call has to do it itself.

Hierarchy

Index

Methods

Methods

__enter__

  • __enter__(): Self

  • Return this client and close it when the context exits.

    Returns Self

__exit__

  • __exit__(exc_type, exc_value, traceback): None

  • Close resources owned by the HTTP client.

    Parameters

    • exc_type: type[BaseException] | None
    • exc_value: BaseException | None
    • traceback: TracebackType | None

    Returns None

__init__

  • __init__(*, token, timeout_short, timeout_medium, timeout_long, timeout_max, max_retries, min_delay_between_retries, statistics, headers, http_compressor): None

  • Initialize the HTTP client base.

    Parameters

    • optionalkeyword-onlytoken: str | None = None

      Apify API token for authentication.

    • optionalkeyword-onlytimeout_short: timedelta = DEFAULT_TIMEOUT_SHORT

      Default timeout for short-duration API operations (simple CRUD operations, ...).

    • optionalkeyword-onlytimeout_medium: timedelta = DEFAULT_TIMEOUT_MEDIUM

      Default timeout for medium-duration API operations (batch operations, listing, ...).

    • optionalkeyword-onlytimeout_long: timedelta = DEFAULT_TIMEOUT_LONG

      Default timeout for long-duration API operations (long-polling, streaming, ...).

    • optionalkeyword-onlytimeout_max: timedelta = DEFAULT_TIMEOUT_MAX

      Maximum timeout cap for any single request attempt, including tier and per-call timeouts.

    • optionalkeyword-onlymax_retries: int = DEFAULT_MAX_RETRIES

      Maximum number of retries for failed requests.

    • optionalkeyword-onlymin_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES

      Minimum delay between retries.

    • optionalkeyword-onlystatistics: ClientStatistics | None = None

      Statistics tracker for API calls. Created automatically if not provided.

    • optionalkeyword-onlyheaders: dict[str, str] | None = None

      Additional HTTP headers to include in all requests.

    • optionalkeyword-onlyhttp_compressor: HttpCompressor | None = None

      Compressor used to compress request bodies. Defaults to GzipHttpCompressor.

    Returns None

call

  • call(*, method, url, headers, params, data, json, stream, timeout): HttpResponse

  • Make an HTTP request with automatic retry and exponential backoff.

    Parameters

    • keyword-onlymethod: str

      HTTP method (GET, POST, PUT, DELETE, etc.).

    • keyword-onlyurl: str

      Full URL to make the request to.

    • optionalkeyword-onlyheaders: dict[str, str] | None = None

      Additional headers to include.

    • optionalkeyword-onlyparams: dict[str, Any] | None = None

      Query parameters to append to the URL.

    • optionalkeyword-onlydata: ((str | bytes) | bytearray) | None = None

      Raw request body data. Cannot be used together with json.

    • optionalkeyword-onlyjson: JsonSerializable | None = None

      JSON-serializable data for the request body. Cannot be used together with data.

    • optionalkeyword-onlystream: bool | None = None

      Whether to stream the response body.

    • optionalkeyword-onlytimeout: Timeout = 'medium'

      Timeout for the API HTTP request. Use short, medium, or long tier literals for preconfigured timeouts. A timedelta overrides it for this call (capped at timeout_max), and no_timeout disables the timeout entirely.

    Returns HttpResponse

    The HTTP response object.

close

  • close(): None

  • Close resources owned by the HTTP client.

    Transports that own a connection pool or a session override it. The default does nothing.

    Returns None

is_retryable_transport_error

  • is_retryable_transport_error(exc): bool

  • Return whether an underlying HTTP-library exception is retryable.

    The default classifies nothing as retryable, so a transport that doesn't override it gives up on the first connection failure. Every transport adapter should map its own transient error types here.

    Parameters

    • exc: Exception

    Returns bool

is_timeout_error

  • is_timeout_error(exc): bool

  • Return whether an exception represents a transport timeout.

    Recognizes Python's own TimeoutError. Transport adapters extend it with the timeout types their HTTP library defines.

    Parameters

    • exc: Exception

    Returns bool

send_request

  • send_request(*, method, url, headers, content, timeout, stream): HttpResponse

  • Send one request through the underlying HTTP library.

    Required by the inherited call, so a transport adapter must implement it. Overriding call itself bypasses it entirely. Let the HTTP library's exceptions propagate unwrapped: call classifies them through is_retryable_transport_error and is_timeout_error.

    Parameters

    • keyword-onlymethod: str

      HTTP method (GET, POST, PUT, DELETE, etc.).

    • keyword-onlyurl: str

      Full request URL, with the query parameters already encoded into it.

    • keyword-onlyheaders: dict[str, str]

      Final request headers, with the client's default headers already merged in.

    • keyword-onlycontent: bytes | None

      Request body, already serialized and compressed, or None for a request without a body.

    • keyword-onlytimeout: float | None

      Timeout for this attempt in seconds, or None for no timeout at all.

    • keyword-onlystream: bool

      Whether to return the response with the body unread, so the caller can stream it.

    Returns HttpResponse

    The HTTP response object.

set_default_authorization

  • set_default_authorization(token): None

  • Set the Authorization header from the token, unless an authorization header is already configured.

    Parameters

    • token: str

      The Apify API token to set as the Bearer authorization.

    Returns None

Page Options