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)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

The client session supports the context manager protocol for self closing.

class aiohttp.ClientSession(*, connector=None, loop=None, cookies=None, headers=None, skip_auto_headers=None, auth=None, json_serialize=json.dumps, version=aiohttp.HttpVersion11, cookie_jar=None, read_timeout=None, conn_timeout=None, timeout=sentinel, raise_for_status=False, connector_owner=True, auto_decompress=True, proxies=None)¶

The class for creating client sessions and making requests.

Parameters:

Parameters:	connector (aiohttp.connector.BaseConnector) – BaseConnector sub-class instance to support connection pooling. loop – event loop used for processing HTTP requests. If loop is `None` the constructor borrows it from connector if specified. `asyncio.get_event_loop()` is used for getting default event loop otherwise. Deprecated since version 2.0. 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) 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. json_serialize (callable) – Json serializer callable. By default `json.dumps()` function. raise_for_status (bool) – Automatically call `ClientResponse.raise_for_status()` for each response, `False` by default. This parameter can be overridden when you 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. timeout – a `ClientTimeout` settings structure, 5min total timeout by default. New in version 3.3. read_timeout (float) – Request operations timeout. `read_timeout` is cumulative for all request operations (request, redirects, responses, data consuming). By default, the read timeout is 560 seconds. Use `None` or `0` to disable timeout checks. Deprecated since version 3.3: Use `timeout` parameter instead. conn_timeout* (float) – timeout for connection establishing (optional). Values `0` or `None` mean no timeout. Deprecated since version 3.3: Use `timeout` parameter instead. 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. auto_decompress (bool) – Automatically decompress response body, `True` by default New in version 2.3. trust_env (bool) – Get proxies information from HTTP_PROXY / HTTPS_PROXY environment variables if the parameter is `True` (`False` by default). Get proxy credentials from `~/.netrc` file if present. See also `.netrc` documentation: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html New in version 2.3. Changed in version 3.0: Added support for `~/.netrc` file.

connector (aiohttp.connector.BaseConnector) – BaseConnector sub-class instance to support connection pooling.
loop –
event loop used for processing HTTP requests.

If loop is None the constructor borrows it from connector if specified.

asyncio.get_event_loop() is used for getting default event loop otherwise.

Deprecated since version 2.0.
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)
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.
json_serialize (callable) –
Json serializer callable.

By default json.dumps() function.
raise_for_status (bool) –
Automatically call ClientResponse.raise_for_status() for each response, False by default.

This parameter can be overridden when you 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.
timeout –

a ClientTimeout settings structure, 5min

total timeout by default.

New in version 3.3.
read_timeout (float) –
Request operations timeout. read_timeout is cumulative for all request operations (request, redirects, responses, data consuming). By default, the read timeout is 5*60 seconds. Use None or 0 to disable timeout checks.

Deprecated since version 3.3: Use timeout parameter instead.
conn_timeout (float) –
timeout for connection establishing (optional). Values 0 or None mean no timeout.

Deprecated since version 3.3: Use timeout parameter instead.
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.
auto_decompress (bool) –

Automatically decompress response body,

True by default

New in version 2.3.
trust_env (bool) –
Get proxies information from HTTP_PROXY / HTTPS_PROXY environment variables if the parameter is True (False by default).

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

See also

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

New in version 2.3.

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

closed¶

True if the session has been closed, False otherwise.

A read-only property.

connector¶

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

New in version 2.1.

Note

This parameter affects all subsequent requests.

loop¶

A loop instance used for session creation.

A read-only property.

coroutine async-with request(method, url, *, params=None, data=None, json=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=None, verify_ssl=None, fingerprint=None, ssl_context=None, proxy_headers=None)¶

Performs an asynchronous HTTP request. Returns a response object.

Parameters:

Parameters:	method (str) – HTTP method url – Request URL, `str` or `URL`. 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`, `aiohttp.MultiDict` or `aiohttp.MultiDictProxy` `collections.abc.Iterable` e.g. `tuple` or `list` `str` with preferably url-encoded content (Warning: content will not be encoded by aiohttp) data – Dictionary, bytes, or file-like object to send in the body of the request (optional) json – Any json compatible python object (optional). json and data parameters could not be used at the same time. 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) – If set to `False`, do not follow redirects. `True` by default (optional). max_redirects (int) – Maximum number of redirects to follow. `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). New 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. ssl – SSL validation mode. `None` 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. New 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. New 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. Warning: use of MD5 or SHA1 digests is insecure and removed. New 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. New in version 2.3. Deprecated since version 3.0: Use `ssl=ssl_context` proxy_headers (abc.Mapping) – HTTP headers to send to the proxy if the parameter proxy has been provided. New 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. New in version 3.0.
Return ClientResponse:
	a `client response` object.

method (str) – HTTP method
url – Request URL, str or URL.
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, aiohttp.MultiDict or aiohttp.MultiDictProxy
- collections.abc.Iterable e.g. tuple or list
- str with preferably url-encoded content (Warning: content will not be encoded by aiohttp)
data – Dictionary, bytes, or file-like object to send in the body of the request (optional)
json – Any json compatible python object (optional). json and data parameters could not be used at the same time.
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) – If set to False, do not follow redirects. True by default (optional).
max_redirects (int) – Maximum number of redirects to follow. 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).

New 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.
ssl –

SSL validation mode. None 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.

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

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

Warning: use of MD5 or SHA1 digests is insecure and removed.

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

New in version 2.3.

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

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

New in version 3.0.

Return ClientResponse:

a client response object.

coroutine async-with get(url, *, allow_redirects=True, **kwargs)¶

Perform a GET request.