net.http

HTTP client with retry and authentication support.

Module Contents

Classes

_Fileobj

Base class for protocol classes.

BaseURL

Represent a base url object along with its authentication.

HTTPSession

HTTP session manager with failover support for multiple base URLs.

Functions

get_filename(→ str | None)

Return a filename from an HTTP Content-Disposition header.

Attributes

logger

HTTP_OK

class net.http._Fileobj

Bases: Protocol

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...
write(b: bytes, /) → object

Write bytes to file.

Parameters:

b – bytes to write

net.http.logger
net.http.HTTP_OK = 200
net.http.get_filename(content_disposition: str) → str | None

Return a filename from an HTTP Content-Disposition header.

Parameters:

content_disposition – a Content-Disposition header string

Returns:

the filename or None

exception net.http.HTTPError(msg: str, response: requests.models.Response | None = None)

Bases: e3.error.E3Error

Exception raised for HTTP operations errors.

property status: int | None

Return the HTTP status code from the response.

class net.http.BaseURL(url: str)

Represent a base url object along with its authentication.

The root class BaseURL does not use authentication

get_auth() → tuple[str, str] | requests.auth.AuthBase | None

Return auth requests parameter.

Returns:

authentication associated with the url

__str__() → str

Return string representation of base URL.

class net.http.HTTPSession(base_urls: list[str | BaseURL] | None = None)

HTTP session manager with failover support for multiple base URLs.

CHUNK_SIZE
DEFAULT_TIMEOUT = (60, 60)
__enter__() → typing_extensions.Self

Enter context manager for HTTP session.

__exit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: types.TracebackType | None) → None

Exit context manager.

Parameters:

  • exc_type – exception type

  • exc_val – exception value

  • exc_tb – exception traceback

set_max_retries(base_url: str | None = None, connect: int | None = None, read: int | None = None, redirect: int | None = None) → None

Retry configuration.

Parameters:

  • base_url – base url for the HTTPAdapter

  • connect – how many connection-related errors to retry on

  • read – how many times to retry on read errors

  • redirect – how many redirects to perform. Limit this to avoid infinite redirect loops.

request(method: str, url: str, data_streams: dict[str, Any] | None = None, **kwargs: Any) → requests.models.Response

Send a request.

See requests Session.request function.

The main difference is that several servers are tried in case base_urls have been set.

For POST requests an additional parameter is supported: data_streams. data_streams is a dict associating a string key to either another string, a dict, a list or a file descriptor. String value are passed without any modifications. lists and dicts are automatically encoded

Parameters:

  • method – HTTP method

  • url – URL to request

  • data_streams – dict of data streams for POST requests

in JSON. Finally file objects are streamed during the POST request (no complete read is done into memory to fetch file content). When using data_streams parameter, data parameter will be ignored and headers one modified.

download_file(url: str, dest: str | pathlib.Path | None = None, filename: str | None = None, fileobj: _Fileobj | None = None, validate: collections.abc.Callable[[str], bool] | None = None, exception_on_error: bool = False, **kwargs: Any) → str | None

Download a file.

Parameters:

  • url – the url to GET

  • dest – local directory path for the downloaded file. If None, a file object must be specified.

  • filename – the local path whether to store this resource, by default use the name provided in the Content-Disposition header.

  • fileobj – if specified, the downloaded file is written to this file object instead of opening a file. The file object must be opened in binary mode.

  • validate – function to call once the download is complete for detecting invalid / corrupted download. Takes the local path as parameter and returns a boolean. The function is not called when a file object is specified.

  • exception_on_error – if True raises an exception in case download fails instead of returning None.

  • kwargs – additional parameters for the request

Returns:

the name of the file, or None if there is an error or a file object is passed and the filename could not be deduced from the request.

Raises:

ValueError – if neither dest nor fileobj is provided