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

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 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)
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 to ClientRequest

Changed in version 0.16: response_class default changed from None to ClientResponse

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.

cookies¶

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

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

Perform a GET request.