:mod:`arequests` -- asynchronous HTTP requests
==============================================

.. module:: arequests
   :synopsis: asynchronous HTTP requests

The module is based on the `urequests module
<https://github.com/micropython/micropython-lib/blob/master/urequests/urequests.py>`_ from the micropython-lib.

Example::

    import arequests

    # All the HTTP communication is done behind the scenes
    # The method returns the Response object for further processing
    resp = await arequests.get('https://google.com')

    # Read the response
    content = await resp.content()

    # Don't forget to close the underlying stream!
    # content(), text(), json() do that, but read() does not
    await resp.close()


Functions
---------

.. function:: request(method, url, data=None, json=None, headers={}, stream=None, ssl=None)

   Makes a HTTP request with the *method* verb to the *url* location.
   If a body needs to be sent, it may be passed in *data* (arbitrary string or bytes object),
   or as *json*. In the latter case, the *Content-Type* header is automatically set
   to *application/json* and the *data* value (if not None) is ignored. Protocol (plain or SSL)
   is deduced automatically from the url scheme.

   * *headers* - additional request headers (dict).
   * *stream* - read data from a stream and send it as the body of the HTTP request. Is overridden by *json* and *data* parameters.
   * *ssl* - additional parameters for the SSL connection (this parameter **does not** instruct the function to choose between a plain and an encrypted request). Accepted values are:

       + ref. the keyword arguments of the :meth:`~ssl.wrap_socket()` method.
       + *max_fragment* (only for axtls): number (from 4096 to 16384). Please note that the TLS server can ignore this setting (see RFC. 6066).
       + *record_size* (only for axtls): if true, send the *max_fragment* parameter as a Record Size Limit Extension (see RFC. 8449), otherwise (the default) send as a Maximum Fragment Length Extension (see. RFC. 6066).

   Returns a Response object, which is used to receive the reply to the HTTP request.
   Please note that axtls implementation does not support the *do_handshake* SSL parameter and forces it to *True*.

.. function:: head(url, \*\*kw)

   Makes `request()` with the *HEAD* verb.

.. function:: get(url, \*\*kw)

   Makes `request()` with the *GET* verb.

.. function:: post(url, \*\*kw)

   Makes `request()` with the *POST* verb.

.. function:: put(url, \*\*kw)

   Makes `request()` with the *PUT* verb.

.. function:: patch(url, \*\*kw)

   Makes `request()` with the *PATCH* verb.

.. function:: delete(url, \*\*kw)

   Makes `request()` with the *DELETE* verb.

Methods
-------

.. method:: Response.__len__()

   Returns the length of the response as indicated by the *Content-Length* header.
   May be zero or None of the header is missing in the response.

.. method:: Response.close()

   Close the underlying socket. This is a coroutine.

.. method:: Response.read(n=-1)

   Read at most *n* bytes from the stream. If *n* is not positive,
   reads the number of bytes, indicated by the *Content-Length* header.
   If that one is missing, tries to read all available bytes from the response stream.
   `Response.content()`, `Response.text()`, and `Response.json()`
   methods cannot be called after this method.
   This is a coroutine.

.. method:: Response.readinto(buffer)

   The same as `Response.read()`, but puts the data read into the *buffer*.
   The same remarks apply.

.. method:: Response.content()
            Response.text()
            Response.json()

   Reads all data (according to the *Content-Length* header) from the underlying stream.
   `content()` method returns bytes, `text()` returns a string (content is decoded as *utf-8*),
   `json()` tries to parse the content as a json document.
   All three methods are coroutines. The data is cached, the underlying stream is closed.
   Hence, the methods can be called repeatedly, the `read()` and `readinto()` methods
   cannot me called after one of these.