aiohttp
Client session is the recommended interface for making HTTP requests.
Session encapsulates a connection pool (connector instance) and supports keepalives by default. Unless you are connecting to a large, unknown number of different servers over the lifetime of your application, it is suggested you use a single session for the lifetime of your application to benefit from connection pooling.
Usage example:
import aiohttp
import asyncio
async def fetch(client):
async with client.get('http://python.org') as resp:
assert resp.status == 200
return await resp.text()
async def main():
async with aiohttp.ClientSession() as client:
html = await fetch(client)
print(html)
asyncio.run(main())
The client session supports the context manager protocol for self closing.
The class for creating client sessions and making requests.
- param base_url
Base part of the URL (optional) If set, it allows to skip the base part (https://docs.aiohttp.org) in request calls. If base_url includes a path (as in https://docs.aiohttp.org/en/stable) the path is ignored/discarded.
3.8
- 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
orContent-Type
if these headers are not explicitly passed. Usingskip_auto_headers
parameter allows to skip that generation. Note thatContent-Length
autogeneration can't be skipped.Iterable of
str
or~multidict.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,
~aiohttp.abc.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 collections.abc.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 needraise_for_status
for most of cases but overrideraise_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.
- 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. UseNone
or0
to disable timeout checks.3.3
Use
timeout
parameter instead.- param float conn_timeout
timeout for connection establishing (optional). Values
0
orNone
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
Trust environment settings for proxy configuration if the parameter is
True
(False
by default). Seeaiohttp-client-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
..netrc
documentation: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html2.3
3.0
Added support for
~/.netrc
file.3.9
Added support for reading HTTP Basic Auth credentials from
~/.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. Seeaiohttp-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.abc.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 ~multidict.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 collections.abc.Callable
3.7
auto_decompress
Should the body response be automatically decompressed
bool
default is True
3.7
trust_env
Trust environment settings for proxy configuration or ~/.netrc file if present. See aiohttp-client-proxy-support
for more information.
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, server_hostname=None, auto_decompress=None)
Performs an asynchronous HTTP request. Returns a response object that should be used as an async context manager.
- param str method
HTTP method
- param url
Request URL,
~yarl.URL
orstr
that will be encoded with~yarl.URL
(see~yarl.URL
to skip encoding).- param params
Mapping, iterable of tuple of key/value pairs or string to be sent as parameters in the query string of the new request. Ignored for subsequent redirected requests (optional)
Allowed values are:
collections.abc.Mapping
e.g.dict
,multidict.MultiDict
ormultidict.MultiDictProxy
collections.abc.Iterable
e.g.tuple
orlist
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 intoFormData
, 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
orContent-Type
if these headers are not explicitly passed. Usingskip_auto_headers
parameter allows to skip that generation.Iterable of
str
or~multidict.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 toTrue
. If set toNone
value fromClientSession
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 str server_hostname
Sets or overrides the host name that the target server’s certificate will be matched against.
See :py
asyncio.loop.create_connection
for more information.3.9
- 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 collections.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
- param bool auto_decompress
Automatically decompress response body. Overrides
ClientSession.auto_decompress
. May be used to enable/disable auto decompression on a per-request basis.- return ClientResponse
a
client response <ClientResponse>
object.
get(url, , allow_redirects=True,*kwargs)
Perform a GET
request. Returns an async context manager.
In order to modify inner request<aiohttp.ClientSession.request>
parameters, provide kwargs.
- param url
Request URL,
str
or~yarl.URL
- param bool allow_redirects
If set to
False
, do not follow redirects.True
by default (optional).- return ClientResponse
a
client response <ClientResponse>
object.
post(url, , data=None,*kwargs)
Perform a POST
request. Returns an async context manager.
In order to modify inner request<aiohttp.ClientSession.request>
parameters, provide kwargs.
- param url
Request URL,
str
or~yarl.URL
- param data
Data to send in the body of the request; see
request<aiohttp.ClientSession.request>
for details (optional)- return ClientResponse
a
client response <ClientResponse>
object.
put(url, , data=None,*kwargs)
Perform a PUT
request. Returns an async context manager.
In order to modify inner request<aiohttp.ClientSession.request>
parameters, provide kwargs.
- param url
Request URL,
str
or~yarl.URL
- param data
Data to send in the body of the request; see
request<aiohttp.ClientSession.request>
for details (optional)- return ClientResponse
a
client response <ClientResponse>
object.
delete(url, **kwargs)
Perform a DELETE
request. Returns an async context manager.
In order to modify inner request<aiohttp.ClientSession.request>
parameters, provide kwargs.
- param url
Request URL,
str
or~yarl.URL
- return ClientResponse
a
client response <ClientResponse>
object.
head(url, , allow_redirects=False,*kwargs)
Perform a HEAD
request. Returns an async context manager.
In order to modify inner request<aiohttp.ClientSession.request>
parameters, provide kwargs.
- param url
Request URL,
str
or~yarl.URL
- param bool allow_redirects
If set to
False
, do not follow redirects.False
by default (optional).- return ClientResponse
a
client response <ClientResponse>
object.
options(url, , allow_redirects=True,*kwargs)
Perform an OPTIONS
request. Returns an async context manager.
In order to modify inner request<aiohttp.ClientSession.request>
parameters, provide kwargs.
- param url
Request URL,
str
or~yarl.URL
- param bool allow_redirects
If set to
False
, do not follow redirects.True
by default (optional).- return ClientResponse
a
client response <ClientResponse>
object.
patch(url, , data=None,*kwargs)
Perform a PATCH
request. Returns an async context manager.
In order to modify inner request<aiohttp.ClientSession.request>
parameters, provide kwargs.
- param url
Request URL,
str
or~yarl.URL
- param data
Data to send in the body of the request; see
request<aiohttp.ClientSession.request>
for details (optional)- return ClientResponse
a
client response <ClientResponse>
object.
ws_connect(url, *, method='GET', protocols=(), timeout=10.0,receive_timeout=None,auth=None,autoclose=True,autoping=True,heartbeat=None,origin=None, params=None, headers=None, proxy=None, proxy_auth=None, ssl=None, verify_ssl=None, fingerprint=None, ssl_context=None, proxy_headers=None, compress=0, max_msg_size=4194304)
Create a websocket connection. Returns a ClientWebSocketResponse
async context manager object.
- param url
Websocket server url,
~yarl.URL
orstr
that will be encoded with~yarl.URL
(see~yarl.URL
to skip encoding).- param tuple protocols
Websocket protocols
- param float timeout
Timeout for websocket to close.
10
seconds by default- param float receive_timeout
Timeout for websocket to receive complete message.
None
(unlimited) seconds by default- param aiohttp.BasicAuth auth
an object that represents HTTP Basic Authorization (optional)
- param bool autoclose
Automatically close websocket connection on close message from server. If autoclose is False then close procedure has to be handled manually.
True
by default- param bool autoping
automatically send pong on ping message from server.
True
by default- param float heartbeat
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)
- param str origin
Origin header to send to server(optional)
- 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
,multidict.MultiDict
ormultidict.MultiDictProxy
collections.abc.Iterable
e.g.tuple
orlist
str
with preferably url-encoded content (Warning: content will not be encoded by aiohttp)
- param dict headers
HTTP Headers to send with the request (optional)
- param str proxy
Proxy URL,
str
or~yarl.URL
(optional)- param aiohttp.BasicAuth proxy_auth
an object that represents proxy HTTP Basic Authorization (optional)
- 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.
Note: use of MD5 or SHA1 digests is insecure and deprecated.
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 dict proxy_headers
HTTP headers to send to the proxy if the parameter proxy has been provided.
2.3
- param int compress
Enable Per-Message Compress Extension support. 0 for disable, 9 to 15 for window bit support. Default value is 0.
2.3
- param int max_msg_size
maximum size of read websocket message, 4 MB by default. To disable the size limit use
0
.
3.3
- param str method
HTTP method to establish WebSocket connection,
'GET'
by default.
3.5
close()
Close underlying connector.
Release all acquired resources.
detach()
Detach connector from session without closing the former.
Session is switched to closed state anyway.
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.
request(method, url, *, params=None, data=None, json=None,headers=None, cookies=None, auth=None, allow_redirects=True, max_redirects=10, encoding='utf-8', version=HttpVersion(major=1, minor=1), compress=None, chunked=None, expect100=False, raise_for_status=False, read_bufsize=None, connector=None, loop=None,read_until_eof=True, timeout=sentinel)
Asynchronous context manager for performing an asynchronous HTTP request. Returns a ClientResponse
response object. Use as an async context manager.
- param str method
HTTP method
- param url
Request URL,
~yarl.URL
orstr
that will be encoded with~yarl.URL
(see~yarl.URL
to skip encoding).- param dict params
Parameters to be sent in the query string of the new request (optional)
- param data
The data to send in the body of the request. This can be a
FormData
object or anything that can be passed intoFormData
, e.g. a dictionary, bytes, or file-like object. (optional)- param json
Any json compatible python object (optional). json and data parameters could not be used at the same time.
- param dict headers
HTTP Headers to send with the request (optional)
- param dict cookies
Cookies to send with the request (optional)
- param aiohttp.BasicAuth auth
an object that represents HTTP Basic Authorization (optional)
- param bool allow_redirects
If set to
False
, do not follow redirects.True
by default (optional).- param aiohttp.protocol.HttpVersion version
Request HTTP version (optional)
- param bool compress
Set to
True
if request has to be compressed with deflate encoding.False
instructs aiohttp to not compress data.None
by default (optional).- param int chunked
Enables chunked transfer encoding.
None
by default (optional).- param bool expect100
Expect 100-continue response from server.
False
by default (optional).- param bool raise_for_status
Automatically call
ClientResponse.raise_for_status()
for response if set toTrue
. If set toNone
value fromClientSession
will be used.None
by default (optional).
3.4
- param aiohttp.BaseConnector connector
BaseConnector sub-class instance to support connection pooling.
- param bool read_until_eof
Read response until EOF if response does not have Content-Length header.
True
by default (optional).- param int read_bufsize
Size of the read buffer (
ClientResponse.content
).None
by default, it means that the session global value is used.
3.7
- param timeout
a
ClientTimeout
settings structure, 300 seconds (5min) total timeout by default.- param loop
event loop<asyncio-event-loop>
used for processing HTTP requests. If param isNone
,asyncio.get_event_loop
is used for getting default event loop.
2.0
- return ClientResponse
a
client response <ClientResponse>
object.
Usage:
import aiohttp
async def fetch():
async with aiohttp.request('GET',
'http://python.org/') as resp:
assert resp.status == 200
print(await resp.text())
Connectors are transports for aiohttp client API.
There are standard connectors:
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).
Base class for all connectors.
- param float keepalive_timeout
timeout for connection reusing after releasing (optional). Values
0
. For disabling keep-alive feature useforce_close=True
flag.- param int limit
total number simultaneous connections. If limit is
None
the connector has no limit (default: 100).- param int limit_per_host
limit simultaneous connections to the same endpoint. Endpoints are the same if they are have equal
(host, port, is_ssl)
triple. If limit is0
the connector has no limit (default: 0).- param bool force_close
close underlying sockets after connection releasing (optional).
- param bool enable_cleanup_closed
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.
- param loop
event loop<asyncio-event-loop>
used for handling connections. If param isNone
,asyncio.get_event_loop
is used for getting default event loop.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 None
the connector has no limit per host.
Read-only property.
close()
Close all opened connections.
connect(request)
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.
- param aiohttp.ClientRequest request
request object which is connection initiator.
- return
Connection
object.
_create_connection(req)
Abstract method for actual connection establishing, should be overridden in subclasses.
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.
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
Pass verify_ssl to
ClientSession.get()
etc.- 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.
Note: use of MD5 or SHA1 digests is insecure and deprecated.
2.3
Pass verify_ssl to
ClientSession.get()
etc.- param bool use_dns_cache
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.
- param int ttl_dns_cache
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.
- param int limit
total number simultaneous connections. If limit is
None
the connector has no limit (default: 100).- param int limit_per_host
limit simultaneous connections to the same endpoint. Endpoints are the same if they are have equal
(host, port, is_ssl)
triple. If limit is0
the connector has no limit (default: 0).- param aiohttp.abc.AbstractResolver resolver
custom resolver instance to use.
aiohttp.DefaultResolver
by default (asynchronous ifaiodns>=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.- param int family
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 passsocket.AF_INET
orsocket.AF_INET6
explicitly.- 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.
- param tuple local_addr
tuple of
(local_host, local_port)
used to bind socket locally if specified.- param bool force_close
close underlying sockets after connection releasing (optional).
- param bool enable_cleanup_closed
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.
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)
Clear internal DNS cache.
Remove specific entry if both host and port are specified, clear all cache otherwise.
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:
- param str path
Unix socket path
path
Path to UNIX socket, read-only str
property.
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
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.
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
coroutine).
version
Response's version, ~aiohttp.protocol.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 (~yarl.URL
).
real_url
Unmodified URL of request with URL fragment unstripped (~yarl.URL
).
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 misformed chunked encoding of broken compression data.
cookies
HTTP cookies of response (Set-Cookie HTTP header, ~http.cookies.SimpleCookie
).
headers
A case-insensitive multidict proxy with HTTP headers of response, ~multidict.CIMultiDictProxy
.
raw_headers
Unmodified HTTP headers of response as unconverted bytes, a sequence of (key, value)
pairs.
links
Link HTTP header parsed into a ~multidict.MultiDictProxy
.
For each link, key is link param rel when it exists, or link url as str
otherwise, and value is ~multidict.MultiDictProxy
of link params and url at key url as ~yarl.URL
instance.
3.2
content_type
Read-only property with content part of Content-Type header.
Note
Returns value is 'application/octet-stream'
if no Content-Type header present in HTTP headers according to 2616
. 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 ~collections.abc.Sequence
of ClientResponse
objects of preceding requests (earliest request first) if there were redirects, an empty sequence otherwise.
close()
Close response and underlying connection.
For keep-alive
support see release
.
read()
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.
close
, release
.
release()
It is not required to call release on the response object. When the client fully receives the payload, the underlying connection automatically returns back to pool. If the payload is not fully read, the connection is closed
raise_for_status()
Raise an aiohttp.ClientResponseError
if the response status is 400 or higher.
Do nothing for success responses (less than 400).
text(encoding=None)
Read response's body and return decoded str
using specified encoding parameter.
If encoding is None
content encoding is autocalculated using Content-Type
HTTP header and charset-normalizer tool if the header is not provided by server.
cchardet
is used with fallback to charset-normalizer
if cchardet is not available.
Close underlying connection if data reading gets an error, release connection otherwise.
- param str encoding
text encoding used for BODY decoding, or
None
for encoding autodetection (default).- return str
decoded BODY
- raise LookupError
if the encoding detected by cchardet is unknown by Python (e.g. VISCII).
Note
If response has no charset
info in Content-Type
HTTP header cchardet
/ charset-normalizer
is used for content encoding autodetection.
It may hurt performance. If page encoding is known passing explicit encoding parameter might help:
await resp.text('ISO-8859-1')
json(*, encoding=None, loads=json.loads, content_type='application/json')
Read response's body as JSON, return dict
using specified encoding and loader. If data is not still available a read
call will be done,
If encoding is None
content encoding is autocalculated using cchardet
or charset-normalizer
as fallback if cchardet is not available.
if response's content-type does not match content_type parameter aiohttp.ContentTypeError
get raised. To disable content type check pass None
value.
- param str encoding
text encoding used for BODY decoding, or
None
for encoding autodetection (default).By the standard JSON encoding should be
UTF-8
but practice beats purity: some servers return non-UTF responses. Autodetection works pretty fine anyway.- param collections.abc.Callable loads
callable
used for loading JSON data,json.loads
by default.- param str content_type
specify response's content-type, if content type does not match raise
aiohttp.ClientResponseError
. To disable content-type check, passNone
as value. (default: application/json).- return
BODY as JSON data parsed by loads parameter or
None
if BODY is empty or contains white-spaces only.
request_info
A namedtuple with request URL and headers from ~aiohttp.ClientRequest
object, aiohttp.RequestInfo
instance.
get_encoding()
Automatically detect content encoding using charset
info in Content-Type
HTTP header. If this info is not exists or there are no appropriate codecs for encoding then cchardet
/ charset-normalizer
is used.
Beware that it is not always safe to use the result of this function to decode a response. Some encodings detected by cchardet are not known by Python (e.g. VISCII). charset-normalizer is not concerned by that issue.
- raise RuntimeError
if called before the body has been read, for
cchardet
usage
3.0
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 for handling client-side websockets.
closed
Read-only property, True
if close
has been called or ~aiohttp.WSMsgType.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)
Reads extra info from connection's transport
exception()
Returns exception if any occurs or returns None.
ping(message=b'')
Send ~aiohttp.WSMsgType.PING
to peer.
- param message
optional payload of ping message,
str
(converted to UTF-8 encoded bytes) orbytes
.
3.0
The method is converted into coroutine
pong(message=b'')
Send ~aiohttp.WSMsgType.PONG
to peer.
- param message
optional payload of pong message,
str
(converted to UTF-8 encoded bytes) orbytes
.
3.0
The method is converted into coroutine
send_str(data, compress=None)
Send data to peer as ~aiohttp.WSMsgType.TEXT
message.
- param str data
data to send.
- param int compress
sets specific level of compression for single message,
None
for not overriding per-socket setting.- raise TypeError
if data is not
str
3.0
The method is converted into coroutine
, compress parameter added.
send_bytes(data, compress=None)
Send data to peer as ~aiohttp.WSMsgType.BINARY
message.
- param data
data to send.
- param int compress
sets specific level of compression for single message,
None
for not overriding per-socket setting.- raise TypeError
if data is not
bytes
,bytearray
ormemoryview
.
3.0
The method is converted into coroutine
, compress parameter added.
send_json(data, compress=None, *, dumps=json.dumps)
Send data to peer as JSON string.
- param data
data to send.
- param int compress
sets specific level of compression for single message,
None
for not overriding per-socket setting.- param collections.abc.Callable dumps
any
callable
that accepts an object and returns a JSON string (json.dumps
by default).- raise RuntimeError
if connection is not started or closing
- raise ValueError
if data is not serializable object
- raise TypeError
if value returned by
dumps(data)
is notstr
3.0
The method is converted into coroutine
, compress parameter added.
close(*, code=WSCloseCode.OK, message=b'')
A coroutine<coroutine>
that initiates closing handshake by sending ~aiohttp.WSMsgType.CLOSE
message. It waits for close response from server. To add a timeout to close() call just wrap the call with asyncio.wait() or asyncio.wait_for().
- param int code
closing code. See also
~aiohttp.WSCloseCode
.- param message
optional payload of close message,
str
(converted to UTF-8 encoded bytes) orbytes
.
receive()
A coroutine<coroutine>
that waits upcoming data message from peer and returns it.
The coroutine implicitly handles ~aiohttp.WSMsgType.PING
, ~aiohttp.WSMsgType.PONG
and ~aiohttp.WSMsgType.CLOSE
without returning the message.
It process ping-pong game and performs closing handshake internally.
- return
~aiohttp.WSMessage
receive_str()
A coroutine<coroutine>
that calls receive
but also asserts the message type is ~aiohttp.WSMsgType.TEXT
.
- return str
peer's message content.
- raise TypeError
if message is
~aiohttp.WSMsgType.BINARY
.
receive_bytes()
A coroutine<coroutine>
that calls receive
but also asserts the message type is ~aiohttp.WSMsgType.BINARY
.
- return bytes
peer's message content.
- raise TypeError
if message is
~aiohttp.WSMsgType.TEXT
.
receive_json(*, loads=json.loads)
A coroutine<coroutine>
that calls receive_str
and loads the JSON string to a Python dict.
- param collections.abc.Callable loads
any
callable
that acceptsstr
and returnsdict
with parsed JSON (json.loads
by default).- return dict
loaded JSON content
- raise TypeError
if message is
~aiohttp.WSMsgType.BINARY
.- raise ValueError
if message is not valid JSON.
A data class for client timeout settings.
See aiohttp-client-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.
3.3
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.
3.7
Rounding to the next seconds boundary is disabled for timeouts smaller than 5 seconds for the sake of easy debugging.
In turn, tiny timeouts can lead to significant performance degradation on production environment.
Represents ETag identifier.
value
Value of corresponding etag without quotes.
is_weak
Flag indicates that etag is weak (has W/ prefix).
3.8
A data class with request URL and headers from ~aiohttp.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.
3.2
HTTP basic authentication helper.
- param str login
login
- param str password
password
- param str encoding
encoding (
'latin1'
by default)
Should be used for specifying authorization data in client API, e.g. auth parameter for ClientSession.request() <aiohttp.ClientSession.request>
.
decode(auth_header, encoding='latin1')
Decode HTTP basic authentication credentials.
- param str auth_header
The
Authorization
header to decode.- param str encoding
(optional) encoding ('latin1' by default)
- return
decoded authentication data,
BasicAuth
.
from_url(url)
Constructed credentials info from url's user and password parts.
- return
credentials data,
BasicAuth
orNone
is credentials are not provided.
2.3
encode()
Encode credentials into string suitable for Authorization
header etc.
- return
encoded authentication data,
str
.
The cookie jar instance is available as ClientSession.cookie_jar
.
The jar contains ~http.cookies.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.
- param bool unsafe
(optional) Whether to accept cookies from IPs.
- param bool quote_cookie
(optional) Whether to quote cookies according to
2109
. Some backend systems (not compatible with RFC mentioned above) does not support quoted cookies.
3.7
- param treat_as_secure_origin
(optional) Mark origins as secure for cookies marked as Secured. Possible types are
Possible types are:
tuple
orlist
ofstr
oryarl.URL
str
yarl.URL
3.8
update_cookies(cookies, response_url=None)
Update cookies returned by server in Set-Cookie
header.
- param cookies
a
collections.abc.Mapping
(e.g.dict
,~http.cookies.SimpleCookie
) or iterable of pairs with cookies returned by server's response.- param ~yarl.URL response_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)
Return jar's cookies acceptable for URL and available in Cookie
header for sending client requests for given URL.
- param ~yarl.URL response_url
request's URL for which cookies are asked.
- return
http.cookies.SimpleCookie
with filtered cookies for given URL.
save(file_path)
Write a pickled representation of cookies into the file at provided path.
- param file_path
Path to file where cookies will be serialized,
str
orpathlib.Path
instance.
load(file_path)
Load a pickled representation of cookies from the file at provided path.
- param file_path
Path to file from where cookies will be imported,
str
orpathlib.Path
instance.
clear(predicate=None)
Removes all cookies from the jar if the predicate is None
. Otherwise remove only those ~http.cookies.Morsel
that predicate(morsel)
returns True
.
- param predicate
callable that gets
~http.cookies.Morsel
as a parameter and returnsTrue
if this~http.cookies.Morsel
must be deleted from the jar.
4.0
clear_domain(domain)
Remove all cookies from the jar that belongs to the specified domain or its subdomains.
- param str domain
domain for which cookies must be deleted from the jar.
4.0
Dummy cookie jar which does not store cookies but ignores them.
Could be useful e.g. for web crawlers to iterate over Internet without blowing up with saved cookies information.
To install dummy cookie jar pass it into session instance:
jar = aiohttp.DummyCookieJar()
session = aiohttp.ClientSession(cookie_jar=DummyCookieJar())
Fingerprint helper for checking SSL certificates by SHA256 digest.
- param bytes digest
SHA256 digest for certificate in DER-encoded binary form (see
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))
3.0
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<aiohttp.FormData.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.
Helper class for multipart/form-data and application/x-www-form-urlencoded body generation.
- param fields
A container for the key/value pairs of this form.
Possible types are:
dict
tuple
orlist
io.IOBase
, e.g. a file-like objectmultidict.MultiDict
ormultidict.MultiDictProxy
If it is a
tuple
orlist
, it must be a valid argument foradd_fields<aiohttp.FormData.add_fields>
.For
dict
,multidict.MultiDict
, andmultidict.MultiDictProxy
, the keys and values must be valid name and value arguments toadd_field<aiohttp.FormData.add_field>
, respectively.
add_field(name, value, content_type=None, filename=None,content_transfer_encoding=None)
Add a field to the form.
- param str name
Name of the field
- param value
Value of the field
Possible types are:
str
bytes
,bytearray
, ormemoryview
io.IOBase
, e.g. a file-like object
- param str content_type
The field's content-type header (optional)
- param str filename
The field's filename (optional)
If this is not set and
value
is abytes
,bytearray
, ormemoryview
object, the name argument is used as the filename unlesscontent_transfer_encoding
is specified.If
filename
is not set andvalue
is anio.IOBase
object, the filename is extracted from the object if possible.
- param str content_transfer_encoding
The field's content-transfer-encoding header (optional)
add_fields(fields)
Add one or more fields to the form.
- param fields
An iterable containing:
io.IOBase
, e.g. a file-like objectmultidict.MultiDict
ormultidict.MultiDictProxy
tuple
orlist
of length two, containing a name-value pair
Exception hierarchy has been significantly modified in version 2.0. aiohttp defines only exceptions that covers connection handling and server response misbehaviors. For developer specific mistakes, aiohttp uses python standard exceptions like 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.
ClientError
Base class for all client specific exceptions.
Derived from Exception
This exception can only be raised while reading the response payload if one of these errors occurs:
- invalid compression
- malformed chunked encoding
- not enough data that satisfy
Content-Length
HTTP header.
Derived from ClientError
InvalidURL
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.
Represent Content-Disposition header
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.
ClientResponseError
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
.
3.1
Web socket server response error.
Derived from ClientResponseError
Invalid content type.
Derived from ClientResponseError
2.3
Client was redirected too many times.
Maximum number of redirects can be configured by using parameter max_redirects
in request<aiohttp.ClientSession.request>
.
Derived from ClientResponseError
3.2
These exceptions related to low-level connection problems.
Derived from ClientError
Subset of connection errors that are initiated by an OSError
exception.
Derived from ClientConnectionError
and OSError
Connector related exceptions.
Derived from ClientOSError
Derived from ClientConnectorError
Derived from ClientConnectorError
Derived from ClientConnectionError
Derived from ClientConnectorError
Response ssl error.
Derived from ClientSSLError
and ssl.SSLError
Response certificate error.
Derived from ClientSSLError
and ssl.CertificateError
Server disconnected.
Derived from ~aiohttp.ServerConnectionError
message
Partially parsed HTTP message (optional).
Server operation timeout: read timeout, etc.
Derived from ServerConnectionError
and asyncio.TimeoutError
Server fingerprint mismatch.
Derived from ServerConnectionError
ClientError
ClientResponseError
ContentTypeError
WSServerHandshakeError
~aiohttp.ClientHttpProxyError
ClientConnectionError
ClientOSError
ClientConnectorError
ClientSSLError
ClientConnectorCertificateError
ClientConnectorSSLError
ClientProxyConnectionError
ServerConnectionError
ServerDisconnectedError
ServerTimeoutError
ServerFingerprintMismatch
ClientPayloadError
InvalidURL