.. 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())
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.
.. cofunction:: 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, raise_for_status=False, \
read_bufsize=None, \
connector=None, loop=None,\
read_until_eof=True, timeout=sentinel)
:async-with:
Asynchronous context manager for performing an asynchronous HTTP
request. Returns a :class:`ClientResponse` response object.
: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: The data to send in the body of the request. This can be a
:class:`FormData` object or anything that can be passed into
:class:`FormData`, e.g. a dictionary, bytes, or file-like object.
(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 bool raise_for_status: Automatically call
:meth:`ClientResponse.raise_for_status()`
for response if set to ``True``. If
set to ``None`` value from
``ClientSession`` will be used.
``None`` by default (optional).
.. versionadded:: 3.4
:param aiohttp.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 int read_bufsize: Size of the read buffer (:attr:`ClientResponse.content`).
``None`` by default,
it means that the session global value is used.
.. versionadded:: 3.7
:param timeout: a :class:`ClientTimeout` settings structure, 300 seconds (5min)
total timeout by default.
: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())
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 .. deprecated:: 3.5
.. 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.
Client response returned by :meth:`aiohttp.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).
.. attribute:: version Response's version, :class:`~aiohttp.protocol.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:: ok Boolean representation of HTTP status code (:class:`bool`). ``True`` if ``status`` is less than ``400``; otherwise, ``False``.
.. attribute:: method Request's method (:class:`str`).
.. attribute:: url URL of request (:class:`~yarl.URL`).
.. attribute:: real_url Unmodified URL of request with URL fragment unstripped (:class:`~yarl.URL`). .. versionadded:: 3.2
.. 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:: links Link HTTP header parsed into a :class:`~multidict.MultiDictProxy`. For each link, key is link param `rel` when it exists, or link url as :class:`str` otherwise, and value is :class:`~multidict.MultiDictProxy` of link params and url at key `url` as :class:`~yarl.URL` instance. .. versionadded:: 3.2
.. 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'`` or ``None`` if no *Content-Type* header present in HTTP headers or it has no charset information.
.. attribute:: content_disposition Read-only property that specified the *Content-Disposition* HTTP header. Instance of :class:`ContentDisposition` or ``None`` if no *Content-Disposition* header present in HTTP headers.
.. 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 *charset-normalizer* tool if the
header is not provided by server.
:term:`cchardet` is used with fallback to :term:`charset-normalizer` 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*
:raise LookupError: if the encoding detected by cchardet is
unknown by Python (e.g. VISCII).
.. note::
If response has no ``charset`` info in ``Content-Type`` HTTP
header :term:`cchardet` / :term:`charset-normalizer` 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:`charset-normalizer` 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).
By the standard JSON encoding should be
``UTF-8`` but practice beats purity: some
servers return non-UTF
responses. Autodetection works pretty fine
anyway.
:param collections.abc.Callable loads: :term:`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:`~aiohttp.ClientRequest`
object, :class:`aiohttp.RequestInfo` instance.
.. method:: get_encoding()
Automatically detect content encoding using ``charset`` info in
``Content-Type`` HTTP header. If this info is not exists or there
are no appropriate codecs for encoding then :term:`cchardet` /
:term:`charset-normalizer` is used.
Beware that it is not always safe to use the result of this function to
decode a response. Some encodings detected by cchardet are not known by
Python (e.g. VISCII). *charset-normalizer* is not concerned by that issue.
:raise RuntimeError: if called before the body has been read,
for :term:`cchardet` usage
.. versionadded:: 3.0
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, compress=None)
Send *data* to peer as :const:`~aiohttp.WSMsgType.TEXT` message.
:param str data: data to send.
:param int compress: sets specific level of compression for
single message,
``None`` for not overriding per-socket setting.
:raise TypeError: if data is not :class:`str`
.. versionchanged:: 3.0
The method is converted into :term:`coroutine`,
*compress* parameter added.
.. comethod:: send_bytes(data, compress=None)
Send *data* to peer as :const:`~aiohttp.WSMsgType.BINARY` message.
:param data: data to send.
:param int compress: sets specific level of compression for
single message,
``None`` for not overriding per-socket setting.
:raise TypeError: if data is not :class:`bytes`,
:class:`bytearray` or :class:`memoryview`.
.. versionchanged:: 3.0
The method is converted into :term:`coroutine`,
*compress* parameter added.
.. comethod:: send_json(data, compress=None, *, dumps=json.dumps)
Send *data* to peer as JSON string.
:param data: data to send.
:param int compress: sets specific level of compression for
single message,
``None`` for not overriding per-socket setting.
:param collections.abc.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`,
*compress* parameter added.
.. comethod:: close(*, code=WSCloseCode.OK, 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. See also :class:`~aiohttp.WSCloseCode`.
:param message: optional payload of *close* 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 collections.abc.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.
Represents ETag identifier.
.. attribute:: value Value of corresponding etag without quotes.
.. attribute:: is_weak Flag indicates that etag is weak (has `W/` prefix).
.. versionadded:: 3.8
A data class with request URL and headers from :class:`~aiohttp.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.
.. attribute:: real_url Requested *url* with URL fragment unstripped, :class:`yarl.URL` instance. .. versionadded:: 3.2
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() <aiohttp.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`.
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())
Fingerprint helper for checking SSL certificates by SHA256 digest.
| param bytes digest: | SHA256 digest for certificate in DER-encoded binary form (see :meth:`ssl.SSLSocket.getpeercert`). |
|---|
To check fingerprint pass the object into :meth:`ClientSession.get` call, e.g.:
import hashlib
with open(path_to_cert, 'rb') as f:
digest = hashlib.sha256(f.read()).digest()
await session.get(url, ssl=aiohttp.Fingerprint(digest))
.. versionadded:: 3.0
A :class:`FormData` object contains the form data and also handles
encoding it into a body that is either multipart/form-data or
application/x-www-form-urlencoded. multipart/form-data is
used if at least one field is an :class:`io.IOBase` object or was
added with at least one optional argument to :meth:`add_field<aiohttp.FormData.add_field>`
(content_type, filename, or content_transfer_encoding).
Otherwise, application/x-www-form-urlencoded is used.
:class:`FormData` instances are callable and return a :class:`aiohttp.payload.Payload` on being called.
Helper class for multipart/form-data and application/x-www-form-urlencoded body generation.
| param fields: | A container for the key/value pairs of this form. Possible types are:
If it is a :class:`tuple` or :class:`list`, it must be a valid argument for :meth:`add_fields<aiohttp.FormData.add_fields>`. For :class:`dict`, :class:`multidict.MultiDict`, and :class:`multidict.MultiDictProxy`, the keys and values must be valid name and value arguments to :meth:`add_field<aiohttp.FormData.add_field>`, respectively. |
|---|
.. method:: add_field(name, value, content_type=None, filename=None,\
content_transfer_encoding=None)
Add a field to the form.
:param str name: Name of the field
:param value: Value of the field
Possible types are:
- :class:`str`
- :class:`bytes`, :class:`bytearray`, or :class:`memoryview`
- :class:`io.IOBase`, e.g. a file-like object
:param str content_type: The field's content-type header (optional)
:param str filename: The field's filename (optional)
If this is not set and ``value`` is a :class:`bytes`, :class:`bytearray`,
or :class:`memoryview` object, the `name` argument is used as the filename
unless ``content_transfer_encoding`` is specified.
If ``filename`` is not set and ``value`` is an :class:`io.IOBase`
object, the filename is extracted from the object if possible.
:param str content_transfer_encoding: The field's content-transfer-encoding
header (optional)
.. method:: add_fields(fields)
Add one or more fields to the form.
:param fields: An iterable containing:
- :class:`io.IOBase`, e.g. a file-like object
- :class:`multidict.MultiDict` or :class:`multidict.MultiDictProxy`
- :class:`tuple` or :class:`list` of length two, containing a name-value pair
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.
Represent Content-Disposition header
.. attribute:: value
A :class:`str` instance. Value of Content-Disposition header
itself, e.g. attachment.
.. attribute:: filename
A :class:`str` instance. Content filename extracted from
parameters. May be None.
.. attribute:: parameters
Read-only mapping contains all parameters.
.. 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:: status
HTTP status code of response (:class:`int`), e.g. ``400``.
.. 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.
.. attribute:: code
HTTP status code of response (:class:`int`), e.g. ``400``.
.. deprecated:: 3.1
Web socket server response error.
Derived from :exc:`ClientResponseError`
Invalid content type.
Derived from :exc:`ClientResponseError`
.. versionadded:: 2.3
Client was redirected too many times.
Maximum number of redirects can be configured by using
parameter max_redirects in :meth:`request<aiohttp.ClientSession.request>`.
Derived from :exc:`ClientResponseError`
.. versionadded:: 3.2
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:`ClientConnectorError`
Derived from :exc:`ClientConnectorError`
Derived from :exc:`ClientConnectionError`
Derived from :exc:`ClientConnectorError`
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:`~aiohttp.ServerConnectionError`
.. attribute:: message Partially parsed HTTP message (optional).
Server operation timeout: read timeout, etc.
Derived from :exc:`ServerConnectionError` and :exc:`asyncio.TimeoutError`
Server fingerprint mismatch.
Derived from :exc:`ServerConnectionError`