.. 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)
asyncio.run(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.
.. function:: request(method, url, *, params=None, data=None, \
json=None,\
cookies=None, headers=None, skip_auto_headers=None, auth=None, \
allow_redirects=True, max_redirects=10, \
compress=False, chunked=None, expect100=False, raise_for_status=None, \
read_until_eof=True, \
proxy=None, proxy_auth=None, \
timeout=sentinel, ssl=True, \
server_hostname=None, \
proxy_headers=None, \
trace_request_ctx=None, \
read_bufsize=None, \
auto_decompress=None, \
max_line_size=None, \
max_field_size=None, \
max_headers=None, \
version=aiohttp.HttpVersion11, \
connector=None)
:canonical: aiohttp.client.request
:async:
Asynchronous context manager for performing an asynchronous HTTP
request. Returns a :class:`ClientResponse` response object. Use as
an async context manager.
:param str method: HTTP method
:param url: Request URL, :class:`~yarl.URL` or :class:`str` that will
be encoded with :class:`~yarl.URL` (see :class:`~yarl.URL`
to skip encoding).
:param params: Mapping, iterable of tuple of *key*/*value* pairs or
string to be sent as parameters in the query
string of the new request. Ignored for subsequent
redirected requests (optional)
Allowed values are:
- :class:`collections.abc.Mapping` e.g. :class:`dict`,
:class:`multidict.MultiDict` or
:class:`multidict.MultiDictProxy`
- :class:`collections.abc.Iterable` e.g. :class:`tuple` or
:class:`list`
- :class:`str` with preferably url-encoded content
(**Warning:** content will not be encoded by *aiohttp*)
: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 cookies: HTTP Cookies to send with the request (optional)
:param dict headers: HTTP Headers to send with the request (optional)
:param skip_auto_headers: set of headers for which autogeneration
should be skipped.
*aiohttp* autogenerates headers like ``User-Agent`` or
``Content-Type`` if these headers are not explicitly
passed. Using ``skip_auto_headers`` parameter allows to skip
that generation.
Iterable of :class:`str` or :class:`~multidict.istr`
(optional)
:param aiohttp.BasicAuth auth: an object that represents HTTP Basic
Authorization (optional)
:param bool allow_redirects: Whether to process redirects or not.
When ``True``, redirects are followed (up to ``max_redirects`` times)
and logged into :attr:`ClientResponse.history` and ``trace_configs``.
When ``False``, the original response is returned.
``True`` by default (optional).
:param int max_redirects: Maximum number of redirects to follow.
:exc:`TooManyRedirects` is raised if the number is exceeded.
Ignored when ``allow_redirects=False``.
``10`` by default.
:param bool compress: Set to ``True`` if request has to be compressed
with deflate encoding. If `compress` can not be combined
with a *Content-Encoding* and *Content-Length* headers.
``None`` by default (optional).
:param int chunked: Enables chunked transfer encoding.
It is up to the developer
to decide how to chunk data streams. If chunking is enabled, aiohttp
encodes the provided chunks in the "Transfer-encoding: chunked" format.
If *chunked* is set, then the *Transfer-encoding* and *content-length*
headers are disallowed. ``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 bool read_until_eof: Read response until EOF if response
does not have Content-Length header.
``True`` by default (optional).
:param proxy: Proxy URL, :class:`str` or :class:`~yarl.URL` (optional)
:param aiohttp.BasicAuth proxy_auth: an object that represents proxy HTTP
Basic Authorization (optional)
:param timeout: a :class:`ClientTimeout` settings structure, 300 seconds (5min)
total timeout, 30 seconds socket connect timeout by default.
:param ssl: SSL validation mode. ``True`` for default SSL check
(:func:`ssl.create_default_context` is used),
``False`` for skip SSL certificate validation,
:class:`aiohttp.Fingerprint` for fingerprint
validation, :class:`ssl.SSLContext` for custom SSL
certificate validation.
Supersedes *verify_ssl*, *ssl_context* and
*fingerprint* parameters.
:param str server_hostname: Sets or overrides the host name that the
target server's certificate will be matched against.
See :py:meth:`asyncio.loop.create_connection`
for more information.
:param collections.abc.Mapping proxy_headers: HTTP headers to send to the proxy
if the parameter proxy has been provided.
:param trace_request_ctx: Object used to give as a kw param for each new
:class:`TraceConfig` object instantiated,
used to give information to the
tracers that is only available at request time.
: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 bool auto_decompress: Automatically decompress response body.
May be used to enable/disable auto decompression on a per-request basis.
:param int max_line_size: Maximum allowed size of lines in responses.
:param int max_field_size: Maximum allowed size of header name and value combined in responses.
:param int max_headers: Maximum number of headers and trailers combined in responses.
:param aiohttp.protocol.HttpVersion version: Request HTTP version,
``HTTP 1.1`` by default. (optional)
:param aiohttp.BaseConnector connector: BaseConnector sub-class
instance to support connection pooling. (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())
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).
.. py:class:: AddrInfoType Refer to :py:data:`aiohappyeyeballs.AddrInfoType` for more info.
Warning
Be sure to use aiohttp.AddrInfoType rather than
aiohappyeyeballs.AddrInfoType to avoid import breakage, as
it is likely to be removed from :mod:`aiohappyeyeballs` in the
future.
.. py:class:: SocketFactoryType Refer to :py:data:`aiohappyeyeballs.SocketFactoryType` for more info.
Warning
Be sure to use aiohttp.SocketFactoryType rather than
aiohappyeyeballs.SocketFactoryType to avoid import breakage,
as it is likely to be removed from :mod:`aiohappyeyeballs` in the
future.
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` method).
.. 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 malformed chunked encoding of broken compression data.
.. attribute:: cookies
HTTP cookies of response (*Set-Cookie* HTTP header,
:class:`~http.cookies.SimpleCookie`).
.. note::
Since :class:`~http.cookies.SimpleCookie` uses cookie name as the
key, cookies with the same name but different domains or paths will
be overwritten. Only the last cookie with a given name will be
accessible via this attribute.
To access all cookies, including duplicates with the same name,
use :meth:`response.headers.getall('Set-Cookie') <multidict.MultiDictProxy.getall>`.
The session's cookie jar will correctly store all cookies, even if
they are not accessible via this attribute.
.. 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 ``'application/octet-stream'`` if no Content-Type header
is present or the value contains invalid syntax according to
:rfc:`9110`. To see the original header check
``resp.headers["Content-Type"]``.
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`.
.. method:: read() :async: 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`.
.. method:: 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).
.. method:: text(encoding=None)
:async:
Read response's body and return decoded :class:`str` using
specified *encoding* parameter.
If *encoding* is ``None`` content encoding is determined from the
Content-Type header, or using the ``fallback_charset_resolver`` function.
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).
:raises: :exc:`UnicodeDecodeError` if decoding fails. See also
:meth:`get_encoding`.
:return str: decoded *BODY*
.. method:: json(*, encoding=None, loads=json.loads, \
content_type='application/json')
:async:
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 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 :class:`typing.NamedTuple` with request URL and headers from :class:`~aiohttp.ClientRequest`
object, :class:`aiohttp.RequestInfo` instance.
.. method:: get_encoding() Retrieve content encoding using ``charset`` info in ``Content-Type`` HTTP header. If no charset is present or the charset is not understood by Python, the ``fallback_charset_resolver`` function associated with the ``ClientSession`` is called. .. 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 optional extra information from the connection's transport.
If no value associated with ``name`` is found, ``default`` is returned.
See :meth:`asyncio.BaseTransport.get_extra_info`
:param str name: The key to look up in the transport extra information.
:param default: Default value to be used when no value for ``name`` is
found (default is ``None``).
.. method:: exception() Returns exception if any occurs or returns None.
.. method:: ping(message=b'')
:async:
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`
.. method:: pong(message=b'')
:async:
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`
.. method:: send_str(data, compress=None)
:async:
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.
.. method:: send_bytes(data, compress=None)
:async:
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.
.. method:: send_json(data, compress=None, *, dumps=json.dumps)
:async:
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.
.. method:: send_json_bytes(data, compress=None, *, dumps)
:async:
Send *data* to peer as a JSON binary frame using a bytes-returning encoder.
: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 JSON as :class:`bytes`
(e.g. ``orjson.dumps``).
: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:`bytes`
.. method:: send_frame(message, opcode, compress=None)
:async:
Send a :const:`~aiohttp.WSMsgType` message *message* to peer.
This method is low-level and should be used with caution as it
only accepts bytes which must conform to the correct message type
for *message*.
It is recommended to use the :meth:`send_str`, :meth:`send_bytes`
or :meth:`send_json` methods instead of this method.
The primary use case for this method is to send bytes that are
have already been encoded without having to decode and
re-encode them.
:param bytes message: message to send.
:param ~aiohttp.WSMsgType opcode: opcode of the message.
:param int compress: sets specific level of compression for
single message,
``None`` for not overriding per-socket setting.
.. versionadded:: 3.11
.. method:: close(*, code=WSCloseCode.OK, message=b'')
:async:
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`.
.. method:: receive() :async: 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`
.. method:: receive_str() :async: 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 aiohttp.WSMessageTypeError: if message is not :const:`~aiohttp.WSMsgType.TEXT`.
.. method:: receive_bytes() :async: 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 aiohttp.WSMessageTypeError: if message is not :const:`~aiohttp.WSMsgType.BINARY`.
.. method:: receive_json(*, loads=json.loads)
:async:
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 an HTTP request to be sent by the client.
This object encapsulates all the details of an HTTP request before it is sent. It is primarily used within client middleware to inspect or modify requests.
Note
You typically don't create ClientRequest instances directly. They are
created internally by :class:`ClientSession` methods and passed to middleware.
For more information about using middleware, see :ref:`aiohttp-client-middleware`.
.. attribute:: body
:type: Payload | Literal[b""]
The request body payload (defaults to ``b""`` if no body passed).
.. danger::
**DO NOT set this attribute directly!** Direct assignment will cause resource
leaks. Always use :meth:`update_body` instead:
.. code-block:: python
# WRONG - This will leak resources!
request.body = b"new data"
# CORRECT - Use update_body
await request.update_body(b"new data")
Setting body directly bypasses cleanup of the previous payload, which can
leave file handles open, streams unclosed, and buffers unreleased.
Additionally, setting body directly must be done from within an event loop
and is not thread-safe. Setting body outside of an event loop may raise
RuntimeError when closing file-based payloads.
.. attribute:: chunked :type: bool | None Whether to use chunked transfer encoding: - ``True``: Use chunked encoding - ``False``: Don't use chunked encoding - ``None``: Automatically determine based on body
.. attribute:: compress :type: str | None The compression encoding for the request body. Common values include ``'gzip'`` and ``'deflate'``, but any string value is technically allowed. ``None`` means no compression.
.. attribute:: headers
:type: multidict.CIMultiDict
The HTTP headers that will be sent with the request. This is a case-insensitive
multidict that can be modified by middleware.
.. code-block:: python
# Add or modify headers
request.headers['X-Custom-Header'] = 'value'
request.headers['User-Agent'] = 'MyApp/1.0'
.. attribute:: is_ssl :type: bool ``True`` if the request uses a secure scheme (e.g., HTTPS, WSS), ``False`` otherwise.
.. attribute:: method :type: str The HTTP method of the request (e.g., ``'GET'``, ``'POST'``, ``'PUT'``, etc.).
.. attribute:: original_url :type: yarl.URL The original URL passed to the request method, including any fragment. This preserves the exact URL as provided by the user.
.. attribute:: proxy :type: yarl.URL | None The proxy URL if the request will be sent through a proxy, ``None`` otherwise.
.. attribute:: proxy_headers :type: multidict.CIMultiDict | None Headers to be sent to the proxy server (e.g., ``Proxy-Authorization``). Only set when :attr:`proxy` is not ``None``.
.. attribute:: response_class :type: type[ClientResponse] The class to use for creating the response object. Defaults to :class:`ClientResponse` but can be customized for special handling.
.. attribute:: server_hostname :type: str | None Override the hostname for SSL certificate verification. Useful when connecting through proxies or to IP addresses.
.. attribute:: session
:type: ClientSession
The client session that created this request. Useful for accessing
session-level configuration or making additional requests within middleware.
.. warning::
Be careful when making requests with the same session inside middleware
to avoid infinite recursion. Use ``middlewares=()`` parameter when needed.
.. attribute:: ssl :type: ssl.SSLContext | bool | Fingerprint SSL validation configuration for this request: - ``True``: Use default SSL verification - ``False``: Skip SSL verification - :class:`ssl.SSLContext`: Custom SSL context - :class:`Fingerprint`: Verify specific certificate fingerprint
.. attribute:: url
:type: yarl.URL
The target URL of the request with the fragment (``#...``) part stripped.
This is the actual URL that will be used for the connection.
.. note::
To access the original URL with fragment, use :attr:`original_url`.
.. attribute:: version :type: HttpVersion The HTTP version to use for the request (e.g., ``HttpVersion(1, 1)`` for HTTP/1.1).
.. method:: update_body(body)
Update the request body and close any existing payload to prevent resource leaks.
**This is the ONLY correct way to modify a request body.** Never set the
:attr:`body` attribute directly.
This method is particularly useful in middleware when you need to modify the
request body after the request has been created but before it's sent.
:param body: The new body content. Can be:
- ``bytes``/``bytearray``: Raw binary data
- ``str``: Text data (encoded using charset from Content-Type)
- :class:`FormData`: Form data encoded as multipart/form-data
- :class:`Payload`: A pre-configured payload object
- ``AsyncIterable[bytes]``: Async iterable of bytes chunks
- File-like object: Will be read and sent as binary data
- ``None``: Clears the body
.. code-block:: python
async def middleware(request, handler):
# Modify request body in middleware
if request.method == 'POST':
# CORRECT: Always use update_body
await request.update_body(b'{"modified": true}')
# WRONG: Never set body directly!
# request.body = b'{"modified": true}' # This leaks resources!
# Or add authentication data to form
if isinstance(request.body, FormData):
form = FormData()
# Copy existing fields and add auth token
form.add_field('auth_token', 'secret123')
await request.update_body(form)
return await handler(request)
.. note::
This method is async because it may need to close file handles or
other resources associated with the previous payload. Always await
this method to ensure proper cleanup.
.. danger::
**Never set :attr:`ClientRequest.body` directly!** Direct assignment will cause resource
leaks. Always use this method instead. Setting the body attribute directly:
- Bypasses cleanup of the previous payload
- Leaves file handles and streams open
- Can cause memory leaks
- May result in unexpected behavior with async iterables
.. warning::
When updating the body, ensure that the Content-Type header is
appropriate for the new body content. The Content-Length header
will be updated automatically. When using :class:`FormData` or
:class:`Payload` objects, headers are updated automatically,
but you may need to set Content-Type manually for raw bytes or text.
It is not recommended to change the payload type in middleware. If the
body was already set (e.g., as bytes), it's best to keep the same type
rather than converting it (e.g., to str) as this may result in unexpected
behavior.
.. versionadded:: 3.12
A data class for websocket client timeout settings.
.. attribute:: ws_receive A timeout for websocket to receive a complete message. :class:`float`, ``None`` by default.
.. attribute:: ws_close A timeout for the websocket to close. :class:`float`, ``10.0`` by default.
Note
Timeouts of 5 seconds or more are rounded for scheduling on the next second boundary (an absolute time where microseconds part is zero) for the sake of performance.
E.g., assume a timeout is 10, absolute time when timeout should expire
is loop.time() + 5, and it points to 12345.67 + 10 which is equal
to 12355.67.
The absolute time for the timeout cancellation is 12356.
It leads to grouping all close scheduled timeout expirations to exactly the same time to reduce amount of loop wakeups.
.. versionchanged:: 3.7 Rounding to the next seconds boundary is disabled for timeouts smaller than 5 seconds for the sake of easy debugging. In turn, tiny timeouts can lead to significant performance degradation on production environment.
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 to represent the Content-Disposition header, available as :attr:`ClientResponse.content_disposition` attribute.
.. attribute:: typeA :class:`str` instance. Value of Content-Disposition header itself, e.g.
attachment... attribute:: filenameA :class:`str` instance. Content filename extracted from parameters. May be
None... attribute:: parametersRead-only mapping contains all parameters.
A :class:`typing.NamedTuple` 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
.. function:: set_zlib_backend(lib)
:canonical: aiohttp.compression_utils.set_zlib_backend
Sets the compression backend for zlib-based operations.
This function allows you to override the default zlib backend
used internally by passing a module that implements the standard
compression interface.
The module should implement at minimum the exact interface offered by the
latest version of zlib.
:param types.ModuleType lib: A module that implements the zlib-compatible compression API.
Example usage::
import zlib_ng.zlib_ng as zng
import aiohttp
aiohttp.set_zlib_backend(zng)
.. note:: aiohttp has been tested internally with :mod:`zlib`, :mod:`zlib_ng.zlib_ng`, and :mod:`isal.isal_zlib`.
.. versionadded:: 3.12
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 :canonical: aiohttp.client_exceptions.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
:canonical: aiohttp.client_exceptions.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.
.. attribute:: description
Invalid URL description, :class:`str` instance or :data:`None`.
.. exception:: InvalidUrlClientError :canonical: aiohttp.client_exceptions.InvalidUrlClientError Base class for all errors related to client url. Derived from :exc:`InvalidURL`
.. exception:: RedirectClientError :canonical: aiohttp.client_exceptions.RedirectClientError Base class for all errors related to client redirects. Derived from :exc:`ClientError`
.. exception:: NonHttpUrlClientError :canonical: aiohttp.client_exceptions.NonHttpUrlClientError Base class for all errors related to non http client urls. Derived from :exc:`ClientError`
.. exception:: InvalidUrlRedirectClientError :canonical: aiohttp.client_exceptions.InvalidUrlRedirectClientError Redirect URL is malformed, e.g. it does not contain host part. Derived from :exc:`InvalidUrlClientError` and :exc:`RedirectClientError`
.. exception:: NonHttpUrlRedirectClientError :canonical: aiohttp.client_exceptions.NonHttpUrlRedirectClientError Redirect URL does not contain http schema. Derived from :exc:`RedirectClientError` and :exc:`NonHttpUrlClientError`
.. exception:: ClientResponseError
:canonical: aiohttp.client_exceptions.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
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
Web socket server response error.
Derived from :exc:`ClientResponseError`
.. exception:: WSMessageTypeError :canonical: aiohttp.client_exceptions.WSMessageTypeError Received WebSocket message of unexpected type Derived from :exc:`TypeError`
These exceptions related to low-level connection problems.
Derived from :exc:`ClientError`
Derived from :exc:`ClientConnectionError` and :exc:`ConnectionResetError`
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`
DNS resolution error.
Derived from :exc:`ClientConnectorError`
Derived from :exc:`ClientConnectorError`
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`
Derived from :exc:`ClientConnectorError`
Derived from :exc:`ClientConnectionError`
Server disconnected.
Derived from :exc:`~aiohttp.ServerConnectionError`
.. attribute:: message Partially parsed HTTP message (optional).
Server fingerprint mismatch.
Derived from :exc:`ServerConnectionError`
Server operation timeout: read timeout, etc.
To catch all timeouts, including the total timeout, use
:exc:`asyncio.TimeoutError`.
Derived from :exc:`ServerConnectionError` and :exc:`asyncio.TimeoutError`
Connection timeout on connect and sock_connect timeouts.
Derived from :exc:`ServerTimeoutError`
Reading from socket timeout on sock_read timeout.
Derived from :exc:`ServerTimeoutError`
- :exc:`ClientError`
.. type:: ClientMiddlewareType
Type alias for client middleware functions. Middleware functions must have this signature::
Callable[
[ClientRequest, ClientHandlerType],
Awaitable[ClientResponse]
]
.. type:: ClientHandlerType
Type alias for client request handler functions::
Callable[[ClientRequest], Awaitable[ClientResponse]]