Migration to 2.x

Client

chunking

aiohttp does not support custom chunking sizes. 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.

aiohttp does not enable chunked encoding automatically even if a transfer-encoding header is supplied: chunked has to be set explicitly. If chunked is set, then the Transfer-encoding and content-length headers are disallowed.

compression

Compression has to be enabled explicitly with the compress parameter. If compression is enabled, adding a content-encoding header is not allowed. Compression also enables the chunked transfer-encoding. Compression can not be combined with a Content-Length header.

Client Connector

  1. By default a connector object manages a total number of concurrent connections. This limit was a per host rule in version 1.x. In 2.x, the limit parameter defines how many concurrent connection connector can open and a new limit_per_host parameter defines the limit per host. By default there is no per-host limit.

  2. BaseConnector.close is now a normal function as opposed to coroutine in version 1.x

  3. BaseConnector.conn_timeout was moved to ClientSession

ClientResponse.release

Internal implementation was significantly redesigned. 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

Client exceptions

Exception hierarchy has been significantly modified. aiohttp now 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 moved from aiohttp.errors module to top level aiohttp module.

New hierarchy of exceptions:

  • ClientError - Base class for all client specific exceptions

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

      • WSServerHandshakeError - web socket server response error

        • ClientHttpProxyError - proxy response

    • ClientConnectionError - exceptions related to low-level connection problems

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

        • ClientConnectorError - connector related exceptions

          • ClientProxyConnectionError - proxy connection initialization error

            • ServerConnectionError - server connection related errors

          • ServerDisconnectedError - server disconnected

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

          • ServerFingerprintMismatch - server fingerprint mismatch

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

Client payload (form-data)

To unify form-data/payload handling a new Payload system was introduced. It handles customized handling of existing types and provide implementation for user-defined types.

  1. FormData.__call__ does not take an encoding arg anymore and its return value changes from an iterator or bytes to a Payload instance. aiohttp provides payload adapters for some standard types like str, byte, io.IOBase, StreamReader or DataQueue.

  2. a generator is not supported as data provider anymore, streamer can be used instead. For example, to upload data from file:

    @aiohttp.streamer
def file_sender(writer, file_name=None):
      with open(file_name, 'rb') as f:
          chunk = f.read(2**16)
          while chunk:
              yield from writer.write(chunk)
              chunk = f.read(2**16)

# Then you can use `file_sender` like this:

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

Various

  1. the encoding parameter is deprecated in ClientSession.request(). Payload encoding is controlled at the payload level. It is possible to specify an encoding for each payload instance.

  2. the version parameter is removed in ClientSession.request() client version can be specified in the ClientSession constructor.

  3. aiohttp.MsgType dropped, use aiohttp.WSMsgType instead.

  4. ClientResponse.url is an instance of yarl.URL class (url_obj is deprecated)

  5. ClientResponse.raise_for_status() raises aiohttp.ClientResponseError exception

  6. ClientResponse.json() is strict about response’s content type. if content type does not match, it raises aiohttp.ClientResponseError exception. To disable content type check you can pass None as content_type parameter.

Server

ServerHttpProtocol and low-level details

Internal implementation was significantly redesigned to provide better performance and support HTTP pipelining. ServerHttpProtocol is dropped, implementation is merged with RequestHandler a lot of low-level api’s are dropped.

Application

  1. Constructor parameter loop is deprecated. Loop is get configured by application runner, run_app function for any of gunicorn workers.

  2. Application.router.add_subapp is dropped, use Application.add_subapp instead

  3. Application.finished is dropped, use Application.cleanup instead

WebRequest and WebResponse

  1. the GET and POST attributes no longer exist. Use the query attribute instead of GET

  2. Custom chunking size is not support WebResponse.chunked - developer is responsible for actual chunking.

  3. Payloads are supported as body. So it is possible to use client response’s content object as body parameter for WebResponse

  4. FileSender api is dropped, it is replaced with more general FileResponse class:

    async def handle(request):
    return web.FileResponse('path-to-file.txt')

  5. WebSocketResponse.protocol is renamed to WebSocketResponse.ws_protocol. WebSocketResponse.protocol is instance of RequestHandler class.

RequestPayloadError

Reading request’s payload may raise a RequestPayloadError exception. The behavior is similar to ClientPayloadError.

WSGI

WSGI support has been dropped, as well as gunicorn wsgi support. We still provide default and uvloop gunicorn workers for web.Application