Client Reference

aiohttp

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.

The class for creating client sessions and making requests.

param aiohttp.BaseConnector connector

BaseConnector sub-class instance to support connection pooling.

param loop

event loop<asyncio-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.

2.0

param dict cookies

Cookies to send with the request (optional)

param headers

HTTP Headers to send with every request (optional).

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

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. Note that Content-Length autogeneration can't be skipped.

Iterable of str or ~aiohttp.istr (optional)

param aiohttp.BasicAuth auth

an object that represents HTTP Basic Authorization (optional)

param version

supported HTTP version, HTTP 1.1 by default.

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

param callable json_serialize: Json serializer callable.

By default json.dumps function.

param bool raise_for_status

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.

param timeout: a ClientTimeout settings structure, 300 seconds (5min) total timeout by default.

3.3

param float read_timeout: 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.

3.3

Use timeout parameter instead.
param float conn_timeout: timeout for connection establishing (optional). Values 0 or None mean no timeout.

3.3

Use timeout parameter instead.
param bool connector_owner

Close connector instance on session closing.

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

param bool auto_decompress: Automatically decompress response body, True by default

2.3

param int read_bufsize: Size of the read buffer (ClientResponse.content). 64 KiB by default.

3.7

param bool trust_env

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.

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

2.3

3.0

Added support for ~/.netrc file.

param bool requote_redirect_url

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

3.5

param trace_configs: A list of TraceConfig instances used for client tracing. None (default) is used for request tracing disabling. See aiohttp-client-tracing-reference for more information.

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, ~aiohttp.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.

2.1

Note

This parameter affects all subsequent requests.

3.5

The attribute modification is deprecated.

loop

A loop instance used for session creation.

A read-only property.

3.5

timeout

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

3.7

headers

HTTP Headers that sent with every request

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

3.7

skip_auto_headers

Set of headers for which autogeneration skipped.

frozenset of str or ~aiohttp.istr (optional)

3.7

auth

An object that represents HTTP Basic Authorization.

~aiohttp.BasicAuth (optional)

3.7

json_serialize

Json serializer callable.

By default json.dumps function.

3.7

connector_owner

Should connector be closed on session closing

bool (optional)

3.7

raise_for_status

Should ClientResponse.raise_for_status() be called for each response

Either bool or callable

3.7

auto_decompress

Should the body response be automatically decompressed

bool default is True

3.7

trust_env

Should get proxies information from HTTP_PROXY / HTTPS_PROXY environment variables or ~/.netrc file if present

bool default is False

3.7

trace_config

A list of TraceConfig instances used for client tracing. None (default) is used for request tracing disabling. See aiohttp-client-tracing-reference for more information.

3.7

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, read_bufsize=None, 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.

param str method

HTTP method

param url

Request URL, str or ~yarl.URL.

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:

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)

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

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)

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

3.5

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 str or ~aiohttp.istr (optional)

param aiohttp.BasicAuth auth

an object that represents HTTP Basic Authorization (optional)

param bool allow_redirects

If set to False, do not follow redirects. True by default (optional).

param int max_redirects

Maximum number of redirects to follow. 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

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

param bool expect100

Expect 100-continue response from server. False by default (optional).

param bool raise_for_status

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

3.4

param bool read_until_eof: Read response until EOF if response does not have Content-Length header. True by default (optional).
param int read_bufsize: Size of the read buffer (ClientResponse.content). None by default, it means that the session global value is used.

3.7

param proxy: Proxy URL, str or ~yarl.URL (optional)
param aiohttp.BasicAuth proxy_auth: an object that represents proxy HTTP Basic Authorization (optional)
param int timeout: override the session's timeout.

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

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

3.0

param bool verify_ssl

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

2.3

3.0

Use ssl=False

param bytes fingerprint

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.

2.3

3.0

Use ssl=aiohttp.Fingerprint(digest)

param ssl.SSLContext ssl_context

ssl context used for processing HTTPS requests (optional).

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

2.3

3.0

Use ssl=ssl_context

param abc.Mapping proxy_headers

HTTP headers to send to the proxy if the parameter proxy has been provided.

2.3

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

3.0

return ClientResponse

a client response <ClientResponse> object.

get(url, , allow_redirects=True,*kwargs)

Perform a GET request.