Client Reference¶

Client Session¶

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.

class aiohttp.ClientSession(base_url=None, *, connector=None, cookies=None, headers=None, skip_auto_headers=None, auth=None, json_serialize=json.dumps, request_class=ClientRequest, response_class=ClientResponse, ws_response_class=ClientWebSocketResponse, version=aiohttp.HttpVersion11, cookie_jar=None, connector_owner=True, raise_for_status=False, timeout=sentinel, auto_decompress=True, trust_env=False, requote_redirect_url=True, trace_configs=None, middlewares=(), read_bufsize=2**16, max_line_size=8190, max_field_size=8190, fallback_charset_resolver=lambda r, b: ..., ssl_shutdown_timeout=0)[source]¶

The class for creating client sessions and making requests.

Parameters:

base_url –

Base part of the URL (optional) If set, allows to join a base part to relative URLs in request calls. If the URL has a path it must have a trailing / (as in https://docs.aiohttp.org/en/stable/).

Note that URL joining follows RFC 3986. This means, in the most common case the request URLs should have no leading slash, e.g.:

session = ClientSession(base_url="http://example.com/foo/")

await session.request("GET", "bar")
# request for http://example.com/foo/bar

await session.request("GET", "/bar")
# request for http://example.com/bar

Added in version 3.8.

Changed in version 3.12: Added support for overriding the base URL with an absolute one in client sessions.

connector (aiohttp.BaseConnector) – BaseConnector sub-class instance to support connection pooling.
cookies (dict) – Cookies to send with the request (optional)
headers –
HTTP Headers to send with every request (optional).

May be either iterable of key-value pairs or Mapping (e.g. dict, CIMultiDict).
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. Note that Content-Length autogeneration can’t be skipped.

Iterable of str or istr (optional)
auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional). It will be included with any request. However, if the _base_url parameter is set, the request URL’s origin must match the base URL’s origin; otherwise, the default auth will not be included.
json_serialize (collections.abc.Callable) –
Json serializer callable.

By default json.dumps() function.
request_class (aiohttp.ClientRequest) – Custom class to use for client requests.
response_class (ClientResponse) – Custom class to use for client responses.
ws_response_class (ClientWebSocketResponse) – Custom class to use for websocket responses.
version – supported HTTP version, HTTP 1.1 by default.
cookie_jar –
Cookie Jar, AbstractCookieJar instance.

By default every session instance has own private cookie jar for automatic cookies processing but user may redefine this behavior by providing own jar implementation.

One example is not processing cookies at all when working in proxy mode.

If no cookie processing is needed, a aiohttp.DummyCookieJar instance can be provided.
connector_owner (bool) –
Close connector instance on session closing.

Setting the parameter to False allows to share connection pool between sessions without sharing session state: cookies etc.

raise_for_status (bool) –

Automatically call ClientResponse.raise_for_status() for each response, False by default.

This parameter can be overridden when making a request, e.g.:

client_session = aiohttp.ClientSession(raise_for_status=True)
resp = await client_session.get(url, raise_for_status=False)
async with resp:
    assert resp.status == 200

Set the parameter to True if you need raise_for_status for most of cases but override raise_for_status for those requests where you need to handle responses with status 400 or higher.

You can also provide a coroutine which takes the response as an argument and can raise an exception based on custom logic, e.g.:

async def custom_check(response):
    if response.status not in {201, 202}:
        raise RuntimeError('expected either 201 or 202')
    text = await response.text()
    if 'apple pie' not in text:
        raise RuntimeError('I wanted to see "apple pie" in response')

client_session = aiohttp.ClientSession(raise_for_status=custom_check)
...

As with boolean values, you’re free to set this on the session and/or overwrite it on a per-request basis.

timeout –

a ClientTimeout settings structure, 300 seconds (5min)
total timeout, 30 seconds socket connect timeout by default.

Added in version 3.3.

Changed in version 3.10.9: The default value for the sock_connect timeout has been changed to 30 seconds.
auto_decompress (bool) –
Automatically decompress response body (True by default).

Added in version 2.3.
trust_env (bool) –
Trust environment settings for proxy configuration if the parameter is True (False by default). See Proxy support for more information.

Get proxy credentials from ~/.netrc file if present.

Get HTTP Basic Auth credentials from ~/.netrc file if present.

If NETRC environment variable is set, read from file specified there rather than from ~/.netrc.

See also

.netrc documentation: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html

Added in version 2.3.

Changed in version 3.0: Added support for ~/.netrc file.

Changed in version 3.9: Added support for reading HTTP Basic Auth credentials from ~/.netrc file.
requote_redirect_url (bool) –

Apply URL requoting for redirection URLs if
automatic redirection is enabled (True by default).

Added in version 3.5.
trace_configs – A list of TraceConfig instances used for client tracing. None (default) is used for request tracing disabling. See Tracing Reference for more information.
middlewares –

A sequence of middleware instances to apply to all session requests.
Each middleware must match the ClientMiddlewareType signature. () (empty tuple, default) is used when no middleware is needed. See Client Middleware for more information.

Added in version 3.12.
read_bufsize (int) –

Size of the read buffer (ClientResponse.content).
64 KiB by default.

Added in version 3.7.
max_line_size (int) – Maximum allowed size of lines in responses.
max_field_size (int) – Maximum allowed size of header fields in responses.
fallback_charset_resolver (Callable[[ClientResponse,bytes],str]) –
A callable that accepts a ClientResponse and the bytes contents, and returns a str which will be used as the encoding parameter to bytes.decode().

This function will be called when the charset is not known (e.g. not specified in the Content-Type header). The default function simply defaults to utf-8.

Added in version 3.8.6.
ssl_shutdown_timeout (float) –
(DEPRECATED) This parameter is deprecated and will be removed in aiohttp 4.0. Grace period for SSL shutdown handshake on TLS connections when the connector is closed (0 seconds by default). By default (0), SSL connections are aborted immediately when the connector is closed, without performing the shutdown handshake. During normal operation, SSL connections use Python’s default SSL shutdown behavior. Setting this to a positive value (e.g., 0.1) will perform a graceful shutdown when closing the connector, notifying the remote peer which can help prevent “connection reset” errors at the cost of additional cleanup time. This timeout is passed to the underlying TCPConnector when one is created automatically. Note: On Python versions prior to 3.11, only a value of 0 is supported; other values will trigger a warning.

Added in version 3.12.5.

Changed in version 3.12.11: Changed default from 0.1 to 0 to abort SSL connections immediately when the connector is closed. Added support for ssl_shutdown_timeout=0 on all Python versions. A RuntimeWarning is issued when non-zero values are passed on Python < 3.11.

Deprecated since version 3.12.11: This parameter is deprecated and will be removed in aiohttp 4.0.

closed¶

True if the session has been closed, False otherwise.

A read-only property.

connector¶

aiohttp.BaseConnector derived instance used for the session.

A read-only property.

cookie_jar¶

The session cookies, AbstractCookieJar instance.

Gives access to cookie jar’s content and modifiers.

A read-only property.

requote_redirect_url¶: aiohttp re quote’s redirect urls by default, but some servers require exact url from location header. To disable re-quote system set requote_redirect_url attribute to False.

Added in version 2.1.

Note

This parameter affects all subsequent requests.

Deprecated since version 3.5: The attribute modification is deprecated.

loop¶

A loop instance used for session creation.

A read-only property.

Deprecated since version 3.5.

timeout¶: Default client timeouts, ClientTimeout instance. The value can be tuned by passing timeout parameter to ClientSession constructor.

Added in version 3.7.

headers¶

HTTP Headers that sent with every request

May be either iterable of key-value pairs or Mapping (e.g. dict, CIMultiDict).

Added in version 3.7.

skip_auto_headers¶

Set of headers for which autogeneration skipped.

frozenset of str or istr (optional)

Added in version 3.7.

auth¶

An object that represents HTTP Basic Authorization.

BasicAuth (optional)

Added in version 3.7.

json_serialize¶

Json serializer callable.

By default json.dumps() function.

Added in version 3.7.

connector_owner¶

Should connector be closed on session closing

bool (optional)

Added in version 3.7.

raise_for_status¶

Should ClientResponse.raise_for_status() be called for each response

Either bool or collections.abc.Callable

Added in version 3.7.

auto_decompress¶

Should the body response be automatically decompressed

bool default is True

Added in version 3.7.

trust_env¶

Trust environment settings for proxy configuration or ~/.netrc file if present. See Proxy support for more information.

bool default is False

Added in version 3.7.

trace_configs¶: A list of TraceConfig instances used for client tracing. None (default) is used for request tracing disabling. See Tracing Reference for more information.

Added in version 3.7.

async 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=None, 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, middlewares=None, read_bufsize=None, auto_decompress=None, max_line_size=None, max_field_size=None)[source]¶

Performs an asynchronous HTTP request. Returns a response object that should be used as an async context manager.

Parameters:

method (str) – HTTP method
url – Request URL, URL or str that will be encoded with URL (see URL to skip encoding).
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:
- collections.abc.Mapping e.g. dict, multidict.MultiDict or multidict.MultiDictProxy
- collections.abc.Iterable e.g. tuple or list
- str with preferably url-encoded content (Warning: content will not be encoded by aiohttp)
data – The data to send in the body of the request. This can be a FormData object or anything that can be passed into FormData, e.g. a dictionary, bytes, or file-like object. (optional)
json – Any json compatible python object (optional). json and data parameters could not be used at the same time.
cookies (dict) –

HTTP Cookies to send with
the request (optional)

Global session cookies and the explicitly set cookies will be merged when sending the request.

Added in version 3.5.
headers (dict) – HTTP Headers to send with the request (optional)
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 str or istr (optional)
auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional)
allow_redirects (bool) – Whether to process redirects or not. When True, redirects are followed (up to max_redirects times) and logged into ClientResponse.history and trace_configs. When False, the original response is returned. True by default (optional).
max_redirects (int) – Maximum number of redirects to follow. TooManyRedirects is raised if the number is exceeded. Ignored when allow_redirects=False. 10 by default.
compress (bool) – 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).
chunked (int) – Enable 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).
expect100 (bool) – Expect 100-continue response from server. False by default (optional).
raise_for_status (bool) –

Automatically call ClientResponse.raise_for_status() for
response if set to True. If set to None value from ClientSession will be used. None by default (optional).

Added in version 3.4.
read_until_eof (bool) – Read response until EOF if response does not have Content-Length header. True by default (optional).
proxy – Proxy URL, str or URL (optional)
proxy_auth (aiohttp.BasicAuth) – an object that represents proxy HTTP Basic Authorization (optional)
timeout (int) –
override the session’s timeout.

Changed in version 3.3: The parameter is ClientTimeout instance, float is still supported for sake of backward compatibility.

If float is passed it is a total timeout (in seconds).
ssl –

SSL validation mode. True for default SSL check
(ssl.create_default_context() is used), False for skip SSL certificate validation, aiohttp.Fingerprint for fingerprint validation, ssl.SSLContext for custom SSL certificate validation.

Supersedes verify_ssl, ssl_context and fingerprint parameters.

Added in version 3.0.
server_hostname (str) –
Sets or overrides the host name that the target server’s certificate will be matched against.

See asyncio.loop.create_connection() for more information.

Added in version 3.9.
proxy_headers (collections.abc.Mapping) –
HTTP headers to send to the proxy if the parameter proxy has been provided.

Added in version 2.3.
trace_request_ctx –
Object used to give as a kw param for each new TraceConfig object instantiated, used to give information to the tracers that is only available at request time.

Added in version 3.0.
middlewares –

A sequence of middleware instances to apply to this request only.
Each middleware must match the ClientMiddlewareType signature. None by default which uses session middlewares. See Client Middleware for more information.

Added in version 3.12.
read_bufsize (int) –

Size of the read buffer (ClientResponse.content).
None by default, it means that the session global value is used.

Added in version 3.7.
auto_decompress (bool) – Automatically decompress response body. Overrides ClientSession.auto_decompress. May be used to enable/disable auto decompression on a per-request basis.
max_line_size (int) – Maximum allowed size of lines in responses.
max_field_size (int) – Maximum allowed size of header fields in responses.

Return ClientResponse:

a client response object.

async get(url, *, allow_redirects=True, **kwargs)[source]¶

Perform a GET request. Returns an async context manager.

In order to modify inner request parameters, provide kwargs.

Parameters:

url – Request URL, str or URL
allow_redirects (bool) – Whether to process redirects or not. When True, redirects are followed and logged into ClientResponse.history. When False, the original response is returned. True by default (optional).

Return ClientResponse:

a client response object.

async post(url, *, data=None, **kwargs)[source]¶

Perform a POST request. Returns an async context manager.

In order to modify inner request parameters, provide kwargs.

Parameters:

url – Request URL, str or URL
data – Data to send in the body of the request; see request for details (optional)

Return ClientResponse:

a client response object.

async put(url, *, data=None, **kwargs)[source]¶

Perform a PUT request. Returns an async context manager.

In order to modify inner request parameters, provide kwargs.

Parameters:

url – Request URL, str or URL
data – Data to send in the body of the request; see request for details (optional)

Return ClientResponse:

a client response object.

async delete(url, **kwargs)[source]¶

Perform a DELETE request. Returns an async context manager.

In order to modify inner request parameters, provide kwargs.

Parameters:: url – Request URL, str or URL
Return ClientResponse:: a client response object.

async head(url, *, allow_redirects=False, **kwargs)[source]¶

Perform a HEAD request. Returns an async context manager.

In order to modify inner request parameters, provide kwargs.

Parameters:

url – Request URL, str or URL
allow_redirects (bool) – Whether to process redirects or not. When True, redirects are followed and logged into ClientResponse.history. When False, the original response is returned. False by default (optional).

Return ClientResponse:

a client response object.

async options(url, *, allow_redirects=True, **kwargs)[source]¶

Perform an OPTIONS request. Returns an async context manager.

In order to modify inner request parameters, provide kwargs.

Parameters:

url – Request URL, str or URL
allow_redirects (bool) – Whether to process redirects or not. When True, redirects are followed and logged into ClientResponse.history. When False, the original response is returned. True by default (optional).

Return ClientResponse:

a client response object.

async patch(url, *, data=None, **kwargs)[source]¶

Perform a PATCH request. Returns an async context manager.

In order to modify inner request parameters, provide kwargs.

Parameters:

url – Request URL, str or URL
data – Data to send in the body of the request; see request for details (optional)

Return ClientResponse:

a client response object.

async ws_connect(url, *, method='GET', protocols=(), timeout=sentinel, auth=None, autoclose=True, autoping=True, heartbeat=None, origin=None, params=None, headers=None, proxy=None, proxy_auth=None, ssl=True, verify_ssl=None, fingerprint=None, ssl_context=None, proxy_headers=None, compress=0, max_msg_size=4194304)[source]¶

Create a websocket connection. Returns a ClientWebSocketResponse async context manager object.

Parameters:

url – Websocket server url, URL or str that will be encoded with URL (see URL to skip encoding).
protocols (tuple) – Websocket protocols
timeout – a ClientWSTimeout timeout for websocket. By default, the value ClientWSTimeout(ws_receive=None, ws_close=10.0) is used (10.0 seconds for the websocket to close). None means no timeout will be used.
auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional)
autoclose (bool) – Automatically close websocket connection on close message from server. If autoclose is False then close procedure has to be handled manually. True by default
autoping (bool) – automatically send pong on ping message from server. True by default
heartbeat (float) – Send ping message every heartbeat seconds and wait pong response, if pong response is not received then close connection. The timer is reset on any data reception.(optional)
origin (str) – Origin header to send to server(optional)
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:
- collections.abc.Mapping e.g. dict, multidict.MultiDict or multidict.MultiDictProxy
- collections.abc.Iterable e.g. tuple or list
- str with preferably url-encoded content (Warning: content will not be encoded by aiohttp)
headers (dict) – HTTP Headers to send with the request (optional)
proxy (str) – Proxy URL, str or URL (optional)
proxy_auth (aiohttp.BasicAuth) – an object that represents proxy HTTP Basic Authorization (optional)
ssl –

SSL validation mode. True for default SSL check
(ssl.create_default_context() is used), False for skip SSL certificate validation, aiohttp.Fingerprint for fingerprint validation, ssl.SSLContext for custom SSL certificate validation.

Supersedes verify_ssl, ssl_context and fingerprint parameters.

Added in version 3.0.
verify_ssl (bool) –
Perform SSL certificate validation for HTTPS requests (enabled by default). May be disabled to skip validation for sites with invalid certificates.

Added in version 2.3.

Deprecated since version 3.0: Use ssl=False
fingerprint (bytes) –
Pass the SHA256 digest of the expected certificate in DER format to verify that the certificate the server presents matches. Useful for certificate pinning.

Note: use of MD5 or SHA1 digests is insecure and deprecated.

Added in version 2.3.

Deprecated since version 3.0: Use ssl=aiohttp.Fingerprint(digest)
ssl_context (ssl.SSLContext) –
ssl context used for processing HTTPS requests (optional).

ssl_context may be used for configuring certification authority channel, supported SSL options etc.

Added in version 2.3.

Deprecated since version 3.0: Use ssl=ssl_context
proxy_headers (dict) –
HTTP headers to send to the proxy if the parameter proxy has been provided.

Added in version 2.3.
compress (int) –

Enable Per-Message Compress Extension support.
0 for disable, 9 to 15 for window bit support. Default value is 0.

Added in version 2.3.
max_msg_size (int) –

maximum size of read websocket message,
4 MB by default. To disable the size limit use 0.

Added in version 3.3.
method (str) –

HTTP method to establish WebSocket connection,
'GET' by default.

Added in version 3.5.

async close()[source]¶

Close underlying connector.

Release all acquired resources.

detach()[source]¶

Detach connector from session without closing the former.

Session is switched to closed state anyway.

Basic API¶

While we encourage 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.

async aiohttp.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, version=aiohttp.HttpVersion11, connector=None)[source]¶

Asynchronous context manager for performing an asynchronous HTTP request. Returns a ClientResponse response object. Use as an async context manager.

Parameters:

method (str) – HTTP method
url – Request URL, URL or str that will be encoded with URL (see URL to skip encoding).
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:
- collections.abc.Mapping e.g. dict,
  multidict.MultiDict or multidict.MultiDictProxy
- collections.abc.Iterable e.g. tuple or
  list
- str with preferably url-encoded content
  (Warning: content will not be encoded by aiohttp)
data – The data to send in the body of the request. This can be a FormData object or anything that can be passed into FormData, e.g. a dictionary, bytes, or file-like object. (optional)
json – Any json compatible python object (optional). json and data parameters could not be used at the same time.
cookies (dict) – HTTP Cookies to send with the request (optional)
headers (dict) – HTTP Headers to send with the request (optional)
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 str or istr (optional)
auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional)
allow_redirects (bool) – Whether to process redirects or not. When True, redirects are followed (up to max_redirects times) and logged into ClientResponse.history and trace_configs. When False, the original response is returned. True by default (optional).
max_redirects (int) – Maximum number of redirects to follow. TooManyRedirects is raised if the number is exceeded. Ignored when allow_redirects=False. 10 by default.
compress (bool) – 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).
chunked (int) – 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).
expect100 (bool) – Expect 100-continue response from server. False by default (optional).
raise_for_status (bool) –

Automatically call
ClientResponse.raise_for_status() for response if set to True. If set to None value from ClientSession will be used. None by default (optional).

Added in version 3.4.
read_until_eof (bool) – Read response until EOF if response does not have Content-Length header. True by default (optional).
proxy – Proxy URL, str or URL (optional)
proxy_auth (aiohttp.BasicAuth) – an object that represents proxy HTTP Basic Authorization (optional)
timeout – a ClientTimeout settings structure, 300 seconds (5min) total timeout, 30 seconds socket connect timeout by default.
ssl –
SSL validation mode. True for default SSL check (ssl.create_default_context() is used), False for skip SSL certificate validation, aiohttp.Fingerprint for fingerprint validation, ssl.SSLContext for custom SSL certificate validation.

Supersedes verify_ssl, ssl_context and fingerprint parameters.
server_hostname (str) –
Sets or overrides the host name that the target server’s certificate will be matched against.

See asyncio.loop.create_connection() for more information.
proxy_headers (collections.abc.Mapping) – HTTP headers to send to the proxy if the parameter proxy has been provided.
trace_request_ctx – Object used to give as a kw param for each new TraceConfig object instantiated, used to give information to the tracers that is only available at request time.
read_bufsize (int) –

Size of the read buffer (ClientResponse.content).
None by default, it means that the session global value is used.

Added in version 3.7.
auto_decompress (bool) – Automatically decompress response body. May be used to enable/disable auto decompression on a per-request basis.
max_line_size (int) – Maximum allowed size of lines in responses.
max_field_size (int) – Maximum allowed size of header fields in responses.
version (aiohttp.protocol.HttpVersion) – Request HTTP version, HTTP 1.1 by default. (optional)
connector (aiohttp.BaseConnector) – BaseConnector sub-class instance to support connection pooling. (optional)

Return ClientResponse:

a client response 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¶

Connectors are transports for aiohttp client API.

There are standard connectors:

TCPConnector for regular TCP sockets (both HTTP and HTTPS schemes supported).
UnixConnector for connecting via UNIX socket (it’s used mostly for testing purposes).

All connector classes should be derived from BaseConnector.

By default all connectors support keep-alive connections (behavior is controlled by force_close constructor’s parameter).

class aiohttp.BaseConnector(*, keepalive_timeout=15, force_close=False, limit=100, limit_per_host=0, enable_cleanup_closed=False, loop=None)[source]¶

Base class for all connectors.

Parameters:

keepalive_timeout (float) – timeout for connection reusing after releasing (optional). Values 0. For disabling keep-alive feature use force_close=True flag.
limit (int) – total number simultaneous connections. If limit is 0 the connector has no limit (default: 100).
limit_per_host (int) – limit simultaneous connections to the same endpoint. Endpoints are the same if they are have equal (host, port, is_ssl) triple. If limit is 0 the connector has no limit (default: 0).
force_close (bool) – close underlying sockets after connection releasing (optional).
enable_cleanup_closed (bool) –
some SSL servers do not properly complete SSL shutdown process, in that case asyncio leaks SSL connections. If this parameter is set to True, aiohttp additionally aborts underlining transport after 2 seconds. It is off by default.

For Python version 3.12.7+, or 3.13.1 and later, this parameter is ignored because the asyncio SSL connection leak is fixed in these versions of Python.
loop –
event loop used for handling connections. If param is None, asyncio.get_event_loop() is used for getting default event loop.

Deprecated since version 2.0.

closed¶: Read-only property, True if connector is closed.

force_close¶: Read-only property, True if connector should ultimately close connections on releasing.

limit¶: The total number for simultaneous connections. If limit is 0 the connector has no limit. The default limit size is 100.

limit_per_host¶

The limit for simultaneous connections to the same endpoint.

Endpoints are the same if they are have equal (host, port, is_ssl) triple.

If limit_per_host is 0 the connector has no limit per host.

Read-only property.

async close()[source]¶: Close all opened connections.

async connect(request)[source]¶

Get a free connection from pool or create new one if connection is absent in the pool.

The call may be paused if limit is exhausted until used connections returns to pool.

Parameters:: request (aiohttp.ClientRequest) – request object which is connection initiator.
Returns:: Connection object.

async _create_connection(req)[source]¶: Abstract method for actual connection establishing, should be overridden in subclasses.

class aiohttp.AddrInfoType¶: Refer to 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 aiohappyeyeballs in the future.

class aiohttp.SocketFactoryType¶: Refer to 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 aiohappyeyeballs in the future.

class aiohttp.TCPConnector(*, ssl=True, verify_ssl=True, fingerprint=None, use_dns_cache=True, ttl_dns_cache=10, family=0, ssl_context=None, local_addr=None, resolver=None, keepalive_timeout=sentinel, force_close=False, limit=100, limit_per_host=0, enable_cleanup_closed=False, timeout_ceil_threshold=5, happy_eyeballs_delay=0.25, interleave=None, loop=None, socket_factory=None, ssl_shutdown_timeout=0)[source]¶

Connector for working with HTTP and HTTPS via TCP sockets.

The most common transport. When you don’t know what connector type to use, use a TCPConnector instance.

TCPConnector inherits from BaseConnector.

Constructor accepts all parameters suitable for BaseConnector plus several TCP-specific ones:

param ssl:

SSL validation mode. True for default SSL check
(ssl.create_default_context() is used), False for skip SSL certificate validation, aiohttp.Fingerprint for fingerprint validation, ssl.SSLContext for custom SSL certificate validation.

Supersedes verify_ssl, ssl_context and fingerprint parameters.

Added in version 3.0.

Parameters:

verify_ssl (bool) –
perform SSL certificate validation for HTTPS requests (enabled by default). May be disabled to skip validation for sites with invalid certificates.

Deprecated since version 2.3: Pass verify_ssl to ClientSession.get() etc.
fingerprint (bytes) –
pass the SHA256 digest of the expected certificate in DER format to verify that the certificate the server presents matches. Useful for certificate pinning.

Note: use of MD5 or SHA1 digests is insecure and deprecated.

Deprecated since version 2.3: Pass verify_ssl to ClientSession.get() etc.
use_dns_cache (bool) –
use internal cache for DNS lookups, True by default.

Enabling an option may speedup connection establishing a bit but may introduce some side effects also.
ttl_dns_cache (int) –
expire after some seconds the DNS entries, None means cached forever. By default 10 seconds (optional).

In some environments the IP addresses related to a specific HOST can change after a specific time. Use this option to keep the DNS cache updated refreshing each entry after N seconds.
limit (int) – total number simultaneous connections. If limit is 0 the connector has no limit (default: 100).
limit_per_host (int) – limit simultaneous connections to the same endpoint. Endpoints are the same if they are have equal (host, port, is_ssl) triple. If limit is 0 the connector has no limit (default: 0).
resolver (aiohttp.abc.AbstractResolver) –
custom resolver instance to use. aiohttp.DefaultResolver by default (asynchronous if aiodns>=1.1 is installed).

Custom resolvers allow to resolve hostnames differently than the way the host is configured.

The resolver is aiohttp.ThreadedResolver by default, asynchronous version is pretty robust but might fail in very rare cases.
family (int) –
TCP socket family, both IPv4 and IPv6 by default. For IPv4 only use socket.AF_INET, for IPv6 only – socket.AF_INET6.

family is 0 by default, that means both IPv4 and IPv6 are accepted. To specify only concrete version please pass socket.AF_INET or socket.AF_INET6 explicitly.
ssl_context (ssl.SSLContext) –
SSL context used for processing HTTPS requests (optional).

ssl_context may be used for configuring certification authority channel, supported SSL options etc.
local_addr (tuple) – tuple of (local_host, local_port) used to bind socket locally if specified.
force_close (bool) – close underlying sockets after connection releasing (optional).
enable_cleanup_closed (bool) – Some ssl servers do not properly complete SSL shutdown process, in that case asyncio leaks SSL connections. If this parameter is set to True, aiohttp additionally aborts underlining transport after 2 seconds. It is off by default.
happy_eyeballs_delay (float) –
The amount of time in seconds to wait for a connection attempt to complete, before starting the next attempt in parallel. This is the “Connection Attempt Delay” as defined in RFC 8305. To disable Happy Eyeballs, set this to None. The default value recommended by the RFC is 0.25 (250 milliseconds).

Added in version 3.10.
interleave (int) –
controls address reordering when a host name resolves to multiple IP addresses. If 0 or unspecified, no reordering is done, and addresses are tried in the order returned by the resolver. If a positive integer is specified, the addresses are interleaved by address family, and the given integer is interpreted as “First Address Family Count” as defined in RFC 8305. The default is 0 if happy_eyeballs_delay is not specified, and 1 if it is.

Added in version 3.10.
socket_factory (SocketFactoryType) –
This function takes an AddrInfoType and is used in lieu of socket.socket() when creating TCP connections.

Added in version 3.12.
ssl_shutdown_timeout (float) –
(DEPRECATED) This parameter is deprecated and will be removed in aiohttp 4.0. Grace period for SSL shutdown on TLS connections when the connector is closed (0 seconds by default). By default (0), SSL connections are aborted immediately when the connector is closed, without performing the shutdown handshake. During normal operation, SSL connections use Python’s default SSL shutdown behavior. Setting this to a positive value (e.g., 0.1) will perform a graceful shutdown when closing the connector, notifying the remote server which can help prevent “connection reset” errors at the cost of additional cleanup time. Note: On Python versions prior to 3.11, only a value of 0 is supported; other values will trigger a warning.

Added in version 3.12.5.

Changed in version 3.12.11: Changed default from 0.1 to 0 to abort SSL connections immediately when the connector is closed. Added support for ssl_shutdown_timeout=0 on all Python versions. A RuntimeWarning is issued when non-zero values are passed on Python < 3.11.

Deprecated since version 3.12.11: This parameter is deprecated and will be removed in aiohttp 4.0.

family¶

TCP socket family e.g. socket.AF_INET or socket.AF_INET6

Read-only property.

dns_cache¶

Use quick lookup in internal DNS cache for host names if True.

Read-only bool property.

cached_hosts¶

The cache of resolved hosts if dns_cache is enabled.

Read-only types.MappingProxyType property.

clear_dns_cache(self, host=None, port=None)[source]¶

Clear internal DNS cache.

Remove specific entry if both host and port are specified, clear all cache otherwise.

class aiohttp.UnixConnector(path, *, conn_timeout=None, keepalive_timeout=30, limit=100, force_close=False, loop=None)[source]¶

Unix socket connector.

Use UnixConnector for sending HTTP/HTTPS requests through UNIX Sockets as underlying transport.

UNIX sockets are handy for writing tests and making very fast connections between processes on the same host.

UnixConnector is inherited from BaseConnector.

Usage:

conn = UnixConnector(path='/path/to/socket')
session = ClientSession(connector=conn)
async with session.get('http://python.org') as resp:
    ...

Constructor accepts all parameters suitable for BaseConnector plus UNIX-specific one:

Parameters:: path (str) – Unix socket path

path¶: Path to UNIX socket, read-only str property.

class aiohttp.Connection¶

Encapsulates single connection in connector object.

End user should never create Connection instances manually but get it by BaseConnector.connect() coroutine.

closed¶: bool read-only property, True if connection was closed, released or detached.

loop¶: Event loop used for connection

Deprecated since version 3.5.

transport¶: Connection transport

close()¶: Close connection with forcibly closing underlying socket.

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.

Response object¶

class aiohttp.ClientResponse[source]¶

Client response returned by aiohttp.ClientSession.request() and family.

User never creates the instance of ClientResponse class but gets it from API calls.

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 release() method).

version¶: Response’s version, HttpVersion instance.

status¶: HTTP status code of response (int), e.g. 200.

reason¶: HTTP status reason of response (str), e.g. "OK".

ok¶: Boolean representation of HTTP status code (bool). True if status is less than 400; otherwise, False.

method¶: Request’s method (str).

url¶: URL of request (URL).

real_url¶: Unmodified URL of request with URL fragment unstripped (URL).

Added in version 3.2.

connection¶: Connection used for handling response.

content¶

Payload stream, which contains response’s BODY (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 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.

cookies¶: HTTP cookies of response (Set-Cookie HTTP header, SimpleCookie).

Note

Since 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 response.headers.getall('Set-Cookie').

The session’s cookie jar will correctly store all cookies, even if they are not accessible via this attribute.

headers¶: A case-insensitive multidict proxy with HTTP headers of response, CIMultiDictProxy.

raw_headers¶: Unmodified HTTP headers of response as unconverted bytes, a sequence of (key, value) pairs.

links¶

Link HTTP header parsed into a MultiDictProxy.

For each link, key is link param rel when it exists, or link url as str otherwise, and value is MultiDictProxy of link params and url at key url as URL instance.

Added in version 3.2.

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 headers or raw_headers, e.g. 'Content-Type' not in resp.headers.

charset¶

Read-only property that specifies the encoding for the request’s BODY.

The value is parsed from the Content-Type HTTP header.

Returns str like 'utf-8' or None if no Content-Type header present in HTTP headers or it has no charset information.

content_disposition¶

Read-only property that specified the Content-Disposition HTTP header.

Instance of ContentDisposition or None if no Content-Disposition header present in HTTP headers.

history¶: A Sequence of ClientResponse objects of preceding requests (earliest request first) if there were redirects, an empty sequence otherwise.

close()[source]¶

Close response and underlying connection.

For keep-alive support see release().

async read()[source]¶

Read the whole response’s body as bytes.

Close underlying connection if data reading gets an error, release connection otherwise.

Raise an aiohttp.ClientResponseError if the data can’t be read.

Return bytes:: read BODY.

ClientWebSocketResponse¶

To connect to a websocket server aiohttp.ws_connect() or aiohttp.ClientSession.ws_connect() coroutines should be used, do not create an instance of class ClientWebSocketResponse manually.

class aiohttp.ClientWebSocketResponse[source]¶

Class for handling client-side websockets.

closed¶: Read-only property, True if close() has been called or CLOSE message has been received from peer.

protocol¶

Websocket subprotocol chosen after start() call.

May be None if server and client protocols are not overlapping.

get_extra_info(name, default=None)[source]¶

Reads optional extra information from the connection’s transport. If no value associated with name is found, default is returned.

See asyncio.BaseTransport.get_extra_info()

Parameters:

name (str) – The key to look up in the transport extra information.
default – Default value to be used when no value for name is found (default is None).

exception()[source]¶: Returns exception if any occurs or returns None.

async ping(message=b'')[source]¶

Send PING to peer.

Parameters:: message – optional payload of ping message, str (converted to UTF-8 encoded bytes) or bytes.

Changed in version 3.0: The method is converted into coroutine

async pong(message=b'')[source]¶

Send PONG to peer.

Parameters:: message – optional payload of pong message, str (converted to UTF-8 encoded bytes) or bytes.

Changed in version 3.0: The method is converted into coroutine

async send_str(data, compress=None)[source]¶

Send data to peer as TEXT message.

Parameters:

data (str) – data to send.
compress (int) – sets specific level of compression for single message, None for not overriding per-socket setting.

Raises:

TypeError – if data is not str

Changed in version 3.0: The method is converted into coroutine, compress parameter added.

async send_bytes(data, compress=None)[source]¶

Send data to peer as BINARY message.

Parameters:

data – data to send.
compress (int) – sets specific level of compression for single message, None for not overriding per-socket setting.

Raises:

TypeError – if data is not bytes, bytearray or memoryview.

Changed in version 3.0: The method is converted into coroutine, compress parameter added.

async send_json(data, compress=None, *, dumps=json.dumps)[source]¶

Send data to peer as JSON string.

Parameters:

data – data to send.
compress (int) – sets specific level of compression for single message, None for not overriding per-socket setting.
dumps (collections.abc.Callable) – any callable that accepts an object and returns a JSON string (json.dumps() by default).

Raises:

RuntimeError – if connection is not started or closing
ValueError – if data is not serializable object
TypeError – if value returned by dumps(data) is not str

Changed in version 3.0: The method is converted into coroutine, compress parameter added.

async send_frame(message, opcode, compress=None)[source]¶

Send a 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 send_str(), send_bytes() or 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.

Parameters:

message (bytes) – message to send.
opcode (WSMsgType) – opcode of the message.
compress (int) – sets specific level of compression for single message, None for not overriding per-socket setting.

Added in version 3.11.

async close(*, code=WSCloseCode.OK, message=b'')[source]¶

A coroutine that initiates closing handshake by sending 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().

Parameters:

code (int) – closing code. See also WSCloseCode.
message – optional payload of close message, str (converted to UTF-8 encoded bytes) or bytes.

async receive()[source]¶

A coroutine that waits upcoming data message from peer and returns it.

The coroutine implicitly handles PING, PONG and CLOSE without returning the message.

It process ping-pong game and performs closing handshake internally.

Returns:: WSMessage

async receive_str()[source]¶

A coroutine that calls receive() but also asserts the message type is TEXT.

Return str:: peer’s message content.
Raises:: aiohttp.WSMessageTypeError – if message is not TEXT.

async receive_bytes()[source]¶

A coroutine that calls receive() but also asserts the message type is BINARY.

Return bytes:: peer’s message content.
Raises:: aiohttp.WSMessageTypeError – if message is not BINARY.

async receive_json(*, loads=json.loads)[source]¶

A coroutine that calls receive_str() and loads the JSON string to a Python dict.

Parameters:

loads (collections.abc.Callable) – any callable that accepts str and returns dict with parsed JSON (json.loads() by default).

Return dict:

loaded JSON content

Raises:

TypeError – if message is BINARY.
ValueError – if message is not valid JSON.

ClientRequest¶

class aiohttp.ClientRequest[source]¶

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 ClientSession methods and passed to middleware.

For more information about using middleware, see Client Middleware.

body: 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 update_body() instead:

# 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.

chunked: bool | None¶

Whether to use chunked transfer encoding:

True: Use chunked encoding
False: Don’t use chunked encoding
None: Automatically determine based on body

compress: 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.

headers: multidict.CIMultiDict¶

The HTTP headers that will be sent with the request. This is a case-insensitive multidict that can be modified by middleware.

# Add or modify headers
request.headers['X-Custom-Header'] = 'value'
request.headers['User-Agent'] = 'MyApp/1.0'

is_ssl: bool[source]¶: True if the request uses a secure scheme (e.g., HTTPS, WSS), False otherwise.

method: str¶: The HTTP method of the request (e.g., 'GET', 'POST', 'PUT', etc.).

original_url: yarl.URL¶: The original URL passed to the request method, including any fragment. This preserves the exact URL as provided by the user.

proxy: yarl.URL | None¶: The proxy URL if the request will be sent through a proxy, None otherwise.

proxy_headers: multidict.CIMultiDict | None¶: Headers to be sent to the proxy server (e.g., Proxy-Authorization). Only set when proxy is not None.

response_class: type[ClientResponse]¶: The class to use for creating the response object. Defaults to ClientResponse but can be customized for special handling.

server_hostname: str | None¶: Override the hostname for SSL certificate verification. Useful when connecting through proxies or to IP addresses.

session: 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.

ssl: ssl.SSLContext | bool | Fingerprint¶

SSL validation configuration for this request:

True: Use default SSL verification
False: Skip SSL verification
ssl.SSLContext: Custom SSL context
Fingerprint: Verify specific certificate fingerprint

url: 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 original_url.

version: HttpVersion¶: The HTTP version to use for the request (e.g., HttpVersion(1, 1) for HTTP/1.1).

update_body(body)[source]¶

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 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.

Parameters:

body –

The new body content. Can be:

bytes/bytearray: Raw binary data
str: Text data (encoded using charset from Content-Type)
FormData: Form data encoded as multipart/form-data
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

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 FormData or 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.

Added in version 3.12.

Utilities¶

class aiohttp.ClientTimeout(*, total=None, connect=None, sock_connect=None, sock_read=None)[source]¶

A data class for client timeout settings.

See Timeouts for usage examples.

total¶

Total number of seconds for the whole request.

float, None by default.

connect¶

Maximal number of seconds for acquiring a connection from pool. The time consists connection establishment for a new connection or waiting for a free connection from a pool if pool connection limits are exceeded.

For pure socket connection establishment time use sock_connect.

float, None by default.

sock_connect¶

Maximal number of seconds for connecting to a peer for a new connection, not given from a pool. See also connect.

float, None by default.

sock_read¶

Maximal number of seconds for reading a portion of data from a peer.

float, None by default.

class aiohttp.ClientWSTimeout(*, ws_receive=None, ws_close=None)[source]¶

A data class for websocket client timeout settings.

ws_receive¶

A timeout for websocket to receive a complete message.

float, None by default.

ws_close¶

A timeout for the websocket to close.

float, 10.0 by default.

Added in version 4.0.

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.

Changed in version 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.

class aiohttp.ETag(name, is_weak=False)[source]¶

Represents ETag identifier.

value¶: Value of corresponding etag without quotes.

is_weak¶: Flag indicates that etag is weak (has W/ prefix).

Added in version 3.8.

class aiohttp.ContentDisposition¶

A data class to represent the Content-Disposition header, available as ClientResponse.content_disposition attribute.

type¶

A str instance. Value of Content-Disposition header itself, e.g. attachment.

filename¶

A str instance. Content filename extracted from parameters. May be None.

parameters¶

Read-only mapping contains all parameters.

class aiohttp.RequestInfo[source]¶

A typing.NamedTuple with request URL and headers from ClientRequest object, available as ClientResponse.request_info attribute.

url¶: Requested url, yarl.URL instance.

method¶: Request HTTP method like 'GET' or 'POST', str.

headers¶: HTTP headers for request, multidict.CIMultiDict instance.

real_url¶: Requested url with URL fragment unstripped, yarl.URL instance.

Added in version 3.2.

class aiohttp.BasicAuth(login, password='', encoding='latin1')[source]¶

HTTP basic authentication helper.

Parameters:

login (str) – login
password (str) – password
encoding (str) – encoding ('latin1' by default)

Should be used for specifying authorization data in client API, e.g. auth parameter for ClientSession.request().

classmethod decode(auth_header, encoding='latin1')[source]¶

Decode HTTP basic authentication credentials.

Parameters:

auth_header (str) – The Authorization header to decode.
encoding (str) – (optional) encoding (‘latin1’ by default)

Returns:

decoded authentication data, BasicAuth.

classmethod from_url(url)[source]¶

Constructed credentials info from url’s user and password parts.

Returns:: credentials data, BasicAuth or None is credentials are not provided.

Added in version 2.3.

encode()[source]¶

Encode credentials into string suitable for Authorization header etc.

Returns:: encoded authentication data, str.

class aiohttp.DigestAuthMiddleware(login, password, *, preemptive=True)[source]¶

HTTP digest authentication client middleware.

Parameters:

login (str) – login
password (str) – password
preemptive (bool) – Enable preemptive authentication (default: True)

This middleware supports HTTP digest authentication with both auth and auth-int quality of protection (qop) modes, and a variety of hashing algorithms.

It automatically handles the digest authentication handshake by:

Parsing 401 Unauthorized responses with WWW-Authenticate: Digest headers
Generating appropriate Authorization: Digest headers on retry
Maintaining nonce counts and challenge data per request
When preemptive=True, reusing authentication credentials for subsequent requests to the same protection space (following RFC 7616 Section 3.6)

Preemptive Authentication

By default (preemptive=True), the middleware remembers successful authentication challenges and automatically includes the Authorization header in subsequent requests to the same protection space. This behavior:

Improves server efficiency by avoiding extra round trips
Matches how modern web browsers handle digest authentication
Follows the recommendation in RFC 7616 Section 3.6

The server may still respond with a 401 status and stale=true if the nonce has expired, in which case the middleware will automatically retry with the new nonce.

To disable preemptive authentication and require a 401 challenge for every request, set preemptive=False:

# Default behavior - preemptive auth enabled
digest_auth_middleware = DigestAuthMiddleware(login="user", password="pass")

# Disable preemptive auth - always wait for 401 challenge
digest_auth_middleware = DigestAuthMiddleware(login="user", password="pass",
                                               preemptive=False)

Usage:

digest_auth_middleware = DigestAuthMiddleware(login="user", password="pass")
async with ClientSession(middlewares=(digest_auth_middleware,)) as session:
    async with session.get("http://protected.example.com") as resp:
        # The middleware automatically handles the digest auth handshake
        assert resp.status == 200

    # Subsequent requests include auth header preemptively
    async with session.get("http://protected.example.com/other") as resp:
        assert resp.status == 200  # No 401 round trip needed

Added in version 3.12.

Changed in version 3.12.8: Added preemptive parameter to enable/disable preemptive authentication.

class aiohttp.CookieJar(*, unsafe=False, quote_cookie=True, treat_as_secure_origin=[])[source]¶

The cookie jar instance is available as ClientSession.cookie_jar.

The jar contains 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 collections.abc.Iterable, collections.abc.Sized and aiohttp.abc.AbstractCookieJar interfaces.

Implements cookie storage adhering to RFC 6265.

Parameters:

unsafe (bool) – (optional) Whether to accept cookies from IPs.
quote_cookie (bool) –

(optional) Whether to quote cookies according to
RFC 2109. Some backend systems (not compatible with RFC mentioned above) does not support quoted cookies.

Added in version 3.7.
treat_as_secure_origin –
(optional) Mark origins as secure
for cookies marked as Secured. Possible types are

Possible types are:
- tuple or list of str or yarl.URL
- str
- yarl.URL
Added in version 3.8.

update_cookies(cookies, response_url=None)[source]¶

Update cookies returned by server in Set-Cookie header.

Parameters:

cookies – a collections.abc.Mapping (e.g. dict, SimpleCookie) or iterable of pairs with cookies returned by server’s response.
response_url (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.

filter_cookies(request_url)[source]¶

Return jar’s cookies acceptable for URL and available in Cookie header for sending client requests for given URL.

Parameters:: response_url (URL) – request’s URL for which cookies are asked.
Returns:: http.cookies.SimpleCookie with filtered cookies for given URL.

save(file_path)[source]¶

Write a pickled representation of cookies into the file at provided path.

Parameters:: file_path – Path to file where cookies will be serialized, str or pathlib.Path instance.

load(file_path)[source]¶

Load a pickled representation of cookies from the file at provided path.

Parameters:: file_path – Path to file from where cookies will be imported, str or pathlib.Path instance.

clear(predicate=None)[source]¶

Removes all cookies from the jar if the predicate is None. Otherwise remove only those Morsel that predicate(morsel) returns True.

Parameters:

predicate –

callable that gets Morsel as a parameter and returns True if this Morsel must be deleted from the jar.

Added in version 4.0.

clear_domain(domain)[source]¶

Remove all cookies from the jar that belongs to the specified domain or its subdomains.

Parameters:: domain (str) – domain for which cookies must be deleted from the jar.

Added in version 4.0.

class aiohttp.DummyCookieJar(*, loop=None)[source]¶

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())

class aiohttp.Fingerprint(digest)[source]¶

Fingerprint helper for checking SSL certificates by SHA256 digest.

Parameters:: digest (bytes) – SHA256 digest for certificate in DER-encoded binary form (see ssl.SSLSocket.getpeercert()).

To check fingerprint pass the object into 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))

Added in version 3.0.

aiohttp.set_zlib_backend(lib)[source]¶

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.

Parameters:: lib (types.ModuleType) – 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 zlib, zlib_ng.zlib_ng, and isal.isal_zlib.

Added in version 3.12.

FormData¶

A 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 io.IOBase object or was added with at least one optional argument to add_field (content_type, filename, or content_transfer_encoding). Otherwise, application/x-www-form-urlencoded is used.

FormData instances are callable and return a aiohttp.payload.Payload on being called.

class aiohttp.FormData(fields, quote_fields=True, charset=None)[source]¶

Helper class for multipart/form-data and application/x-www-form-urlencoded body generation.

Parameters:

fields –

A container for the key/value pairs of this form.

Possible types are:

dict
tuple or list
io.IOBase, e.g. a file-like object
multidict.MultiDict or multidict.MultiDictProxy

If it is a tuple or list, it must be a valid argument for add_fields.

For dict, multidict.MultiDict, and multidict.MultiDictProxy, the keys and values must be valid name and value arguments to add_field, respectively.

add_field(name, value, content_type=None, filename=None, content_transfer_encoding=None)[source]¶

Add a field to the form.

Parameters:

name (str) – Name of the field
value –
Value of the field

Possible types are:
- str
- bytes, bytearray, or memoryview
- io.IOBase, e.g. a file-like object
content_type (str) – The field’s content-type header (optional)
filename (str) –
The field’s filename (optional)

If this is not set and value is a bytes, bytearray, or 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 io.IOBase object, the filename is extracted from the object if possible.
content_transfer_encoding (str) – The field’s content-transfer-encoding header (optional)

add_fields(fields)[source]¶

Add one or more fields to the form.

Parameters:

fields –

An iterable containing:

io.IOBase, e.g. a file-like object
multidict.MultiDict or multidict.MultiDictProxy
tuple or list of length two, containing a name-value pair

Client exceptions¶

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 ValueError or TypeError.

Reading a response content may raise a 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 aiohttp.ClientError[source]¶

Base class for all client specific exceptions.

Derived from Exception

class aiohttp.ClientPayloadError[source]¶

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-Length HTTP header.

Derived from ClientError

exception aiohttp.InvalidURL[source]¶

URL used for fetching is malformed, e.g. it does not contain host part.

Derived from ClientError and ValueError

url¶

Invalid URL, yarl.URL instance.

description¶: Invalid URL description, str instance or None.

exception aiohttp.InvalidUrlClientError[source]¶

Base class for all errors related to client url.

Derived from InvalidURL

exception aiohttp.RedirectClientError[source]¶

Base class for all errors related to client redirects.

Derived from ClientError

exception aiohttp.NonHttpUrlClientError[source]¶

Base class for all errors related to non http client urls.

Derived from ClientError

exception aiohttp.InvalidUrlRedirectClientError[source]¶

Redirect URL is malformed, e.g. it does not contain host part.

Derived from InvalidUrlClientError and RedirectClientError

exception aiohttp.NonHttpUrlRedirectClientError[source]¶

Redirect URL does not contain http schema.

Derived from RedirectClientError and NonHttpUrlClientError

Response errors¶

exception aiohttp.ClientResponseError[source]¶

These exceptions could happen after we get response from server.

Derived from ClientError

request_info¶: Instance of RequestInfo object, contains information about request.

status¶: HTTP status code of response (int), e.g. 400.

message¶: Message of response (str), e.g. "OK".

headers¶: Headers in response, a list of pairs.

history¶

History from failed response, if available, else empty tuple.

A tuple of ClientResponse objects used for handle redirection responses.

code¶: HTTP status code of response (int), e.g. 400.

Deprecated since version 3.1.

class aiohttp.ContentTypeError[source]¶

Invalid content type.

Derived from ClientResponseError

Added in version 2.3.

class aiohttp.TooManyRedirects[source]¶

Client was redirected too many times.

Maximum number of redirects can be configured by using parameter max_redirects in request.

Derived from ClientResponseError

Added in version 3.2.

class aiohttp.WSServerHandshakeError[source]¶

Web socket server response error.

Derived from ClientResponseError

exception aiohttp.WSMessageTypeError[source]¶

Received WebSocket message of unexpected type

Derived from TypeError

Connection errors¶

class aiohttp.ClientConnectionError[source]¶

These exceptions related to low-level connection problems.

Derived from ClientError

class aiohttp.ClientConnectionResetError[source]¶: Derived from ClientConnectionError and ConnectionResetError

class aiohttp.ClientOSError[source]¶

Subset of connection errors that are initiated by an OSError exception.

Derived from ClientConnectionError and OSError

class aiohttp.ClientConnectorError[source]¶

Connector related exceptions.

Derived from ClientOSError

class aiohttp.ClientConnectorDNSError[source]¶

DNS resolution error.

Derived from ClientConnectorError

class aiohttp.ClientProxyConnectionError[source]¶: Derived from ClientConnectorError

class aiohttp.ClientSSLError[source]¶: Derived from ClientConnectorError

class aiohttp.ClientConnectorSSLError[source]¶

Response ssl error.

Derived from ClientSSLError and ssl.SSLError

class aiohttp.ClientConnectorCertificateError[source]¶

Response certificate error.

Derived from ClientSSLError and ssl.CertificateError

class aiohttp.UnixClientConnectorError¶: Derived from ClientConnectorError

class aiohttp.ServerConnectionError[source]¶: Derived from ClientConnectionError

class aiohttp.ServerDisconnectedError[source]¶

Server disconnected.

Derived from ServerConnectionError

message¶: Partially parsed HTTP message (optional).

class aiohttp.ServerFingerprintMismatch[source]¶

Server fingerprint mismatch.

Derived from ServerConnectionError

class aiohttp.ServerTimeoutError[source]¶

Server operation timeout: read timeout, etc.

To catch all timeouts, including the total timeout, use asyncio.TimeoutError.

Derived from ServerConnectionError and asyncio.TimeoutError

class aiohttp.ConnectionTimeoutError[source]¶

Connection timeout on connect and sock_connect timeouts.

Derived from ServerTimeoutError

class aiohttp.SocketTimeoutError[source]¶

Reading from socket timeout on sock_read timeout.

Derived from ServerTimeoutError

Client Types¶

type aiohttp.ClientMiddlewareType¶

Type alias for client middleware functions. Middleware functions must have this signature:

Callable[
    [ClientRequest, ClientHandlerType],
    Awaitable[ClientResponse]
]

type aiohttp.ClientHandlerType¶

Type alias for client request handler functions:

Callable[[ClientRequest], Awaitable[ClientResponse]]

Client Reference¶

Client Session¶

Basic API¶

Connectors¶

Response object¶

ClientWebSocketResponse¶

ClientRequest¶

Utilities¶

FormData¶

Client exceptions¶

Response errors¶

Connection errors¶

Hierarchy of exceptions¶

Client Types¶

aiohttp

Navigation