:py:mod:`net.http`
==================

.. py:module:: net.http

.. autoapi-nested-parse::

   HTTP client with retry and authentication support.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   net.http._Fileobj
   net.http.BaseURL
   net.http.HTTPSession



Functions
~~~~~~~~~

.. autoapisummary::

   net.http.get_filename



Attributes
~~~~~~~~~~

.. autoapisummary::

   net.http.logger
   net.http.HTTP_OK


.. py:class:: _Fileobj


   Bases: :py:obj:`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:
               ...

   .. py:method:: write(b: bytes, /) -> object

      Write bytes to file.

      :param b: bytes to write



.. py:data:: logger

   

.. py:data:: HTTP_OK
   :value: 200

   

.. py:function:: get_filename(content_disposition: str) -> str | None

   Return a filename from an HTTP Content-Disposition header.

   :param content_disposition: a Content-Disposition header string
   :return: the filename or None


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


   Bases: :py:obj:`e3.error.E3Error`

   Exception raised for HTTP operations errors.

   .. py:property:: status
      :type: int | None

      Return the HTTP status code from the response.



.. py:class:: BaseURL(url: str)


   Represent a base url object along with its authentication.

   The root class BaseURL does not use authentication

   .. py:method:: get_auth() -> tuple[str, str] | requests.auth.AuthBase | None

      Return auth requests parameter.

      :return: authentication associated with the url


   .. py:method:: __str__() -> str

      Return string representation of base URL.



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


   HTTP session manager with failover support for multiple base URLs.

   .. py:attribute:: CHUNK_SIZE

      

   .. py:attribute:: DEFAULT_TIMEOUT
      :value: (60, 60)

      

   .. py:method:: __enter__() -> typing_extensions.Self

      Enter context manager for HTTP session.


   .. py:method:: __exit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: types.TracebackType | None) -> None

      Exit context manager.

      :param exc_type: exception type
      :param exc_val: exception value
      :param exc_tb: exception traceback


   .. py:method:: set_max_retries(base_url: str | None = None, connect: int | None = None, read: int | None = None, redirect: int | None = None) -> None

      Retry configuration.

      :param base_url: base url for the HTTPAdapter
      :param connect: how many connection-related errors to retry on
      :param read: how many times to retry on read errors
      :param redirect: how many redirects to perform. Limit this to avoid
          infinite redirect loops.


   .. py:method:: 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

      :param method: HTTP method
      :param url: URL to request
      :param 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.


   .. py:method:: 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.

      :param url: the url to GET
      :param dest: local directory path for the downloaded file. If
          None, a file object must be specified.
      :param filename: the local path whether to store this resource, by
          default use the name provided  in the ``Content-Disposition``
          header.
      :param 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.
      :param 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.
      :param exception_on_error: if True raises an exception in case download
          fails instead of returning None.
      :param kwargs: additional parameters for the request
      :return: 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