Client Reference

Client Session

Client session is the recommended interface for making HTTP requests.

Session encapsulates a connection pool (connector instance) and supports keepalives by default. Unless you are connecting to a large, unknown number of different servers over the lifetime of your application, it is suggested you use a single session for the lifetime of your application to benefit from connection pooling.

Usage example:

import aiohttp
import asyncio

async def fetch(client):
    async with client.get('http://python.org') as resp:
        assert resp.status == 200
        return await resp.text()

async def main(loop):
    async with aiohttp.ClientSession(loop=loop) as client:
        html = await fetch(client)
        print(html)

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

New in version 0.17.

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

class aiohttp.ClientSession(*, connector=None, loop=None, cookies=None, headers=None, skip_auto_headers=None, auth=None, json_serialize=func:`json.dumps`, version=aiohttp.HttpVersion11, cookie_jar=None, read_timeout=None, conn_timeout=None, raise_for_status=False)[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 every request (optional).

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

  • skip_auto_headers

    set of headers for which autogeneration should be skipped.

    aiohttp autogenerates headers like User-Agent or Content-Type if these headers are not explicitly passed. Using skip_auto_headers parameter allows to skip that generation. Note that Content-Length autogeneration can’t be skipped.

    Iterable of str or upstr (optional)

  • auth (aiohttp.BasicAuth) – an object that represents HTTP Basic Authorization (optional)
  • version

    supported HTTP version, HTTP 1.1 by default.

    New in version 0.21.

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

    New in version 0.22.

  • json_serialize (callable) – Json serializer function. (json.dumps() by default)
  • raise_for_status (bool) –

    Automatically call raise_for_status() for each response. (default is False)

    New in version 2.0.

  • read_timeout (float) – Request operations timeout. read_timeout is cumulative for all request operations (request, redirects, responses, data consuming)
  • conn_timeout (float) – timeout for connection establishing (optional). Values 0 or None mean no timeout.

Changed in version 1.0.

.cookies attribute was dropped. Use cookie_jar
instead.
closed

True if the session has been closed, False otherwise.

A read-only property.

connector
aiohttp.connector.BaseConnector derived instance used

for the session.

A read-only property.

cookie_jar

The session cookies, AbstractCookieJar instance.

Gives access to cookie jar’s content and modifiers.

A read-only property.

New in version 1.0.

loop

A loop instance used for session creation.

A read-only property.

coroutine async-with request(method, url, *, params=None, data=None, json=None, headers=None, skip_auto_headers=None, auth=None, allow_redirects=True, max_redirects=10, version=HttpVersion(major=1, minor=1), compress=None, chunked=None, expect100=False, read_until_eof=True, proxy=None, proxy_auth=None, timeout=5*60)[source]

Performs an asynchronous HTTP request. Returns a response object.

Parameters:
  • method (str) – HTTP method
  • url – Request URL, str or URL.
  • params

    Mapping, iterable of tuple of key/value pairs or string to be sent as parameters in the query string of the new request. Ignored for subsequent redirected requests (optional)

    Allowed values are:

  • data – Dictionary, bytes, or file-like object to send in the body of the request (optional)
  • json – Any json compatible python object (optional). json and data parameters could not be used at the same time.
  • headers (dict) – HTTP Headers to send with the request (optional)
  • skip_auto_headers

    set of headers for which autogeneration should be skipped.

    aiohttp autogenerates headers like User-Agent or Content-Type if these headers are not explicitly passed. Using skip_auto_headers parameter allows to skip that generation.

    Iterable of str or upstr (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. If compress can not be combined with a Content-Encoding and Content-Length headers. None by default (optional).
  • chunked (int) – Enable chunked transfer encoding. It is up to the developer to decide how to chunk data streams. If chunking is enabled, aiohttp encodes the provided chunks in the “Transfer-encoding: chunked” format. If chunked is set, then the Transfer-encoding and content-length headers are disallowed. None by default (optional).
  • expect100 (bool) – Expect 100-continue response from server. False by default (optional).
  • read_until_eof (bool) – Read response until EOF if response does not have Content-Length header. True by default (optional).
  • proxy – Proxy URL, str or URL (optional)
  • proxy_auth (aiohttp.BasicAuth) – an object that represents proxy HTTP Basic Authorization (optional)
  • timeout (int) – a timeout for IO operations, 5min by default. Use None or 0 to disable timeout checks.
Return ClientResponse:
 

a client response object.

New in version 1.0: Added proxy and proxy_auth parameters.

Added timeout parameter.

Changed in version 1.1: URLs may be either str or URL

coroutine async-with get(url, *, allow_redirects=True, **kwargs)[source]

Perform a GET request.

In order to modify inner request parameters, provide kwargs.

Parameters:
  • url – Request URL, str or URL
  • allow_redirects (bool) – If set to False, do not follow redirects. True by default (optional).
Return ClientResponse:
 

a client response object.

Changed in version 1.1: URLs may be either str or URL

coroutine async-with post(url, *, data=None, **kwargs)[source]

Perform a POST request.

In order to modify inner request parameters, provide kwargs.

Parameters:
  • url – Request URL, str or URL
  • data – Dictionary, bytes, or file-like object to send in the body of the request (optional)
Return ClientResponse:
 

a client response object.

Changed in version 1.1: URLs may be either str or URL

coroutine async-with put(url, *, data=None, **kwargs)[source]

Perform a PUT request.

In order to modify inner request parameters, provide kwargs.

Parameters:
  • url – Request URL, str or URL
  • data – Dictionary, bytes, or file-like object to send in the body of the request (optional)
Return ClientResponse:
 

a client response object.

Changed in version 1.1: URLs may be either str or URL

coroutine async-with delete(url, **kwargs)[source]

Perform a DELETE request.

In order to modify inner request parameters, provide kwargs.

Parameters:url – Request URL, str or URL
Return ClientResponse:
 a client response object.

Changed in version 1.1: URLs may be either str or URL

coroutine async-with head(url, *, allow_redirects=False, **kwargs)[source]

Perform a HEAD request.

In order to modify inner request parameters, provide kwargs.

Parameters:
  • url – Request URL, str or URL
  • allow_redirects (bool) – If set to False, do not follow redirects. False by default (optional).
Return ClientResponse:
 

a client response object.

Changed in version 1.1: URLs may be either str or URL

coroutine async-with options(url, *, allow_redirects=True, **kwargs)[source]

Perform an OPTIONS request.

In order to modify inner request parameters, provide kwargs.

Parameters:
  • url – Request URL, str or URL
  • allow_redirects (bool) – If set to False, do not follow redirects. True by default (optional).
Return ClientResponse:
 

a client response object.

Changed in version 1.1: URLs may be either str or URL

coroutine async-with patch(url, *, data=None, **kwargs)[source]

Perform a PATCH request.

In order to modify inner request parameters, provide kwargs.

Parameters:
  • url – Request URL, str or URL
  • data – Dictionary, bytes, or file-like object to send in the body of the request (optional)
Return ClientResponse:
 

a client response object.

Changed in version 1.1: URLs may be either str or URL

coroutine async-with 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)[source]

Create a websocket connection. Returns a ClientWebSocketResponse object.

Parameters:
  • url – Websocket server url, str or URL
  • protocols (tuple) – Websocket protocols
  • timeout (float) – Timeout for websocket to close. 10 seconds by default
  • receive_timeout (float) – Timeout for websocket to receive complete message. None(unlimited) 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
  • heartbeat (float) – Send ping message every heartbeat seconds and wait pong response, if pong response is not received then close connection.
  • origin (str) – Origin header to send to server
  • proxy (str) – Proxy URL, str or URL (optional)
  • proxy_auth (aiohttp.BasicAuth) – an object that represents proxy HTTP Basic Authorization (optional)

New in version 0.16: Add ws_connect().

New in version 0.18: Add auth parameter.

New in version 0.19: Add origin parameter.

New in version 1.0: Added proxy and proxy_auth parameters.

Changed in version 1.1: URLs may be either str or URL

coroutine close()[source]

Close underlying connector.

Release all acquired resources.

detach()[source]

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.

coroutine aiohttp.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)[source]

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

Parameters:
  • method (str) – HTTP method
  • url – Requested URL, str or 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)
  • json – Any json compatible python object (optional). json and data parameters could not be used at the same time.
  • headers (dict) – HTTP Headers to send with the request (optional)
  • 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. None by default (optional).
  • chunked (int) – Enables 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).
  • loopevent 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())

Changed in version 1.1: URLs may be either str or URL

Connectors

Connectors are transports for aiohttp client API.

There are standard connectors:

  1. TCPConnector for regular TCP sockets (both HTTP and HTTPS schemes supported).
  2. 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

class aiohttp.BaseConnector(*, keepalive_timeout=30, limit=100, limit_per_host=None, force_close=False, loop=None)[source]

Base class for all connectors.

Parameters:
  • keepalive_timeout (float) – timeout for connection reusing after releasing (optional). Values 0. For disabling keep-alive feature use force_close=True flag.
  • limit (int) – Total number simultaneous connections. If limit is None the connector has no limit (default: 100).
  • limit_by_host (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 is None the connector has no limit (default: None).
  • force_close (bool) – do close underlying sockets after connection releasing (optional).
  • loopevent 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)
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 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.

coroutine close()[source]

Close all opened connections.

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.
coroutine _create_connection(req)[source]

Abstract method for actual connection establishing, should be overridden in subclasses.

TCPConnector

class aiohttp.TCPConnector(*, verify_ssl=True, fingerprint=None, use_dns_cache=True, family=0, ssl_context=None, conn_timeout=None, keepalive_timeout=30, limit=None, force_close=False, loop=None, local_addr=None, disable_cleanup_closed=True)[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 from BaseConnector.

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

    New in version 0.16.

  • use_dns_cache (bool) –

    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.

    New in version 0.17.

    Changed in version 1.0: The default is changed to True

  • resolver (aiohttp.abc.AbstractResolver) –

    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.

    New in version 0.22.

    Changed in version 1.0: The resolver is aiohttp.AsyncResolver now if aiodns is installed.

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

  • enable_cleanup_closed (tuple) – 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.

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.

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.

UnixConnector

class aiohttp.UnixConnector(path, *, conn_timeout=None, keepalive_timeout=30, limit=None, force_close=False, loop=None)[source]

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:

Parameters:path (str) – Unix socket path
path

Path to UNIX socket, read-only str property.

Connection

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

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

New in version 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 (URL).

connection

Connection used for handling response.

content

Payload stream, contains response’s BODY (StreamReader).

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 mis-formed chunked encoding of broken compression data.

cookies

HTTP cookies of response (Set-Cookie HTTP header, SimpleCookie).

headers

A case-insensitive multidict proxy with HTTP headers of response, 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 RFC 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 Sequence of ClientResponse objects of preceding requests (earliest request first) if there were redirects, an empty sequence otherwise.

close()[source]

Close response and underlying connection.

For keep-alive support see release().

coroutine read()[source]

Read the whole response’s body as bytes.

Close underlying connection if data reading gets an error, release connection otherwise.

Return bytes:read BODY.

See also

close(), release().

coroutine release()[source]

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()[source]

Raise an aiohttp.ClientResponseError if the response status is 400 or higher. Do nothing for success responses (less than 400).

coroutine text(encoding=None)[source]

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, content_type='application/json')[source]

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.

if response’s content-type does not match content_type parameter aiohttp.ClientResponseError get raised. To disable content type check pass None value.

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.
  • content_type (str) – 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).
Returns:

BODY as JSON data parsed by loads parameter or None if BODY is empty or contains white-spaces only.

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[source]

Class for handling client-side websockets.

closed

Read-only property, True if close() has been called of 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)[source]

Reads extra info from connection’s transport

exception()[source]

Returns exception if any occurs or returns None.

ping(message=b'')[source]

Send PING to peer.

Parameters:message – optional payload of ping message, str (converted to UTF-8 encoded bytes) or bytes.
coroutine send_str(data)[source]

Send data to peer as TEXT message.

Parameters:data (str) – data to send.
Raises:TypeError – if data is not str
coroutine send_bytes(data)[source]

Send data to peer as BINARY message.

Parameters:data – data to send.
Raises:TypeError – if data is not bytes, bytearray or memoryview.
coroutine send_json(data, *, dumps=json.loads)[source]

Send data to peer as JSON string.

Parameters:
Raises:
coroutine close(*, code=1000, message=b'')[source]

A coroutine that initiates closing handshake by sending 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:
  • code (int) – closing code
  • message – optional payload of pong message, str (converted to UTF-8 encoded bytes) or bytes.
coroutine receive()[source]

A coroutine that waits upcoming data message from peer and returns it.

The coroutine implicitly handles PING, PONG and CLOSE without returning the message.

It process ping-pong game and performs closing handshake internally.

Returns:WSMessage, tp is a type from WSMsgType enumeration.
coroutine receive_str()[source]

A coroutine that calls receive() but also asserts the message type is TEXT.

Return str:peer’s message content.
Raises:TypeError – if message is BINARY.
coroutine receive_bytes()[source]

A coroutine that calls receive() but also asserts the message type is BINARY.

Return bytes:peer’s message content.
Raises:TypeError – if message is TEXT.
coroutine receive_json(*, loads=json.loads)[source]

A coroutine that calls receive_str() and loads the JSON string to a Python dict.

Parameters:

loads (callable) – any callable that accepts str and returns dict with parsed JSON (json.loads() by default).

Return dict:

loaded JSON content

Raises:

Utilities

BasicAuth

class aiohttp.BasicAuth(login, password='', encoding='latin1')[source]

HTTP basic authentication helper.

Parameters:
  • login (str) – login
  • password (str) – password
  • encoding (str) – encoding (‘latin1’ by default)

Should be used for specifying authorization data in client API, e.g. auth parameter for ClientSession.request().

classmethod decode(auth_header, encoding='latin1')[source]

Decode HTTP basic authentication credentials.

Parameters:
  • auth_header (str) – The Authorization header to decode.
  • encoding (str) – (optional) encoding (‘latin1’ by default)
Returns:

decoded authentication data, BasicAuth.

encode()[source]

Encode credentials into string suitable for Authorization header etc.

Returns:encoded authentication data, str.

CookieJar

class aiohttp.CookieJar(unsafe=False, loop=None)[source]

The cookie jar instance is available as ClientSession.cookie_jar.

The jar contains 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.

Parameters:
  • unsafe (bool) – (optional) Whether to accept cookies from IPs.
  • loop (bool) – an event loop instance. See aiohttp.abc.AbstractCookieJar
update_cookies(cookies, response_url=None)[source]

Update cookies returned by server in Set-Cookie header.

Parameters:
  • cookies – a collections.abc.Mapping (e.g. dict, SimpleCookie) or iterable of pairs with cookies returned by server’s response.
  • response_url (str) – 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)[source]

Return jar’s cookies acceptable for URL and available in Cookie header for sending client requests for given URL.

Parameters:response_url (str) – request’s URL for which cookies are asked.
Returns:http.cookies.SimpleCookie with filtered cookies for given URL.
save(file_path)[source]

Write a pickled representation of cookies into the file at provided path.

Parameters:file_path – Path to file where cookies will be serialized, str or pathlib.Path instance.
load(file_path)[source]

Load a pickled representation of cookies from the file at provided path.

Parameters: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 attributes in aiohttp module.

Hierarchy of exceptions:

  • aiohttp.ClientError - Base class for all client specific exceptions

    • aiohttp.ClientResponseError - exceptions that could happen after we get response from server.

      • aiohttp.WSServerHandshakeError - web socket server response error
      • aiohttp.ClientHttpProxyError - proxy response
    • aiohttp.ClientConnectionError - exceptions related to low-level connection problems

      • aiohttp.ClientOSError - subset of connection errors that are initiated by an OSError exception

        • aiohttp.ClientConnectorError - connector related exceptions

          • aiohttp.ClientProxyConnectionError - proxy connection initialization error
      • aiohttp.ServerConnectionError - server connection related errors

      • aiohttp.ServerDisconnectedError - server disconnected

      • aiohttp.ServerTimeoutError - server operation timeout, (read timeout, etc)

      • aiohttp.ServerFingerprintMismatch - server fingerprint mismatch

    • aiohttp.ClientPayloadError - This exception can only be raised while reading the response

      payload if one of these errors occurs: invalid compression, malformed chunked encoding or not enough data that satisfy content-length header.

blog comments powered by Disqus