Skip to content

Latest commit

 

History

History
842 lines (508 loc) · 24.9 KB

client_reference.rst

File metadata and controls

842 lines (508 loc) · 24.9 KB

HTTP Client Reference

.. module:: aiohttp.client

Client Session

Client session is the recommended interface for making HTTP requests.

Session encapsulates connection pool (connector instance) and supports keepalives by default.

Usage example:

>>> import aiohttp
>>> session = aiohttp.ClientSession()
>>> resp = yield from session.get('http://python.org')
>>> resp
<ClientResponse(python.org/) [200]>
>>> data = yield from resp.read()
>>> session.close()
.. versionadded:: 0.15.2

The client session supports context manager protocol for self closing:

>>> with aiohttp.ClientSession() as session:
>>>     resp = yield from session.get('http://python.org')
>>>     yield from resp.release()
>>> session.closed
True
.. versionadded:: 0.17

Basic API

While we encourage :class:`ClientSession` usage we also provide simple coroutines for making HTTP requests.

Basic API is good for performing simple HTTP requests without keepaliving, cookies and complex connection stuff like properly configured SSL certification chaining.

.. coroutinefunction:: request(method, url, *, params=None, data=None, \
                       headers=None, cookies=None, files=None, auth=None, \
                       allow_redirects=True, max_redirects=10, \
                       encoding='utf-8', \
                       version=HttpVersion(major=1, minor=1), \
                       compress=None, chunked=None, expect100=False, \
                       connector=None, loop=None,\
                       read_until_eof=True, request_class=None,\
                       response_class=None)

   Perform an asynchronous http request. Return a response object
   (:class:`ClientResponse` or derived from).

   :param str method: HTTP method

   :param str url: Requested URL

   :param dict params: Parameters to be sent in the query
                       string of the new request (optional)

   :param data: Dictionary, bytes, or file-like object to
                send in the body of the request (optional)

   :param dict headers: HTTP Headers to send with
                        the request (optional)

   :param dict cookies: Cookies to send with the request (optional)

   :param aiohttp.helpers.BasicAuth auth: BasicAuth named tuple that represents
                                          HTTP Basic Authorization (optional)

   :param bool allow_redirects: If set to ``False``, do not follow redirects.
                                ``True`` by default (optional).

   :param aiohttp.protocol.HttpVersion version: Request http version (optional)

   :param bool compress: Set to ``True`` if request has to be compressed
                         with deflate encoding.
                         ``None`` by default (optional).

   :param int chunked: Set to chunk size for chunked transfer encoding.
                   ``None`` by default (optional).

   :param bool expect100: Expect 100-continue response from server.
                          ``False`` by default (optional).

   :param aiohttp.connector.BaseConnector connector: BaseConnector sub-class
      instance to support connection pooling.

   :param bool read_until_eof: Read response until EOF if response
                               does not have Content-Length header.
                               ``True`` by default (optional).

   :param request_class: Custom Request class implementation (optional)

   :param response_class: Custom Response class implementation (optional)

   :param loop: :ref:`event loop<asyncio-event-loop>`
                used for processing HTTP requests.
                If param is ``None``, :func:`asyncio.get_event_loop`
                is used for getting default event loop, but we strongly
                recommend to use explicit loops everywhere.
                (optional)

Usage:

>>> import aiohttp
>>> resp = yield from aiohttp.request('GET', 'http://python.org/')
>>> resp
<ClientResponse(python.org/) [200]>
>>> data = yield from resp.read()
.. coroutinefunction:: get(url, **kwargs)

   Perform a GET request.

   :param str url: Requested URL.

   :param \*\*kwargs: Optional arguments that :func:`request` takes.

   :return: :class:`ClientResponse` or derived from

.. coroutinefunction:: options(url, **kwargs)

   Perform a OPTIONS request.

   :param str url: Requested URL.

   :param \*\*kwargs: Optional arguments that :func:`request` takes.

   :return: :class:`ClientResponse` or derived from

.. coroutinefunction:: head(url, **kwargs)

   Perform a HEAD request.

   :param str url: Requested URL.

   :param \*\*kwargs: Optional arguments that :func:`request` takes.

   :return: :class:`ClientResponse` or derived from

.. coroutinefunction:: delete(url, **kwargs)

   Perform a DELETE request.

   :param str url: Requested URL.

   :param \*\*kwargs: Optional arguments that :func:`request` takes.

   :return: :class:`ClientResponse` or derived from

.. coroutinefunction:: post(url, *, data=None, **kwargs)

   Perform a POST request.

   :param str url: Requested URL.

   :param \*\*kwargs: Optional arguments that :func:`request` takes.

   :return: :class:`ClientResponse` or derived from

.. coroutinefunction:: put(url, *, data=None, **kwargs)

   Perform a PUT request.

   :param str url: Requested URL.

   :param \*\*kwargs: Optional arguments that :func:`request` takes.

   :return: :class:`ClientResponse` or derived from

.. coroutinefunction:: patch(url, *, data=None, **kwargs)

   Perform a PATCH request.

   :param str url: Requested URL.

   :param \*\*kwargs: Optional arguments that :func:`request` takes.

   :return: :class:`ClientResponse` or derived from

Connectors

.. module:: aiohttp.connector

Connectors are transports for aiohttp client API.

There are standard connectors:

  1. :class:`TCPConnector` for regular TCP sockets (both HTTP and HTTPS schemes supported).
  2. :class:`ProxyConnector` for connecting via HTTP proxy.
  3. :class:`UnixConnector` for connecting via UNIX socket (it's used mostly for testing purposes).

All connector classes should be derived from :class:`BaseConnector`.

By default all connectors except :class:`ProxyConnector` support keep-alive connections (behavior is controlled by force_close constructor's parameter).

BaseConnector

TCPConnector

ProxyConnector

UnixConnector

Connection

Encapsulates single connection in connector object.

End user should never create :class:`Connection` instances manually but get it by :meth:`BaseConnector.connect` coroutine.

.. attribute:: closed

   :class:`bool` read-only property, ``True`` if connection was
   closed, released or detached.
.. attribute:: loop

   Event loop used for connection
.. method:: close()

   Close connection with forcibly closing underlying socket.
.. method:: release()

   Release connection back to connector.

   Underlying socket is not closed, the connection may be reused
   later if timeout (30 seconds by default) for connection was not
   expired.
.. method:: detach()

   Detach underlying socket from connection.

   Underlying socket is not closed, next :meth:`close` or
   :meth:`release` calls don't return socket to free pool.
.. disqus::