.. 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():
async with aiohttp.ClientSession() 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, \
json=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 json: Any json compatible python object (optional). *json* and *data*
parameters could not be used at the same time.
: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.
``None`` by default (optional).
:param int chunked: Enables 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.
.. deprecated:: 2.0
: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())
.. 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:`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 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
.. attribute:: transport Connection transport
.. 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:`~yarl.URL`).
.. attribute:: connection :class:`Connection` used for handling response.
.. attribute:: content Payload stream, which contains response's BODY (:class:`StreamReader`). It supports various reading methods depending on the expected format. When chunked transfer encoding is used by the server, allows retrieving the actual http chunks. Reading from the stream may raise :exc:`aiohttp.ClientPayloadError` if the response object is closed before response receives all data or in case if any transfer encoding related errors like misformed chunked encoding of broken compression data.
.. 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:`~multidict.CIMultiDictProxy`.
.. attribute:: raw_headers Unmodified HTTP headers of response as unconverted bytes, a sequence of ``(key, value)`` pairs.
.. attribute:: content_type
Read-only property with *content* part of *Content-Type* header.
.. note::
Returns value is ``'application/octet-stream'`` if no
Content-Type header present in HTTP headers according to
:rfc:`2616`. To make sure Content-Type header is not present in
the server reply, use :attr:`headers` or :attr:`raw_headers`, e.g.
``'CONTENT-TYPE' not in resp.headers``.
.. attribute:: charset
Read-only property that specifies the encoding for the request's BODY.
The value is parsed from the Content-Type HTTP header.
Returns :class:`str` like
'utf-8'orNoneif no Content-Type header present in HTTP headers or it has no charset information.
.. attribute:: history A :class:`~collections.abc.Sequence` of :class:`ClientResponse` objects of preceding requests (earliest request first) 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. Raise an :exc:`aiohttp.ClientResponseError` if the data can't be read. :return bytes: read *BODY*. .. seealso:: :meth:`close`, :meth:`release`.
.. comethod:: release() It is not required to call `release` on the response object. When the client fully receives the payload, the underlying connection automatically returns back to pool. If the payload is not fully read, the connection is closed
.. method:: raise_for_status() Raise an :exc:`aiohttp.ClientResponseError` 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 ``Content-Type`` HTTP header and *chardet* tool if the
header is not provided by server.
:term:`cchardet` is used with fallback to :term:`chardet` 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*
.. note::
If response has no ``charset`` info in ``Content-Type`` HTTP
header :term:`cchardet` / :term:`chardet` is used for content
encoding autodetection.
It may hurt performance. If page encoding is known passing
explicit *encoding* parameter might help::
await resp.text('ISO-8859-1')
.. comethod:: json(*, encoding=None, loads=json.loads, \
content_type='application/json')
Read response's body as *JSON*, return :class:`dict` using
specified *encoding* and *loader*. If data is not still available
a ``read`` call will be done,
If *encoding* is ``None`` content encoding is autocalculated
using :term:`cchardet` or :term:`chardet` as fallback if
*cchardet* is not available.
if response's `content-type` does not match `content_type` parameter
:exc:`aiohttp.ContentTypeError` get raised.
To disable content type check pass ``None`` value.
: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.
:param str content_type: specify response's content-type, if content type
does not match raise :exc:`aiohttp.ClientResponseError`.
To disable `content-type` check, pass ``None`` as value.
(default: `application/json`).
:return: *BODY* as *JSON* data parsed by *loads* parameter or
``None`` if *BODY* is empty or contains white-spaces only.
.. attribute:: request_info
A namedtuple with request URL and headers from :class:`ClientRequest`
object, :class:`aiohttp.RequestInfo` instance.
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 or :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:: get_extra_info(name, default=None) Reads extra info from connection's transport
.. method:: exception() Returns exception if any occurs or returns None.
.. comethod:: 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`.
.. versionchanged:: 3.0
The method is converted into :term:`coroutine`
.. comethod:: pong(message=b'')
Send :const:`~aiohttp.WSMsgType.PONG` to peer.
:param message: optional payload of *pong* message,
:class:`str` (converted to *UTF-8* encoded bytes)
or :class:`bytes`.
.. versionchanged:: 3.0
The method is converted into :term:`coroutine`
.. comethod:: 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`
.. versionchanged:: 3.0
The method is converted into :term:`coroutine`
.. comethod:: 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`.
.. versionchanged:: 3.0
The method is converted into :term:`coroutine`
.. comethod:: send_json(data, *, dumps=json.dumps)
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`
.. versionchanged:: 3.0
The method is converted into :term:`coroutine`
.. 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. To add a timeout to `close()` call
just wrap the 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`
.. 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.
A namedtuple with request URL and headers from :class:`ClientRequest` object, available as :attr:`ClientResponse.request_info` attribute.
.. attribute:: url Requested *url*, :class:`yarl.URL` instance.
.. attribute:: method Request HTTP method like ``'GET'`` or ``'POST'``, :class:`str`.
.. attribute:: headers HTTP headers for request, :class:`multidict.CIMultiDict` instance.
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`.
.. classmethod:: from_url(url)
Constructed credentials info from url's *user* and *password*
parts.
:return: credentials data, :class:`BasicAuth` or ``None`` is
credentials are not provided.
.. versionadded:: 2.3
.. 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` .. deprecated:: 2.0 |
.. 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 file_path: Path to file where cookies will be serialized,
:class:`str` or :class:`pathlib.Path` instance.
.. method:: load(file_path)
Load a pickled representation of cookies from the file
at provided path.
:param file_path: Path to file from where cookies will be
imported, :class:`str` or :class:`pathlib.Path` instance.
Dummy cookie jar which does not store cookies but ignores them.
Could be useful e.g. for web crawlers to iterate over Internet without blowing up with saved cookies information.
To install dummy cookie jar pass it into session instance:
jar = aiohttp.DummyCookieJar() session = aiohttp.ClientSession(cookie_jar=DummyCookieJar())
Exception hierarchy has been significantly modified in version 2.0. aiohttp defines only exceptions that covers connection handling and server response misbehaviors. For developer specific mistakes, aiohttp uses python standard exceptions like :exc:`ValueError` or :exc:`TypeError`.
Reading a response content may raise a :exc:`ClientPayloadError` exception. This exception indicates errors specific to the payload encoding. Such as invalid compressed data, malformed chunked-encoded chunks or not enough data that satisfy the content-length header.
All exceptions are available as members of aiohttp module.
.. exception:: ClientError Base class for all client specific exceptions. Derived from :exc:`Exception`
This exception can only be raised while reading the response payload if one of these errors occurs:
- invalid compression
- malformed chunked encoding
- not enough data that satisfy
Content-LengthHTTP header.
Derived from :exc:`ClientError`
.. exception:: InvalidURL
URL used for fetching is malformed, e.g. it does not contain host
part.
Derived from :exc:`ClientError` and :exc:`ValueError`
.. attribute:: url
Invalid URL, :class:`yarl.URL` instance.
.. exception:: ClientResponseError
These exceptions could happen after we get response from server.
Derived from :exc:`ClientError`
.. attribute:: request_info
Instance of :class:`RequestInfo` object, contains information
about request.
.. attribute:: code
HTTP status code of response (:class:`int`), e.g. ``200``.
.. attribute:: message
Message of response (:class:`str`), e.g. ``"OK"``.
.. attribute:: headers
Headers in response, a list of pairs.
.. attribute:: history
History from failed response, if available, else empty tuple.
A :class:`tuple` of :class:`ClientResponse` objects used for
handle redirection responses.
Web socket server response error.
Derived from :exc:`ClientResponseError`
Web socket server response error.
Derived from :exc:`ClientResponseError`
Invalid content type.
Derived from :exc:`ClientResponseError`
.. versionadded:: 2.3
These exceptions related to low-level connection problems.
Derived from :exc:`ClientError`
Subset of connection errors that are initiated by an :exc:`OSError` exception.
Derived from :exc:`ClientConnectionError` and :exc:`OSError`
Connector related exceptions.
Derived from :exc:`ClientOSError`
Derived from :exc:`ClientConnectonError`
Derived from :exc:`ClientConnectonError`
Derived from :exc:`ClientConnectonError`
Response ssl error.
Derived from :exc:`ClientSSLError` and :exc:`ssl.SSLError`
Response certificate error.
Derived from :exc:`ClientSSLError` and :exc:`ssl.CertificateError`
Server disconnected.
Derived from :exc:`ServerDisconnectonError`
.. attribute:: message Partially parsed HTTP message (optional).
Server operation timeout: read timeout, etc.
Derived from :exc:`ServerConnectonError` and :exc:`asyncio.TimeoutError`
Server fingerprint mismatch.
Derived from :exc:`ServerConnectonError`