net.http
========

.. py:module:: net.http


Attributes
----------

.. autoapisummary::

   net.http.logger


Classes
-------

.. autoapisummary::

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


Functions
---------

.. autoapisummary::

   net.http.get_filename


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

.. 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[T](Protocol):
           def meth(self) -> T:
               ...


   .. py:method:: write(__b: bytes) -> object


.. py:data:: logger

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

   Return a filename from a HTTP Content-Disposition header.

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


.. py:class:: HTTPError(msg: str, status: int | None = None)

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


   .. py:attribute:: status
      :value: None



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

   Represent a base url object along with its authentication.

   The root class BaseURL does not use authentication


   .. py:attribute:: url


   .. 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


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

   .. py:attribute:: CHUNK_SIZE
      :value: 1048576



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



   .. py:attribute:: session


   .. py:attribute:: last_base_url
      :type:  BaseURL | None
      :value: None



   .. py:method:: __enter__() -> HTTPSession


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


   .. 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
      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 | 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



