.. module:: aiohttp
.. currentmodule:: aiohttp
Client session is the recommended interface for making HTTP requests.
Session encapsulates a connection pool (connector instance) and supports keepalives by default. Unless you are connecting to a large, unknown number of different servers over the lifetime of your application, it is suggested you use a single session for the lifetime of your application to benefit from connection pooling.
Usage example:
import aiohttp
import asyncio
async def fetch(client):
async with client.get('http://python.org') as resp:
assert resp.status == 200
return await resp.text()
async def main(loop):
async with aiohttp.ClientSession(loop=loop) as client:
html = await fetch(client)
print(html)
loop = asyncio.get_event_loop()
loop.run_until_complete(main(loop))
.. versionadded:: 0.17
The client session supports the context manager protocol for self closing.
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, 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)
Perform an asynchronous HTTP request. Return a response object
(:class:`ClientResponse` or derived from).
:param str method: HTTP method
:param url: Requested URL, :class:`str` or :class:`~yarl.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.BasicAuth auth: an object 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.
``False`` instructs aiohttp to not compress data
even if the Content-Encoding header is set. Use it
when sending pre-compressed data.
``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 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)
:return ClientResponse: a :class:`client response <ClientResponse>` object.
Usage::
import aiohttp
async def fetch():
async with aiohttp.request('GET', 'http://python.org/') as resp:
assert resp.status == 200
print(await resp.text())
.. deprecated:: 0.21
Use :meth:`ClientSession.request`.
.. versionchanged:: 1.1
URLs may be either :class:`str` or :class:`~yarl.URL`
.. coroutinefunction:: get(url, **kwargs)
Perform a GET request.
:param url: Requested URL, :class:`str` or :class:`~yarl.URL`.
:param \*\*kwargs: Optional arguments that :func:`request` takes.
:return: :class:`ClientResponse` or derived from
.. deprecated:: 0.21
Use :meth:`ClientSession.get`.
.. versionchanged:: 1.1
URLs may be either :class:`str` or :class:`~yarl.URL`
.. coroutinefunction:: options(url, **kwargs)
Perform an OPTIONS request.
:param url: Requested URL, :class:`str` or :class:`~yarl.URL`.
:param \*\*kwargs: Optional arguments that :func:`request` takes.
:return: :class:`ClientResponse` or derived from
.. deprecated:: 0.21
Use :meth:`ClientSession.options`.
.. versionchanged:: 1.1
URLs may be either :class:`str` or :class:`~yarl.URL`
.. coroutinefunction:: head(url, **kwargs)
Perform a HEAD request.
:param url: Requested URL, :class:`str` or :class:`~yarl.URL`.
:param \*\*kwargs: Optional arguments that :func:`request` takes.
:return: :class:`ClientResponse` or derived from
.. deprecated:: 0.21
Use :meth:`ClientSession.head`.
.. versionchanged:: 1.1
URLs may be either :class:`str` or :class:`~yarl.URL`
.. coroutinefunction:: delete(url, **kwargs)
Perform a DELETE request.
:param url: Requested URL, :class:`str` or :class:`~yarl.URL`.
:param \*\*kwargs: Optional arguments that :func:`request` takes.
:return: :class:`ClientResponse` or derived from
.. deprecated:: 0.21
Use :meth:`ClientSession.delete`.
.. versionchanged:: 1.1
URLs may be either :class:`str` or :class:`~yarl.URL`
.. coroutinefunction:: post(url, *, data=None, **kwargs)
Perform a POST request.
:param url: Requested URL, :class:`str` or :class:`~yarl.URL`.
:param \*\*kwargs: Optional arguments that :func:`request` takes.
:return: :class:`ClientResponse` or derived from
.. deprecated:: 0.21
Use :meth:`ClientSession.post`.
.. versionchanged:: 1.1
URLs may be either :class:`str` or :class:`~yarl.URL`
.. coroutinefunction:: put(url, *, data=None, **kwargs)
Perform a PUT request.
:param url: Requested URL, :class:`str` or :class:`~yarl.URL`.
:param \*\*kwargs: Optional arguments that :func:`request` takes.
:return: :class:`ClientResponse` or derived from
.. deprecated:: 0.21
Use :meth:`ClientSession.put`.
.. versionchanged:: 1.1
URLs may be either :class:`str` or :class:`~yarl.URL`
.. coroutinefunction:: patch(url, *, data=None, **kwargs)
Perform a PATCH request.
:param url: Requested URL, :class:`str` or :class:`~yarl.URL`.
:param \*\*kwargs: Optional arguments that :func:`request` takes.
:return: :class:`ClientResponse` or derived from
.. deprecated:: 0.21
Use :meth:`ClientSession.patch`.
.. versionchanged:: 1.1
URLs may be either :class:`str` or :class:`~yarl.URL`
.. coroutinefunction:: ws_connect(url, *, protocols=(), \
timeout=10.0, connector=None, auth=None,\
autoclose=True, autoping=True, loop=None,\
origin=None, headers=None)
This function creates a websocket connection, checks the response and
returns a :class:`ClientWebSocketResponse` object. In case of failure
it may raise a :exc:`~aiohttp.errors.WSServerHandshakeError` exception.
:param url: Websocket server url, :class:`str` or :class:`~yarl.URL`
:param tuple protocols: Websocket protocols
:param float timeout: Timeout for websocket read. 10 seconds by default
:param obj connector: object :class:`TCPConnector`
:param bool autoclose: Automatically close websocket connection
on close message from server. If `autoclose` is
False them close procedure has to be handled manually
:param bool autoping: Automatically send `pong` on `ping` message from server
:param aiohttp.helpers.BasicAuth auth: BasicAuth named tuple that
represents HTTP Basic Authorization
(optional)
:param loop: :ref:`event loop<asyncio-event-loop>` used
for processing HTTP requests.
If param is ``None`` :func:`asyncio.get_event_loop`
used for getting default event loop, but we strongly
recommend to use explicit loops everywhere.
:param str origin: Origin header to send to server
:param headers: :class:`dict`, :class:`CIMultiDict` or
:class:`CIMultiDictProxy` for providing additional
headers for websocket handshake request.
.. versionadded:: 0.18
Add *auth* parameter.
.. versionadded:: 0.19
Add *origin* parameter.
.. versionadded:: 0.20
Add *headers* parameter.
.. deprecated:: 0.21
Use :meth:`ClientSession.ws_connect`.
.. versionchanged:: 1.1
URLs may be either :class:`str` or :class:`~yarl.URL`
Connectors are transports for aiohttp client API.
There are standard connectors:
- :class:`TCPConnector` for regular TCP sockets (both HTTP and HTTPS schemes supported).
- :class:`ProxyConnector` for connecting via HTTP proxy (deprecated).
- :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).
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.
Client response returned be :meth:`ClientSession.request` and family.
User never creates the instance of ClientResponse class but gets it from API calls.
:class:`ClientResponse` supports async context manager protocol, e.g.:
resp = await client_session.get(url)
async with resp:
assert resp.status == 200
After exiting from async with block response object will be
released (see :meth:`release` coroutine).
.. versionadded:: 0.18 Support for ``async with``.
.. attribute:: version Response's version, :class:`HttpVersion` instance.
.. attribute:: status HTTP status code of response (:class:`int`), e.g. ``200``.
.. attribute:: reason HTTP status reason of response (:class:`str`), e.g. ``"OK"``.
.. attribute:: method Request's method (:class:`str`).
.. attribute:: url URL of request (:class:`str`).
.. attribute:: url_obj URL of request (:class:`~yarl.URL`). .. versionadded:: 1.1
.. attribute:: connection :class:`Connection` used for handling response.
.. attribute:: content Payload stream, contains response's BODY (:class:`StreamReader`). Reading from the stream raises :exc:`aiohttp.ClientDisconnectedError` if the response object is closed before read calls.
.. attribute:: cookies HTTP cookies of response (*Set-Cookie* HTTP header, :class:`~http.cookies.SimpleCookie`).
.. attribute:: headers A case-insensitive multidict proxy with HTTP headers of response, :class:`CIMultiDictProxy`.
.. attribute:: raw_headers HTTP headers of response as unconverted bytes, a sequence of ``(key, value)`` pairs.
.. attribute:: history A :class:`~collections.abc.Sequence` of :class:`ClientResponse` objects of preceding requests if there were redirects, an empty sequence otherwise.
.. method:: close() Close response and underlying connection. For :term:`keep-alive` support see :meth:`release`.
.. comethod:: read() Read the whole response's body as :class:`bytes`. Close underlying connection if data reading gets an error, release connection otherwise. :return bytes: read *BODY*. .. seealso:: :meth:`close`, :meth:`release`.
.. comethod:: release() Finish response processing, release underlying connection and return it into free connection pool for re-usage by next upcoming request.
.. method:: raise_for_status() Raise an HttpProcessingError if the response status is 400 or higher. Do nothing for success responses (less than 400).
.. comethod:: text(encoding=None)
Read response's body and return decoded :class:`str` using
specified *encoding* parameter.
If *encoding* is ``None`` content encoding is autocalculated
using :term:`cchardet` or :term:`chardet` as fallback if
*cchardet* is not available.
Close underlying connection if data reading gets an error,
release connection otherwise.
:param str encoding: text encoding used for *BODY* decoding, or
``None`` for encoding autodetection
(default).
:return str: decoded *BODY*
.. comethod:: json(encoding=None, loads=json.loads)
Read response's body as *JSON*, return :class:`dict` using
specified *encoding* and *loader*.
If *encoding* is ``None`` content encoding is autocalculated
using :term:`cchardet` or :term:`chardet` as fallback if
*cchardet* is not available.
Close underlying connection if data reading gets an error,
release connection otherwise.
:param str encoding: text encoding used for *BODY* decoding, or
``None`` for encoding autodetection
(default).
:param callable loads: :func:`callable` used for loading *JSON*
data, :func:`json.loads` by default.
:return: *BODY* as *JSON* data parsed by *loads* parameter or
``None`` if *BODY* is empty or contains white-spaces
only.
To connect to a websocket server :func:`aiohttp.ws_connect` or :meth:`aiohttp.ClientSession.ws_connect` coroutines should be used, do not create an instance of class :class:`ClientWebSocketResponse` manually.
Class for handling client-side websockets.
.. attribute:: closed Read-only property, ``True`` if :meth:`close` has been called of :const:`~aiohttp.WSMsgType.CLOSE` message has been received from peer.
.. attribute:: protocol Websocket *subprotocol* chosen after :meth:`start` call. May be ``None`` if server and client protocols are not overlapping.
.. method:: exception() Returns exception if any occurs or returns None.
.. method:: ping(message=b'')
Send :const:`~aiohttp.WSMsgType.PING` to peer.
:param message: optional payload of *ping* message,
:class:`str` (converted to *UTF-8* encoded bytes)
or :class:`bytes`.
.. method:: send_str(data) Send *data* to peer as :const:`~aiohttp.WSMsgType.TEXT` message. :param str data: data to send. :raise TypeError: if data is not :class:`str`
.. method:: send_bytes(data)
Send *data* to peer as :const:`~aiohttp.WSMsgType.BINARY` message.
:param data: data to send.
:raise TypeError: if data is not :class:`bytes`,
:class:`bytearray` or :class:`memoryview`.
.. method:: send_json(data, *, dumps=json.loads)
Send *data* to peer as JSON string.
:param data: data to send.
:param callable dumps: any :term:`callable` that accepts an object and
returns a JSON string
(:func:`json.dumps` by default).
:raise RuntimeError: if connection is not started or closing
:raise ValueError: if data is not serializable object
:raise TypeError: if value returned by ``dumps(data)`` is not
:class:`str`
.. comethod:: close(*, code=1000, message=b'')
A :ref:`coroutine<coroutine>` that initiates closing handshake by sending
:const:`~aiohttp.WSMsgType.CLOSE` message. It waits for
close response from server. It add timeout to `close()` call just wrap
call with `asyncio.wait()` or `asyncio.wait_for()`.
:param int code: closing code
:param message: optional payload of *pong* message,
:class:`str` (converted to *UTF-8* encoded bytes)
or :class:`bytes`.
.. comethod:: receive()
A :ref:`coroutine<coroutine>` that waits upcoming *data*
message from peer and returns it.
The coroutine implicitly handles
:const:`~aiohttp.WSMsgType.PING`,
:const:`~aiohttp.WSMsgType.PONG` and
:const:`~aiohttp.WSMsgType.CLOSE` without returning the
message.
It process *ping-pong game* and performs *closing handshake* internally.
:return: :class:`~aiohttp.WSMessage`, `tp` is a type from
:class:`~aiohttp.WSMsgType` enumeration.
.. coroutinemethod:: receive_str() A :ref:`coroutine<coroutine>` that calls :meth:`receive` but also asserts the message type is :const:`~aiohttp.WSMsgType.TEXT`. :return str: peer's message content. :raise TypeError: if message is :const:`~aiohttp.WSMsgType.BINARY`.
.. coroutinemethod:: receive_bytes() A :ref:`coroutine<coroutine>` that calls :meth:`receive` but also asserts the message type is :const:`~aiohttp.WSMsgType.BINARY`. :return bytes: peer's message content. :raise TypeError: if message is :const:`~aiohttp.WSMsgType.TEXT`.
.. coroutinemethod:: receive_json(*, loads=json.loads)
A :ref:`coroutine<coroutine>` that calls :meth:`receive_str` and loads
the JSON string to a Python dict.
:param callable loads: any :term:`callable` that accepts
:class:`str` and returns :class:`dict`
with parsed JSON (:func:`json.loads` by
default).
:return dict: loaded JSON content
:raise TypeError: if message is :const:`~aiohttp.WSMsgType.BINARY`.
:raise ValueError: if message is not valid JSON.
HTTP basic authentication helper.
| param str login: | login |
|---|---|
| param str password: | password |
| param str encoding: | encoding ('latin1' by default) |
Should be used for specifying authorization data in client API, e.g. auth parameter for :meth:`ClientSession.request`.
.. classmethod:: decode(auth_header, encoding='latin1')
Decode HTTP basic authentication credentials.
:param str auth_header: The ``Authorization`` header to decode.
:param str encoding: (optional) encoding ('latin1' by default)
:return: decoded authentication data, :class:`BasicAuth`.
.. method:: encode() Encode credentials into string suitable for ``Authorization`` header etc. :return: encoded authentication data, :class:`str`.
The cookie jar instance is available as :attr:`ClientSession.cookie_jar`.
The jar contains :class:`~http.cookies.Morsel` items for storing internal cookie data.
API provides a count of saved cookies:
len(session.cookie_jar)
These cookies may be iterated over:
for cookie in session.cookie_jar:
print(cookie.key)
print(cookie["domain"])
The class implements :class:`collections.abc.Iterable`, :class:`collections.abc.Sized` and :class:`aiohttp.AbstractCookieJar` interfaces.
Implements cookie storage adhering to RFC 6265.
| param bool unsafe: | (optional) Whether to accept cookies from IPs. |
|---|---|
| param bool loop: | an :ref:`event loop<asyncio-event-loop>` instance. See :class:`aiohttp.abc.AbstractCookieJar` |
.. method:: update_cookies(cookies, response_url=None)
Update cookies returned by server in ``Set-Cookie`` header.
:param cookies: a :class:`collections.abc.Mapping`
(e.g. :class:`dict`, :class:`~http.cookies.SimpleCookie`) or
*iterable* of *pairs* with cookies returned by server's
response.
:param str response_url: URL of response, ``None`` for *shared
cookies*. Regular cookies are coupled with server's URL and
are sent only to this server, shared ones are sent in every
client request.
.. method:: filter_cookies(request_url)
Return jar's cookies acceptable for URL and available in
``Cookie`` header for sending client requests for given URL.
:param str response_url: request's URL for which cookies are asked.
:return: :class:`http.cookies.SimpleCookie` with filtered
cookies for given URL.
.. method:: save(file_path) Write a pickled representation of cookies into the file at provided path. :param str file_path: Path to file where cookies will be serialized.
.. method:: load(file_path) Load a pickled representation of cookies from the file at provided path. :param str file_path: Path to file from where cookies will be imported.
.. disqus:: :title: aiohttp client reference