HTTP Client Reference¶
Client Session¶
Client session is the recommended interface for making HTTP requests.
Session encapsulates connection pool (connector instance) and supports keepalives by default.
Usage example:
import aiohttp
import asyncio
async def fetch(client):
async with client.get('http://python.org') as resp:
assert resp.status == 200
print(await resp.text())
with aiohttp.ClientSession() as client:
asyncio.get_event_loop().run_until_complete(fetch(client))
New in version 0.17.
The client session supports context manager protocol for self closing.
-
class
aiohttp.
ClientSession
(*, connector=None, loop=None, cookies=None, headers=None, skip_auto_headers=None, auth=None, request_class=ClientRequest, response_class=ClientResponse, ws_response_class=ClientWebSocketResponse)[source]¶ The class for creating client sessions and making requests.
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. - cookies (dict) – Cookies to send with the request (optional)
- headers –
HTTP Headers to send with the 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
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. - auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional)
- request_class – Request class implementation.
ClientRequest
by default. - response_class – Response class
implementation.
ClientResponse
by default. - ws_response_class –
WebSocketResponse class implementation.
ClientWebSocketResponse
by default.New in version 0.16.
Changed in version 0.16: request_class default changed from
None
toClientRequest
Changed in version 0.16: response_class default changed from
None
toClientResponse
-
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.
The session cookies,
http.cookies.SimpleCookie
instance.A read-only property. Overriding session.cookies = new_val is forbidden, but you may modify the object in-place if needed.
-
coroutine
request
(method, url, *, params=None, data=None, headers=None, skip_auto_headers=None, auth=None, allow_redirects=True, max_redirects=10, encoding='utf-8', version=HttpVersion(major=1, minor=1), compress=None, chunked=None, expect100=False, read_until_eof=True)[source]¶ Performs an asynchronous HTTP request. Returns a response object.
Parameters: - method (str) – HTTP method
- url (str) – Request 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 (optional)
Allowed values are:
collections.abc.Mapping
e.g.dict
,aiohttp.MultiDict
oraiohttp.MultiDictProxy
collections.abc.Iterable
e.g.tuple
orlist
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)
- 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
orContent-Type
if these headers are not explicitly passed. Usingskip_auto_headers
parameter allows to skip that generation. - 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). - version (aiohttp.protocol.HttpVersion) – Request HTTP version (optional)
- compress (bool) – Set to
True
if request has to be compressed with deflate encoding.None
by default (optional). - chunked (int) – Set to chunk size for chunked transfer encoding.
None
by default (optional). - expect100 (bool) – Expect 100-continue response from server.
False
by default (optional). - read_until_eof (bool) – Read response until EOF if response
does not have Content-Length header.
True
by default (optional).
Return ClientResponse: a
client response
object.
-
coroutine
get
(url, *, allow_redirects=True, **kwargs)[source]¶ Perform a
GET
request.In order to modify inner
request
parameters, provide kwargs.Parameters: Return ClientResponse: a
client response
object.
-
coroutine
post
(url, *, data=None, **kwargs)[source]¶ Perform a
POST
request.In order to modify inner
request
parameters, provide kwargs.Parameters: - url (str) – Request URL
- data – Dictionary, bytes, or file-like object to send in the body of the request (optional)
Return ClientResponse: a
client response
object.
-
coroutine
put
(url, *, data=None, **kwargs)[source]¶ Perform a
PUT
request.In order to modify inner
request
parameters, provide kwargs.Parameters: - url (str) – Request URL
- data – Dictionary, bytes, or file-like object to send in the body of the request (optional)
Return ClientResponse: a
client response
object.
-
coroutine
delete
(url, **kwargs)[source]¶ Perform a
DELETE
request.In order to modify inner
request
parameters, provide kwargs.Parameters: url (str) – Request URL Return ClientResponse: a client response
object.
-
coroutine
head
(url, *, allow_redirects=False, **kwargs)[source]¶ Perform a
HEAD
request.In order to modify inner
request
parameters, provide kwargs.Parameters: Return ClientResponse: a
client response
object.
-
coroutine
options
(url, *, allow_redirects=True, **kwargs)[source]¶ Perform an
OPTIONS
request.In order to modify inner
request
parameters, provide kwargs.Parameters: Return ClientResponse: a
client response
object.
-
coroutine
patch
(url, *, data=None, **kwargs)[source]¶ Perform a
PATCH
request.In order to modify inner
request
parameters, provide kwargs.Parameters: - url (str) – Request URL
- data – Dictionary, bytes, or file-like object to send in the body of the request (optional)
Return ClientResponse: a
client response
object.
-
coroutine
ws_connect
(url, *, protocols=(), timeout=10.0, auth=None, autoclose=True, autoping=True, origin=None)[source]¶ Create a websocket connection. Returns a
ClientWebSocketResponse
object.Parameters: - url (str) – Websocket server url
- protocols (tuple) – Websocket protocols
- timeout (float) – Timeout for websocket read. 10 seconds by default
- 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 them close procedure has to be handled manually
- autoping (bool) – automatically send pong on ping message from server
- origin (str) – Origin header to send to server
New in version 0.16: Add
ws_connect()
.New in version 0.18: Add auth parameter.
New in version 0.19: Add origin parameter.
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.
-
coroutine
aiohttp.
request
(method, url, *, params=None, data=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, connector=None, loop=None, read_until_eof=True, request_class=None, response_class=None)[source]¶ Perform an asynchronous HTTP request. Return a response object (
ClientResponse
or derived from).Parameters: - method (str) – HTTP method
- url (str) – Requested URL
- params (dict) – Parameters to be sent in the query string of the new request (optional)
- data – Dictionary, bytes, or file-like object to send in the body of the request (optional)
- headers (dict) – HTTP Headers to send with the request (optional)
- cookies (dict) – Cookies to send with the request (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). - version (aiohttp.protocol.HttpVersion) – Request HTTP version (optional)
- compress (bool) – Set to
True
if request has to be compressed with deflate encoding.False
instructs aiohttp to not compress data even if the Content-Encoding header is set. Use it when sending pre-compressed data.None
by default (optional). - chunked (int) – Set to chunk size for chunked transfer encoding.
None
by default (optional). - expect100 (bool) – Expect 100-continue response from server.
False
by default (optional). - connector (aiohttp.connector.BaseConnector) – BaseConnector sub-class instance to support connection pooling.
- read_until_eof (bool) – Read response until EOF if response
does not have Content-Length header.
True
by default (optional). - request_class – Custom Request class implementation (optional)
- response_class – Custom Response class implementation (optional)
- loop – event loop
used for processing HTTP requests.
If param is
None
,asyncio.get_event_loop()
is used for getting default event loop, but we strongly recommend to use explicit loops everywhere. (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())
.. deprecated:: 0.21
Use :meth:`ClientSession.request`.
-
coroutine
aiohttp.
get
(url, **kwargs)[source]¶ Perform a GET request.
Parameters: Returns: ClientResponse
or derived fromDeprecated since version 0.21: Use
ClientSession.get()
.
-
coroutine
aiohttp.
options
(url, **kwargs)[source]¶ Perform a OPTIONS request.
Parameters: Returns: ClientResponse
or derived fromDeprecated since version 0.21: Use
ClientSession.options()
.
-
coroutine
aiohttp.
head
(url, **kwargs)[source]¶ Perform a HEAD request.
Parameters: Returns: ClientResponse
or derived fromDeprecated since version 0.21: Use
ClientSession.head()
.
-
coroutine
aiohttp.
delete
(url, **kwargs)[source]¶ Perform a DELETE request.
Parameters: Returns: ClientResponse
or derived fromDeprecated since version 0.21: Use
ClientSession.delete()
.
-
coroutine
aiohttp.
post
(url, *, data=None, **kwargs)[source]¶ Perform a POST request.
Parameters: Returns: ClientResponse
or derived fromDeprecated since version 0.21: Use
ClientSession.post()
.
-
coroutine
aiohttp.
put
(url, *, data=None, **kwargs)[source]¶ Perform a PUT request.
Parameters: Returns: ClientResponse
or derived fromDeprecated since version 0.21: Use
ClientSession.put()
.
-
coroutine
aiohttp.
patch
(url, *, data=None, **kwargs)[source]¶ Perform a PATCH request.
Parameters: Returns: ClientResponse
or derived fromDeprecated since version 0.21: Use
ClientSession.patch()
.
-
coroutine
aiohttp.
ws_connect
(url, *, protocols=(), timeout=10.0, connector=None, auth=None, ws_response_class=ClientWebSocketResponse, autoclose=True, autoping=True, loop=None, origin=None, headers=None)[source]¶ This function creates a websocket connection, checks the response and returns a
ClientWebSocketResponse
object. In case of failure it may raise aWSServerHandshakeError
exception.Parameters: - url (str) – Websocket server url
- protocols (tuple) – Websocket protocols
- timeout (float) – Timeout for websocket read. 10 seconds by default
- connector (obj) – object
TCPConnector
- ws_response_class –
WebSocketResponse class implementation.
ClientWebSocketResponse
by default.New in version 0.16.
- autoclose (bool) – Automatically close websocket connection on close message from server. If autoclose is False them close procedure has to be handled manually
- autoping (bool) – Automatically send pong on ping message from server
- auth (aiohttp.helpers.BasicAuth) – BasicAuth named tuple that represents HTTP Basic Authorization (optional)
- loop –
event loop used for processing HTTP requests.
If param is
None
asyncio.get_event_loop()
used for getting default event loop, but we strongly recommend to use explicit loops everywhere. - origin (str) – Origin header to send to server
- headers –
dict
,CIMultiDict
orCIMultiDictProxy
for providing additional headers for websocket handshake request.
New in version 0.18: Add auth parameter.
New in version 0.19: Add origin parameter.
New in version 0.20: Add headers parameter.
Deprecated since version 0.21: Use
ClientSession.ws_connect()
.
Connectors¶
Connectors are transports for aiohttp client API.
There are standard connectors:
TCPConnector
for regular TCP sockets (both HTTP and HTTPS schemes supported).ProxyConnector
for connecting via HTTP proxy.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 except ProxyConnector
support
keep-alive connections (behavior is controlled by force_close
constructor’s parameter).
BaseConnector¶
-
class
aiohttp.
BaseConnector
(*, conn_timeout=None, keepalive_timeout=30, limit=None, share_cookies=False, force_close=False, loop=None)[source]¶ Base class for all connectors.
Parameters: - conn_timeout (float) – timeout for connection establishing
(optional). Values
0
orNone
mean no timeout. - keepalive_timeout (float) – timeout for connection reusing
after releasing (optional). Values
0
orNone
mean no timeout. - limit (int) – limit for simultaneous connections to the same
endpoint. Endpoints are the same if they are
have equal
(host, port, is_ssl)
triple. If limit isNone
the connector has no limit. - share_cookies (bool) – update
cookies
on connection processing (optional, deprecated). - force_close (bool) – do close underlying sockets after connection releasing (optional).
- loop – event loop
used for handling connections.
If param is
None
,asyncio.get_event_loop()
is used for getting default event loop, but we strongly recommend to use explicit loops everywhere. (optional)
Deprecated since version 0.15.2: share_cookies parameter is deprecated, use
ClientSession
for handling cookies for client connections.-
closed
¶ Read-only property,
True
if connector is closed.
-
force_close
¶ Read-only property,
True
if connector should ultimately close connections on releasing.New in version 0.16.
-
limit
¶ 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 is
None
the connector has no limit (default).Read-only property.
New in version 0.16.
-
coroutine
close
()[source]¶ Close all opened connections.
Changed in version 0.21: The method is converted into coroutine (but technically returns a future for keeping backward compatibility during transition period).
-
coroutine
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.client.ClientRequest) – request object which is connection initiator. Returns: Connection
object.
- conn_timeout (float) – timeout for connection establishing
(optional). Values
TCPConnector¶
-
class
aiohttp.
TCPConnector
(*, verify_ssl=True, fingerprint=None, use_dns_cache=False, family=0, ssl_context=None, conn_timeout=None, keepalive_timeout=30, limit=None, share_cookies=False, force_close=False, loop=None, local_addr=None)[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 fromBaseConnector
.Constructor accepts all parameters suitable for
BaseConnector
plus several TCP-specific ones: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.
- fingerprint (bytes) –
Pass the binary MD5, SHA1, or SHA256 digest of the expected certificate in DER format to verify that the certificate the server presents matches. Useful for certificate pinning.
New in version 0.16.
- use_dns_cache (bool) –
use internal cache for DNS lookups,
False
by default.Enabling an option may speedup connection establishing a bit but may introduce some side effects also.
New in version 0.17.
- resolve (bool) –
alias for use_dns_cache parameter.
Deprecated since version 0.17.
- family (int) –
- TCP socket family, both IPv4 and IPv6 by default.
- For IPv4 only use
socket.AF_INET
, for IPv6 only –socket.AF_INET6
.
Changed in version 0.18: family is 0 by default, that means both IPv4 and IPv6 are accepted. To specify only concrete version please pass
socket.AF_INET
orsocket.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.New in version 0.21.
-
ssl_context
¶ ssl.SSLContext
instance for https requests, read-only property.
-
family
¶ TCP socket family e.g.
socket.AF_INET
orsocket.AF_INET6
Read-only property.
-
dns_cache
¶ Use quick lookup in internal DNS cache for host names if
True
.Read-only
bool
property.New in version 0.17.
-
cached_hosts
¶ The cache of resolved hosts if
dns_cache
is enabled.Read-only
types.MappingProxyType
property.New in version 0.17.
-
resolved_hosts
¶ Alias for
cached_hosts
Deprecated since version 0.17.
-
fingerprint
¶ MD5, SHA1, or SHA256 hash of the expected certificate in DER format, or
None
if no certificate fingerprint check required.Read-only
bytes
property.New in version 0.16.
-
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.
New in version 0.17.
-
clear_resolved_hosts
(self, host=None, port=None)[source]¶ Alias for
clear_dns_cache()
.Deprecated since version 0.17.
ProxyConnector¶
-
class
aiohttp.
ProxyConnector
(proxy, *, proxy_auth=None, conn_timeout=None, keepalive_timeout=30, limit=None, share_cookies=False, force_close=True, loop=None)[source]¶ HTTP Proxy connector.
Use
ProxyConnector
for sending HTTP/HTTPS requests through HTTP proxy.ProxyConnector
is inherited fromTCPConnector
.Usage:
conn == ProxyConnector(proxy="http://some.proxy.com") session = ClientSession(connector=conn) async with session.get('http://python.org') as resp: assert resp.status == 200
Constructor accepts all parameters suitable for
TCPConnector
plus several proxy-specific ones:Parameters: - proxy (str) – URL for proxy, e.g.
"http://some.proxy.com"
. - proxy_auth (aiohttp.BasicAuth) – basic authentication info used for proxies with authorization.
Note
ProxyConnector
in opposite to all other connectors doesn’t support keep-alives by default (force_close
isTrue
).Changed in version 0.16: force_close parameter changed to
True
by default.- proxy (str) – URL for proxy, e.g.
UnixConnector¶
-
class
aiohttp.
UnixConnector
(path, *, conn_timeout=None, keepalive_timeout=30, limit=None, share_cookies=False, force_close=False, loop=None)[source]¶ Unix socket connector.
Use
ProxyConnector
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 fromBaseConnector
.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
Connection¶
-
class
aiohttp.
Connection
¶ Encapsulates single connection in connector object.
End user should never create
Connection
instances manually but get it byBaseConnector.connect()
coroutine.-
loop
¶ Event loop used for connection
-
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 be
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 (seerelease()
coroutine).New in version 0.18: Support for
async with
.-
version
¶ Response’s version,
HttpVersion
instance.
-
connection
¶ Connection
used for handling response.
-
content
¶ Payload stream, contains response’s BODY (
StreamReader
compatible instance, most likelyFlowControlStreamReader
one).
HTTP cookies of response (Set-Cookie HTTP header,
SimpleCookie
).
-
headers
¶ A case-insensitive multidict proxy with HTTP headers of response,
CIMultiDictProxy
.
-
raw_headers
¶ HTTP headers of response as unconverted bytes, a sequence of
(key, value)
pairs.
-
history
¶ A
Sequence
ofClientResponse
objects of preceding requests if there were redirects, an empty sequence otherwise.
-
close
()¶ Close response and underlying connection.
For keep-alive support see
release()
.
-
coroutine
read
()¶ Read the whole response’s body as
bytes
.Close underlying connection if data reading gets an error, release connection otherwise.
Return bytes: read BODY.
-
coroutine
release
()¶ Finish response processing, release underlying connection and return it into free connection pool for re-usage by next upcoming request.
-
coroutine
text
(encoding=None)¶ Read response’s body and return decoded
str
using specified encoding parameter.If encoding is
None
content encoding is autocalculated using cchardet or chardet as fallback if cchardet is not available.Close underlying connection if data reading gets an error, release connection otherwise.
Parameters: encoding (str) – text encoding used for BODY decoding, or None
for encoding autodetection (default).Return str: decoded BODY
-
coroutine
json
(encoding=None, loads=json.loads)¶ Read response’s body as JSON, return
dict
using specified encoding and loader.If encoding is
None
content encoding is autocalculated using cchardet or chardet as fallback if cchardet is not available.Close underlying connection if data reading gets an error, release connection otherwise.
Parameters: - encoding (str) – text encoding used for BODY decoding, or
None
for encoding autodetection (default). - loads (callable) –
callable()
used for loading JSON data,json.loads()
by default.
Returns: BODY as JSON data parsed by loads parameter or
None
if BODY is empty or contains white-spaces only.- encoding (str) – text encoding used for BODY decoding, or
-
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
¶ Class for handling client-side websockets.
-
closed
¶ Read-only property,
True
ifclose()
has been called ofMSG_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.
-
exception
()¶ Returns exception if any occurs or returns None.
-
ping
(message=b'')¶ Send
MSG_PING
to peer.Parameters: message – optional payload of ping message, str
(converted to UTF-8 encoded bytes) orbytes
.
-
send_str
(data)¶ Send data to peer as
MSG_TEXT
message.Parameters: data (str) – data to send. Raises: TypeError – if data is not str
-
send_bytes
(data)¶ Send data to peer as
MSG_BINARY
message.Parameters: data – data to send. Raises: TypeError – if data is not bytes
,bytearray
ormemoryview
.
-
coroutine
close
(*, code=1000, message=b'')¶ A coroutine that initiates closing handshake by sending
MSG_CLOSE
message. It waits for close response from server. It add timeout to close() call just wrap call with asyncio.wait() or asyncio.wait_for().Parameters:
-
coroutine
receive
()¶ A coroutine that waits upcoming data message from peer and returns it.
The coroutine implicitly handles
MSG_PING
,MSG_PONG
andMSG_CLOSE
without returning the message.It process ping-pong game and performs closing handshake internally.
Returns: Message
, tp is types of ~aiohttp.MsgType
-
Utilities¶
BasicAuth¶
-
class
aiohttp.
BasicAuth
(login, password='', encoding='latin1')[source]¶ HTTP basic authentication helper.
Parameters: Should be used for specifying authorization data in client API, e.g. auth parameter for
ClientSession.request()
.