Client Quickstart¶

Eager to get started? This page gives a good introduction in how to get started with aiohttp client API.

First, make sure that aiohttp is installed and up-to-date

Let’s get started with some simple examples.

Make a Request¶

Begin by importing the aiohttp module:

import aiohttp

Now, let’s try to get a web-page. For example let’s query http://httpbin.org/get:

async with aiohttp.ClientSession() as session:
    async with session.get('http://httpbin.org/get') as resp:
        print(resp.status)
        print(await resp.text())

Now, we have a ClientSession called session and a ClientResponse object called resp. We can get all the information we need from the response. The mandatory parameter of ClientSession.get() coroutine is an HTTP url (str or class:yarl.URL instance).

In order to make an HTTP POST request use ClientSession.post() coroutine:

session.post('http://httpbin.org/post', data=b'data')

Other HTTP methods are available as well:

session.put('http://httpbin.org/put', data=b'data')
session.delete('http://httpbin.org/delete')
session.head('http://httpbin.org/get')
session.options('http://httpbin.org/get')
session.patch('http://httpbin.org/patch', data=b'data')

Note

Don’t create a session per request. Most likely you need a session per application which performs all requests altogether.

More complex cases may require a session per site, e.g. one for Github and other one for Facebook APIs. Anyway making a session for every request is a very bad idea.

A session contains a connection pool inside. Connection reusage and keep-alives (both are on by default) may speed up total performance.

Passing Parameters In URLs¶

You often want to send some sort of data in the URL’s query string. If you were constructing the URL by hand, this data would be given as key/value pairs in the URL after a question mark, e.g. httpbin.org/get?key=val. Requests allows you to provide these arguments as a dict, using the params keyword argument. As an example, if you wanted to pass key1=value1 and key2=value2 to httpbin.org/get, you would use the following code:

params = {'key1': 'value1', 'key2': 'value2'}
async with session.get('http://httpbin.org/get',
                       params=params) as resp:
    expect = 'http://httpbin.org/get?key2=value2&key1=value1'
    assert str(resp.url) == expect

You can see that the URL has been correctly encoded by printing the URL.

For sending data with multiple values for the same key MultiDict may be used as well.

It is also possible to pass a list of 2 item tuples as parameters, in that case you can specify multiple values for each key:

params = [('key', 'value1'), ('key', 'value2')]
async with session.get('http://httpbin.org/get',
                       params=params) as r:
    expect = 'http://httpbin.org/get?key=value2&key=value1'
    assert str(r.url) == expect

You can also pass str content as param, but beware – content is not encoded by library. Note that + is not encoded:

async with session.get('http://httpbin.org/get',
                       params='key=value+1') as r:
        assert str(r.url) == 'http://httpbin.org/get?key=value+1'

Note

aiohttp internally performs URL canonization before sending request.

Canonization encodes host part by IDNA codec and applies requoting to path and query parts.

For example URL('http://example.com/путь%30?a=%31') is converted to URL('http://example.com/%D0%BF%D1%83%D1%82%D1%8C/0?a=1').

Sometimes canonization is not desirable if server accepts exact representation and does not requote URL itself.

To disable canonization use encoded=True parameter for URL construction:

await session.get(
    URL('http://example.com/%30', encoded=True))

Warning

Passing params overrides encoded=True, never use both options.

Response Content and Status Code¶

We can read the content of the server’s response and it’s status code. Consider the GitHub time-line again:

async with session.get('https://api.github.com/events') as resp:
    print(resp.status)
    print(await resp.text())

prints out something like:

200
'[{"created_at":"2015-06-12T14:06:22Z","public":true,"actor":{...

aiohttp automatically decodes the content from the server. You can specify custom encoding for the text() method:

await resp.text(encoding='windows-1251')

Binary Response Content¶

You can also access the response body as bytes, for non-text requests:

print(await resp.read())

b'[{"created_at":"2015-06-12T14:06:22Z","public":true,"actor":{...

The gzip and deflate transfer-encodings are automatically decoded for you.

You can enable brotli transfer-encodings support, just install brotlipy.

JSON Request¶

Any of session’s request methods like request(), ClientSession.get(), ClientSesssion.post() etc. accept json parameter:

async with aiohttp.ClientSession() as session:
    async with session.post(url, json={'test': 'object'})

By default session uses python’s standard json module for serialization. But it is possible to use different serializer. ClientSession accepts json_serialize parameter:

import ujson

async with aiohttp.ClientSession(
        json_serialize=ujson.dumps) as session:
    await session.post(url, json={'test': 'object'})

Note

ujson library is faster than standard json but slightly incompatible.

JSON Response Content¶

There’s also a built-in JSON decoder, in case you’re dealing with JSON data:

async with session.get('https://api.github.com/events') as resp:
    print(await resp.json())

In case that JSON decoding fails, json() will raise an exception. It is possible to specify custom encoding and decoder functions for the json() call.

Note

The methods above reads the whole response body into memory. If you are planning on reading lots of data, consider using the streaming response method documented below.

Streaming Response Content¶

While methods read(), json() and text() are very convenient you should use them carefully. All these methods load the whole response in memory. For example if you want to download several gigabyte sized files, these methods will load all the data in memory. Instead you can use the content attribute. It is an instance of the aiohttp.StreamReader class. The gzip and deflate transfer-encodings are automatically decoded for you:

async with session.get('https://api.github.com/events') as resp:
    await resp.content.read(10)

In general, however, you should use a pattern like this to save what is being streamed to a file:

with open(filename, 'wb') as fd:
    while True:
        chunk = await resp.content.read(chunk_size)
        if not chunk:
            break
        fd.write(chunk)

It is not possible to use read(), json() and text() after explicit reading from content.

POST a Multipart-Encoded File¶

To upload Multipart-encoded files:

url = 'http://httpbin.org/post'
files = {'file': open('report.xls', 'rb')}

await session.post(url, data=files)

You can set the filename and content_type explicitly:

url = 'http://httpbin.org/post'
data = FormData()
data.add_field('file',
               open('report.xls', 'rb'),
               filename='report.xls',
               content_type='application/vnd.ms-excel')

await session.post(url, data=data)

If you pass a file object as data parameter, aiohttp will stream it to the server automatically. Check StreamReader for supported format information.

Streaming uploads¶

aiohttp supports multiple types of streaming uploads, which allows you to send large files without reading them into memory.

As a simple case, simply provide a file-like object for your body:

with open('massive-body', 'rb') as f:
   await session.post('http://httpbin.org/post', data=f)

Or you can use asynchronous generator:

async def file_sender(file_name=None):
    async with aiofiles.open(file_name, 'rb') as f:
        chunk = await f.read(64*1024)
        while chunk:
            yield chunk
            chunk = await f.read(64*1024)

# Then you can use file_sender as a data provider:

async with session.post('http://httpbin.org/post',
                        data=file_sender(file_name='huge_file')) as resp:
    print(await resp.text())

Because the content attribute is a StreamReader (provides async iterator protocol), you can chain get and post requests together:

resp = await session.get('http://python.org')
await session.post('http://httpbin.org/post',
                   data=resp.content)

Note

Python 3.5 has no native support for asynchronous generators, use async_generator library as workaround.

Deprecated since version 3.1: aiohttp still supports aiohttp.streamer decorator but this approach is deprecated in favor of asynchronous generators as shown above.

WebSockets¶

aiohttp works with client websockets out-of-the-box.

You have to use the aiohttp.ClientSession.ws_connect() coroutine for client websocket connection. It accepts a url as a first parameter and returns ClientWebSocketResponse, with that object you can communicate with websocket server using response’s methods:

async with session.ws_connect('http://example.org/ws') as ws:
    async for msg in ws:
        if msg.type == aiohttp.WSMsgType.TEXT:
            if msg.data == 'close cmd':
                await ws.close()
                break
            else:
                await ws.send_str(msg.data + '/answer')
        elif msg.type == aiohttp.WSMsgType.ERROR:
            break

You must use the only websocket task for both reading (e.g. await ws.receive() or async for msg in ws:) and writing but may have multiple writer tasks which can only send data asynchronously (by await ws.send_str('data') for example).

Timeouts¶

Timeout settings a stored in ClientTimeout data structure.

By default aiohttp uses a total 5min timeout, it means that the whole operation should finish in 5 minutes.

The value could be overridden by timeout parameter for the session:

timeout = aiohttp.ClientTimeout(total=60)
async with aiohttp.ClientSession(timeout=timeout) as session:
    ...

Timeout could be overridden for a request like ClientSession.get():

async with session.get(url, timeout=timeout) as resp:
    ...

Supported ClientTimeout fields are:

total

The whole operation time including connection establishment, request sending and response reading.

connect

Total timeout for acquiring a connection from pool. The time consists connection establishment for a new connection or waiting for a free connection from a pool if pool connection limits are exceeded.

sock_connect

A timeout for connecting to a peer for a new connection, not given from a pool.

sock_read

The maximum allowed timeout for period between reading a new data portion from a peer.

All fields are floats, None or 0 disables a particular timeout check.

Thus the default timeout is:

aiohttp.ClientTimeout(total=5*60, connect=None,
                      sock_connect=None, sock_read=None)

Client Quickstart¶

Make a Request¶

Passing Parameters In URLs¶

Response Content and Status Code¶

Binary Response Content¶

JSON Request¶

JSON Response Content¶

Streaming Response Content¶

More complicated POST requests¶

POST a Multipart-Encoded File¶

Streaming uploads¶

WebSockets¶

Timeouts¶