Helpers API

All public names from submodules errors, multipart, parsers, protocol, utils, and wsgi are exported into aiohttp namespace.

WebSocket utilities

class aiohttp.WSCloseCode[source]

An IntEnum for keeping close message code.


A normal closure, meaning that the purpose for which the connection was established has been fulfilled.


An endpoint is “going away”, such as a server going down or a browser having navigated away from a page.


An endpoint is terminating the connection due to a protocol error.


An endpoint is terminating the connection because it has received a type of data it cannot accept (e.g., an endpoint that understands only text data MAY send this if it receives a binary message).


An endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the message (e.g., non-UTF-8 RFC 3629 data within a text message).


An endpoint is terminating the connection because it has received a message that violates its policy. This is a generic status code that can be returned when there is no other more suitable status code (e.g., unsupported_data or message_too_big) or if there is a need to hide specific details about the policy.


An endpoint is terminating the connection because it has received a message that is too big for it to process.


An endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the server didn’t return them in the response message of the WebSocket handshake. The list of extensions that are needed should appear in the /reason/ part of the Close frame. Note that this status code is not used by the server, because it can fail the WebSocket handshake instead.


A server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.


The service is restarted. a client may reconnect, and if it chooses to do, should reconnect using a randomized delay of 5-30s.


The service is experiencing overload. A client should only connect to a different IP (when there are multiple for the target) or reconnect to the same IP upon user action.

class aiohttp.WSMsgType[source]

An IntEnum for describing WSMessage type.


A mark for continuation frame, user will never get the message with this type.


Text message, the value has str type.


Binary message, the value has bytes type.


Ping frame (sent by client peer).


Pong frame, answer on ping. Sent by server peer.


Close frame.


Actually not frame but a flag indicating that websocket was closed.


Actually not frame but a flag indicating that websocket was received an error.

class aiohttp.WSMessage[source]

Websocket message, returned by .receive() calls.


Message type, WSMsgType instance.


Message payload.

  1. str for WSMsgType.TEXT messages.
  2. bytes for WSMsgType.BINARY messages.
  3. WSCloseCode for WSMsgType.CLOSE messages.
  4. bytes for WSMsgType.PING messages.
  5. bytes for WSMsgType.PONG messages.

Additional info, str.

Makes sense only for WSMsgType.CLOSE messages, contains optional message description.

json(*, loads=json.loads)[source]

Returns parsed JSON data.

New in version 0.22.

Parameters:loads – optional JSON decoder function.

Deprecated alias for type.

Deprecated since version 1.0.

aiohttp.errors module

HTTP related errors.

exception aiohttp.errors.DisconnectedError[source]

Bases: Exception


exception aiohttp.errors.ClientDisconnectedError[source]

Bases: aiohttp.errors.DisconnectedError

Client disconnected.

exception aiohttp.errors.ServerDisconnectedError[source]

Bases: aiohttp.errors.DisconnectedError

Server disconnected.

exception aiohttp.errors.HttpProcessingError(*, code=None, message='', headers=None)[source]

Bases: Exception

HTTP error.

Shortcut for raising HTTP errors with custom code, message and headers.

  • code (int) – HTTP Error code.
  • message (str) – (optional) Error message.
  • of [tuple] headers (list) – (optional) Headers to be sent in response.
code = 0
headers = None
message = ''
exception aiohttp.errors.BadHttpMessage(message, *, headers=None)[source]

Bases: aiohttp.errors.HttpProcessingError

code = 400
message = 'Bad Request'
exception aiohttp.errors.HttpMethodNotAllowed(*, code=None, message='', headers=None)[source]

Bases: aiohttp.errors.HttpProcessingError

code = 405
message = 'Method Not Allowed'
exception aiohttp.errors.HttpBadRequest(message, *, headers=None)[source]

Bases: aiohttp.errors.BadHttpMessage

code = 400
message = 'Bad Request'
exception aiohttp.errors.HttpProxyError(*, code=None, message='', headers=None)[source]

Bases: aiohttp.errors.HttpProcessingError

HTTP proxy error.

Raised in aiohttp.connector.ProxyConnector if proxy responds with status other than 200 OK on CONNECT request.

exception aiohttp.errors.BadStatusLine(line='')[source]

Bases: aiohttp.errors.BadHttpMessage

exception aiohttp.errors.LineTooLong(line, limit='Unknown')[source]

Bases: aiohttp.errors.BadHttpMessage

exception aiohttp.errors.InvalidHeader(hdr)[source]

Bases: aiohttp.errors.BadHttpMessage

exception aiohttp.errors.ClientError[source]

Bases: Exception

Base class for client connection errors.

exception aiohttp.errors.ClientHttpProcessingError[source]

Bases: aiohttp.errors.ClientError

Base class for client HTTP processing errors.

exception aiohttp.errors.ClientConnectionError[source]

Bases: aiohttp.errors.ClientError

Base class for client socket errors.

exception aiohttp.errors.ClientOSError[source]

Bases: aiohttp.errors.ClientConnectionError, OSError

OSError error.

exception aiohttp.errors.ClientTimeoutError[source]

Bases: aiohttp.errors.ClientConnectionError, concurrent.futures._base.TimeoutError

Client connection timeout error.

exception aiohttp.errors.ProxyConnectionError[source]

Bases: aiohttp.errors.ClientConnectionError

Proxy connection error.

Raised in aiohttp.connector.ProxyConnector if connection to proxy can not be established.

exception aiohttp.errors.ClientRequestError[source]

Bases: aiohttp.errors.ClientHttpProcessingError

Connection error during sending request.

exception aiohttp.errors.ClientResponseError[source]

Bases: aiohttp.errors.ClientHttpProcessingError

Connection error during reading response.

exception aiohttp.errors.FingerprintMismatch(expected, got, host, port)[source]

Bases: aiohttp.errors.ClientConnectionError

SSL certificate does not match expected fingerprint.

exception aiohttp.errors.WSServerHandshakeError(*, code=None, message='', headers=None)[source]

Bases: aiohttp.errors.HttpProcessingError

websocket server handshake error.

aiohttp.helpers module

Various helper functions


Compatibility wrapper for the loop.create_future() call introduced in 3.5.2.

class aiohttp.helpers.FormData(fields=(), quote_fields=True)[source]

Bases: object

Helper class for multipart/form-data and application/x-www-form-urlencoded body generation.

add_field(name, value, *, content_type=None, filename=None, content_transfer_encoding=None)[source]

Parses a MIME type into its components.

Parameters:mimetype (str) – MIME type
Returns:4 element tuple for MIME type, subtype, suffix and parameters
Return type:tuple


>>> parse_mimetype('text/html; charset=utf-8')
('text', 'html', '', {'charset': 'utf-8'})

alias of timeout

aiohttp.helpers.ensure_future(coro_or_future, *, loop=None)[source]

Wrap a coroutine or an awaitable in a future.

If the argument is a Future, it is returned directly.

coroutine aiohttp.helpers.noop(*args, **kwargs)[source]

aiohttp.multipart module

class aiohttp.multipart.MultipartReader(headers, content)[source]

Bases: object

Multipart body reader.


Returns True if the final boundary was reached or False otherwise.

Return type:bool
coroutine fetch_next_part()[source]

Returns the next body part reader.

classmethod from_response(response)[source]

Constructs reader instance from HTTP response.

Parameters:responseClientResponse instance
multipart_reader_cls = None

Multipart reader class, used to handle multipart/* body parts. None points to type(self)

coroutine next()[source]

Emits the next multipart body part.


Body part reader class for non multipart/* content types.

alias of BodyPartReader

coroutine release()[source]

Reads all the body parts to the void till the final boundary.


Response wrapper, used when multipart readers constructs from response.

alias of MultipartResponseWrapper

class aiohttp.multipart.MultipartWriter(subtype='mixed', boundary=None)[source]

Bases: object

Multipart body writer.

append(obj, headers=None)[source]

Adds a new body part to multipart writer.

append_form(obj, headers=None)[source]

Helper to append form urlencoded part.

append_json(obj, headers=None)[source]

Helper to append JSON part.


Body part reader class for non multipart/* content types.

alias of BodyPartWriter


Yields multipart byte chunks.

class aiohttp.multipart.BodyPartReader(boundary, headers, content)[source]

Bases: object

Multipart reader for single body part.


Returns True if the boundary was reached or False otherwise.

Return type:bool
chunk_size = 8192

Decodes data according the specified Content-Encoding or Content-Transfer-Encoding headers value.

Supports gzip, deflate and identity encodings for Content-Encoding header.

Supports base64, quoted-printable, binary encodings for Content-Transfer-Encoding header.

Parameters:data (bytearray) – Data to decode.
Raises:RuntimeError - if encoding is unknown.
Return type:bytes

Returns filename specified in Content-Disposition header or None if missed or header is malformed.

coroutine form(*, encoding=None)[source]

Like read(), but assumes that body parts contains form urlencoded data.

Parameters:encoding (str) – Custom form encoding. Overrides specified in charset param of Content-Type header

Returns charset parameter from Content-Type header or default.

coroutine json(*, encoding=None)[source]

Like read(), but assumes that body parts contains JSON data.

Parameters:encoding (str) – Custom JSON encoding. Overrides specified in charset param of Content-Type header
coroutine next()[source]
coroutine read(*, decode=False)[source]

Reads body part data.

Parameters:decode (bool) – Decodes data following by encoding method from Content-Encoding header. If it missed data remains untouched
Return type:bytearray
coroutine read_chunk(size=8192)[source]

Reads body part content chunk of the specified size.

Parameters:size (int) – chunk size
Return type:bytearray
coroutine readline()[source]

Reads body part by line by line.

Return type:bytearray
coroutine release()[source]

Like read(), but reads all the data to the void.

Return type:None
coroutine text(*, encoding=None)[source]

Like read(), but assumes that body part contains text data.

Parameters:encoding (str) – Custom text encoding. Overrides specified in charset param of Content-Type header
Return type:str
class aiohttp.multipart.BodyPartWriter(obj, headers=None, *, chunk_size=8192)[source]

Bases: object

Multipart writer for single body part.


Returns filename specified in Content-Disposition header or None if missed.


Yields byte chunks for body part.

set_content_disposition(disptype, quote_fields=True, **params)[source]

Sets Content-Disposition header.

  • disptype (str) – Disposition type: inline, attachment, form-data. Should be valid extension token (see RFC 2183)
  • params (dict) – Disposition params
exception aiohttp.multipart.BadContentDispositionHeader[source]

Bases: RuntimeWarning

exception aiohttp.multipart.BadContentDispositionParam[source]

Bases: RuntimeWarning


aiohttp.parsers module

Parser is a generator function (NOT coroutine).

Parser receives data with generator’s send() method and sends data to destination DataQueue. Parser receives ParserBuffer and DataQueue objects as a parameters of the parser call, all subsequent send() calls should send bytes objects. Parser sends parsed term to destination buffer with DataQueue.feed_data() method. DataQueue object should implement two methods. feed_data() - parser uses this method to send parsed protocol data. feed_eof() - parser uses this method for indication of end of parsing stream. To indicate end of incoming data stream EofStream exception should be sent into parser. Parser could throw exceptions.

There are three stages:

  • Data flow chain:

    1. Application creates StreamParser object for storing incoming data.

    2. StreamParser creates ParserBuffer as internal data buffer.

    3. Application create parser and set it into stream buffer:

      parser = HttpRequestParser() data_queue = stream.set_parser(parser)

    1. At this stage StreamParser creates DataQueue object and passes it and internal buffer into parser as an arguments.

      def set_parser(self, parser):

      output = DataQueue() self.p = parser(output, self._input) return output

    2. Application waits data on

      while True:

      msg = yield from ...

  • Data flow:

    1. asyncio’s transport reads data from socket and sends data to protocol with data_received() call.
    2. Protocol sends data to StreamParser with feed_data() call.
    3. StreamParser sends data into parser with generator’s send() method.
    4. Parser processes incoming data and sends parsed data to DataQueue with feed_data()
    5. Application received parsed data from
  • Eof:

    1. StreamParser receives eof with feed_eof() call.
    2. StreamParser throws EofStream exception into parser.
    3. Then it unsets parser.
_SocketSocketTransport ->
-> “protocol” -> StreamParser -> “parser” -> DataQueue <- “application”
exception aiohttp.parsers.EofStream[source]

Bases: Exception

eof stream indication.

class aiohttp.parsers.StreamParser(*, loop=None, buf=None, limit=65536, eof_exc_class=<class 'RuntimeError'>)[source]

Bases: object

StreamParser manages incoming bytes stream and protocol parsers.

StreamParser uses ParserBuffer as internal buffer.

set_parser() sets current parser, it creates DataQueue object and sends ParserBuffer and DataQueue into parser generator.

unset_parser() sends EofStream into parser and then removes it.


send data to current parser or store in buffer.


send eof to all parsers, recursively.

set_parser(parser, output=None)[source]

set parser to stream. return parser’s DataQueue.


unset parser, send eof to the parser and then remove it.

class aiohttp.parsers.StreamProtocol(*, loop=None, disconnect_error=<class 'RuntimeError'>, **kwargs)[source]

Bases: asyncio.streams.FlowControlMixin, asyncio.protocols.Protocol

Helper class to adapt between Protocol and StreamReader.

class aiohttp.parsers.ParserBuffer(*args)[source]

Bases: object

ParserBuffer is NOT a bytearray extension anymore.

ParserBuffer provides helper methods for parsers.


read() reads specified amount of bytes.


reads size of less amount of bytes.

readuntil(stop, limit=None)[source]

skip() skips specified amount of bytes.


skipuntil() reads until stop bytes sequence.


wait() waits for specified amount of bytes then returns data without changing internal buffer.

waituntil(stop, limit=None)[source]

waituntil() reads until stop bytes sequence.

class aiohttp.parsers.StreamWriter(transport, protocol, reader, loop)[source]

Bases: asyncio.streams.StreamWriter


aiohttp.signals module

class aiohttp.signals.BaseSignal(items=None)[source]

Bases: aiohttp.helpers.FrozenList

class aiohttp.signals.DebugSignal(items=None)[source]

Bases: aiohttp.signals.BaseSignal

coroutine send(ordinal, name, *args, **kwargs)[source]
class aiohttp.signals.PostSignal(items=None)[source]

Bases: aiohttp.signals.DebugSignal

class aiohttp.signals.PreSignal[source]

Bases: aiohttp.signals.DebugSignal

class aiohttp.signals.Signal(app)[source]

Bases: aiohttp.signals.BaseSignal

Coroutine-based signal implementation.

To connect a callback to a signal, use any list method.

Signals are fired using the send() coroutine, which takes named arguments.

coroutine send(*args, **kwargs)[source]

Sends data to all registered receivers.

aiohttp.wsgi module

wsgi server.

  • proxy protocol
  • x-forward security
  • wsgi file support (os.sendfile)
class aiohttp.wsgi.WSGIServerHttpProtocol(app, readpayload=False, is_ssl=False, *args, **kw)[source]

Bases: aiohttp.server.ServerHttpProtocol

HTTP Server that implements the Python WSGI protocol.

It uses ‘wsgi.async’ of ‘True’. ‘wsgi.input’ can behave differently depends on ‘readpayload’ constructor parameter. If readpayload is set to True, wsgi server reads all incoming data into BytesIO object and sends it as ‘wsgi.input’ environ var. If readpayload is set to false ‘wsgi.input’ is a StreamReader and application should read incoming data with “yield from environ[‘wsgi.input’].read()”. It defaults to False.

create_wsgi_environ(message, payload)[source]
coroutine handle_request(message, payload)[source]

Handle a single HTTP request

blog comments powered by Disqus