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

0.17

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

The class for creating client sessions and making requests.

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

0.21

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.helpers.DummyCookieJar instance can be provided.

0.22

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.

2.0

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.
param float conn_timeout: timeout for connection establishing (optional). Values 0 or None mean no timeout.
param bool connector_owner

Close connector instance on session closing.

Passing connector_owner=False to constructor allows to share connection pool between sessions without sharing session state: cookies etc.

2.1

param bool auto_decompress: Automatically decompress response body

2.3

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

Gives access to cookie jar's content and modifiers.

A read-only property.

1.0

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.

loop

A loop instance used for session creation.

A read-only property.

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,read_until_eof=True, proxy=None, proxy_auth=None,timeout=560)

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

Dictionary, bytes, or file-like object to send in the body of the request (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 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 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 read_until_eof

Read response until EOF if response does not have Content-Length header. True by default (optional).

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 (read_timeout) for IO operations.

return ClientResponse

a client response <ClientResponse> object.

1.0

Added proxy and proxy_auth parameters.

Added timeout parameter.

1.1

URLs may be either str or ~yarl.URL

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

Perform a GET request.

In order to modify inner request<aiohttp.client.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.

1.1

URLs may be either str or ~yarl.URL

post(url, , data=None,*kwargs)

Perform a POST request.

In order to modify inner request<aiohttp.client.ClientSession.request> parameters, provide kwargs.

param url: Request URL, str or ~yarl.URL
param data: Dictionary, bytes, or file-like object to send in the body of the request (optional)
return ClientResponse: a client response <ClientResponse> object.

1.1

URLs may be either str or ~yarl.URL

put(url, , data=None,*kwargs)

Perform a PUT request.

In order to modify inner request<aiohttp.client.ClientSession.request> parameters, provide kwargs.

param url: Request URL, str or ~yarl.URL
param data: Dictionary, bytes, or file-like object to send in the body of the request (optional)
return ClientResponse: a client response <ClientResponse> object.

1.1

URLs may be either str or ~yarl.URL

delete(url, **kwargs)

Perform a DELETE request.

In order to modify inner request<aiohttp.client.ClientSession.request> parameters, provide kwargs.

param url: Request URL, str or ~yarl.URL
return ClientResponse: a client response <ClientResponse> object.

1.1

URLs may be either str or ~yarl.URL

head(url, , allow_redirects=False,*kwargs)

Perform a HEAD request.

In order to modify inner request<aiohttp.client.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.

1.1

URLs may be either str or ~yarl.URL

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

Perform an OPTIONS request.

In order to modify inner request<aiohttp.client.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.

1.1

URLs may be either str or ~yarl.URL

patch(url, , data=None,*kwargs)

Perform a PATCH request.

In order to modify inner request<aiohttp.client.ClientSession.request> parameters, provide kwargs.

param url: Request URL, str or ~yarl.URL
param data: Dictionary, bytes, or file-like object to send in the body of the request (optional)
return ClientResponse: a client response <ClientResponse> object.

1.1

URLs may be either str or ~yarl.URL

ws_connect(url, *, protocols=(), timeout=10.0,receive_timeout=None,auth=None,autoclose=True,autoping=True,heartbeat=None,origin=None, proxy=None, proxy_auth=None)

Create a websocket connection. Returns a ClientWebSocketResponse object.

param url: Websocket server url, str or ~yarl.URL
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 them close procedure has to be handled manually
param bool autoping: automatically send pong on ping message from server
param float heartbeat: Send ping message every heartbeat seconds and wait pong response, if pong response is not received then close connection.
param str origin: Origin header to send to server
param str proxy: Proxy URL, str or ~yarl.URL (optional)
param aiohttp.BasicAuth proxy_auth: an object that represents proxy HTTP Basic Authorization (optional)

0.16

Add ws_connect.

0.18

Add auth parameter.

0.19

Add origin parameter.

1.0

Added proxy and proxy_auth parameters.

1.1

URLs may be either str or ~yarl.URL

close()

Close underlying connector.

Release all acquired resources.

detach()

Detach connector from session without closing the former.

Session is switched to closed state anyway.

Basic API

While we encourage ClientSession usage we also provide simple coroutines for making HTTP requests.

Basic API is good for performing simple HTTP requests without keepaliving, cookies and complex connection stuff like properly configured SSL certification chaining.

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, connector=None, loop=None,read_until_eof=True)

Perform an asynchronous HTTP request. Return a response object (ClientResponse or derived from).

param str method: HTTP method
param url: Requested URL, str or ~yarl.URL
param dict params: Parameters to be sent in the query string of the new request (optional)
param data: Dictionary, bytes, or file-like object to send in the body of the request (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 aiohttp.connector.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 loop: event loop<asyncio-event-loop> used for processing HTTP requests. If param is None, 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())

1.1

URLs may be either str or ~yarl.URL

Connectors

Connectors are transports for aiohttp client API.

There are standard connectors:

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

All connector classes should be derived from BaseConnector.

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

BaseConnector

Base class for all connectors.

param float keepalive_timeout: timeout for connection reusing after releasing (optional). Values 0. For disabling keep-alive feature use force_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 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: None).
param bool force_close: do close underlying sockets after connection releasing (optional).
param loop: event loop<asyncio-event-loop> used for handling connections. If param is None, 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.

0.16

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.

2.0

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

TCPConnector

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 bool verify_ssl

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

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.

0.16

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.

0.17

1.0

The default is changed to True

param int ttl_dns_cache

expire after some seconds the DNS entries, None means cached forever. By default 10 seconds.

By default DNS entries are cached forever, 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.

2.0.8

param aiohttp.abc.AbstractResolver resolver

Custom resolver instance to use. aiohttp.DefaultResolver by default (asynchronous if aiodns>=1.1 is installed).

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

1.1

The resolver is aiohttp.ThreadedResolver by default, asynchronous version is not 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.

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

0.21

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

verify_ssl

Check ssl certifications if True.

Read-only bool property.

ssl_context

ssl.SSLContext instance for https requests, read-only property.

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.

0.17

cached_hosts

The cache of resolved hosts if dns_cache is enabled.

Read-only types.MappingProxyType property.

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.

0.16

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.

0.17

UnixConnector

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.

Connection

Encapsulates single connection in connector object.

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

closed

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

loop

Event loop used for connection

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.

detach()

Detach underlying socket from connection.

Underlying socket is not closed, next close or release calls don't return socket to free pool.

Response object

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

0.18

Support for async with.

version

Response's version, HttpVersion instance.

status

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

reason

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

method

Request's method (str).

url

URL of request (~yarl.URL).

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.

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.

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 chardet tool if the header is not provided by server.

cchardet is used with fallback to chardet 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

Note

If response has no charset info in Content-Type HTTP header cchardet / chardet 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 chardet 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).
param 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, pass None 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 ClientRequest object, aiohttp.RequestInfo instance.

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 for handling client-side websockets.

closed

Read-only property, True if close has been called of ~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) or bytes.

send_str(data)

Send data to peer as ~aiohttp.WSMsgType.TEXT message.

param str data: data to send.
raise TypeError: if data is not str

send_bytes(data)

Send data to peer as ~aiohttp.WSMsgType.BINARY message.

param data: data to send.
raise TypeError: if data is not bytes, bytearray or memoryview.

send_json(data, *, dumps=json.loads)

Send data to peer as JSON string.

param data: data to send.
param 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 not str

close(*, code=1000, 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
param message: optional payload of pong message, str (converted to UTF-8 encoded bytes) or bytes.

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 callable loads: any callable that accepts str and returns dict 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.

Utilities

RequestInfo

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

url

Requested url, yarl.URL instance.

method

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

headers

HTTP headers for request, multidict.CIMultiDict instance.

BasicAuth

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.

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.

encode()

Encode credentials into string suitable for Authorization header etc.

return: encoded authentication data, str.

CookieJar

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

Implements cookie storage adhering to RFC 6265.

param bool unsafe: (optional) Whether to accept cookies from IPs.
param bool loop: an event loop<asyncio-event-loop> instance. See aiohttp.abc.AbstractCookieJar

2.0

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 str 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 str 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 or pathlib.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 or pathlib.Path instance.

Client exceptions

Exception hierarchy has been significantly modified in version 2.0. aiohttp defines only exceptions that covers connection handling and server response misbehaviors. For developer specific mistakes, aiohttp uses python standard exceptions like ValueError or TypeError.

Reading a response content may raise a ClientPayloadError exception. This exception indicates errors specific to the payload encoding. Such as invalid compressed data, malformed chunked-encoded chunks or not enough data that satisfy the content-length header.

All exceptions are available as members of aiohttp module.

ClientError

Base class for all client specific exceptions.

Derived from Exception

Response errors

ClientResponseError

These exceptions could happen after we get response from server.

Derived from ClientError

request_info

Instance of RequestInfo object, contains information about request.

history

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

A tuple of ClientResponse objects used for handle redirection responses.

Web socket server response error.

Derived from ClientResponseError

Proxy response error.

Derived from ClientResponseError

Connection errors

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 ClientConnectonError

Server disconnected.

Derived from ServerDisconnectonError

message

Partially parsed HTTP message (optional).

Server operation timeout: read timeout, etc.

Derived from ServerConnectonError and asyncio.TimeoutError

Server fingerprint mismatch.

Derived from ServerConnectonError

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

Hierarchy of exceptions

ClientError
- ClientResponseError
  - WSServerHandshakeError
  - ClientHttpProxyError
- ClientConnectionError
  - ClientOSError
    - ClientConnectorError
      ClientProxyConnectionError
    - ServerConnectionError
      ServerDisconnectedError
      
      ServerTimeoutError
    - ServerFingerprintMismatch
- ClientPayloadError

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

client_reference.rst

client_reference.rst

Client Reference

Client Session

Basic API

Connectors

BaseConnector

TCPConnector

UnixConnector

Connection

Response object

ClientWebSocketResponse

Utilities

RequestInfo

BasicAuth

CookieJar

Client exceptions

Response errors

Connection errors

Hierarchy of exceptions

Files

client_reference.rst

Latest commit

History

client_reference.rst

File metadata and controls

Client Reference

Client Session

Basic API

Connectors

BaseConnector

TCPConnector

UnixConnector

Connection

Response object

ClientWebSocketResponse

Utilities

RequestInfo

BasicAuth

CookieJar

Client exceptions

Response errors

Connection errors

Hierarchy of exceptions