Helpers API

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

aiohttp.errors module

http related errors.

exception aiohttp.errors.DisconnectedError[source]

Bases: Exception

Disconnected.

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.

Parameters:
  • 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(message, *, headers=None)[source]

Bases: aiohttp.errors.HttpProcessingError

websocket server handshake error.

exception aiohttp.errors.WSClientDisconnectedError[source]

Bases: aiohttp.errors.ClientDisconnectedError

Deprecated.

aiohttp.helpers module

Various helper functions

class aiohttp.helpers.BasicAuth[source]

Bases: aiohttp.helpers.BasicAuth

Http basic authentication helper.

Parameters:
  • login (str) – Login
  • password (str) – Password
  • encoding (str) – (optional) encoding (‘latin1’ by default)
encode()[source]

Encode credentials.

class aiohttp.helpers.FormData(fields=())[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]
add_fields(*fields)[source]
content_type
is_multipart
aiohttp.helpers.parse_mimetype(mimetype)[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

Example:

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

aiohttp.multipart module

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

Bases: object

Multipart body reader.

at_eof()[source]

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

Return type:bool
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)

next()[source]

Emits the next multipart body part.

part_reader_cls

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

alias of BodyPartReader

release()[source]

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

response_wrapper_cls

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.

boundary
part_writer_cls

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

alias of BodyPartWriter

serialize()[source]

Yields multipart byte chunks.

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

Bases: object

Multipart reader for single body part.

at_eof()[source]

Returns True if the boundary was reached or False otherwise.

Return type:bool
chunk_size = 8192
decode(data)[source]

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 encodings for Content-Transfer-Encoding header.

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

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

form(*, encoding=None)[source]

Lke 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
get_charset(default=None)[source]

Returns charset parameter from Content-Type header or default.

json(*, encoding=None)[source]

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

Parameters:encoding (str) – Custom JSON encoding. Overrides specified in charset param of Content-Type header
next()[source]
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
read_chunk(size=8192)[source]

Reads body part content chunk of the specified size. The body part must has Content-Length header with proper value.

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

Reads body part by line by line.

Return type:bytearray
release()[source]

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

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

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

filename

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

serialize()[source]

Yields byte chunks for body part.

set_content_disposition(disptype, **params)[source]

Sets Content-Disposition header.

Parameters:
  • 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.multipart.parse_content_disposition(header)[source]
aiohttp.multipart.content_disposition_filename(params)[source]

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 output.read()

      while True:

      msg = yield form output.read() ...

  • 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 DataQueue.read()
  • 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.

at_eof()[source]
exception()[source]
feed_data(data)[source]

send data to current parser or store in buffer.

feed_eof()[source]

send eof to all parsers, recursively.

output
set_exception(exc)[source]
set_parser(parser, output=None)[source]

set parser to stream. return parser’s DataQueue.

set_transport(transport)[source]
unset_parser()[source]

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.

connection_lost(exc)[source]
connection_made(transport)[source]
data_received(data)[source]
eof_received()[source]
is_connected()[source]
class aiohttp.parsers.ParserBuffer(*args)[source]

Bases: bytearray

ParserBuffer is a bytearray extension.

ParserBuffer provides helper methods for parsers.

exception()[source]
feed_data(data)[source]
read(size)[source]

read() reads specified amount of bytes.

readsome(size=None)[source]

reads size of less amount of bytes.

readuntil(stop, limit=None)[source]
set_exception(exc)[source]
skip(size)[source]

skip() skips specified amount of bytes.

skipuntil(stop)[source]

skipuntil() reads until stop bytes sequence.

wait(size)[source]

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.LinesParser(limit=65536)[source]

Bases: object

Lines parser.

Lines parser splits a bytes stream into a chunks of data, each chunk ends with n symbol.

class aiohttp.parsers.ChunksParser(size=8192)[source]

Bases: object

Chunks parser.

Chunks parser splits a bytes stream into a specified size chunks of data.

aiohttp.protocol module

Http related parsers and protocol.

class aiohttp.protocol.HttpMessage(transport, version, close)[source]

Bases: object

HttpMessage allows to write headers and payload to a stream.

For example, lets say we want to read file then compress it with deflate compression and then send it with chunked transfer encoding, code may look like this:

>>> response = aiohttp.Response(transport, 200)

We have to use deflate compression first:

>>> response.add_compression_filter('deflate')

Then we want to split output stream into chunks of 1024 bytes size:

>>> response.add_chunking_filter(1024)

We can add headers to response with add_headers() method. add_headers() does not send data to transport, send_headers() sends request/response line and then sends headers:

>>> response.add_headers(
...     ('Content-Disposition', 'attachment; filename="..."'))
>>> response.send_headers()

Now we can use chunked writer to write stream to a network stream. First call to write() method sends response status line and headers, add_header() and add_headers() method unavailable at this stage:

>>> with open('...', 'rb') as f:
...     chunk = fp.read(8192)
...     while chunk:
...         response.write(chunk)
...         chunk = fp.read(8192)
>>> response.write_eof()
HOP_HEADERS = None
SERVER_SOFTWARE = 'Python/3.4 aiohttp/0.16.2'
add_chunking_filter(chunk_size=16384, *, EOF_MARKER=<object object>, EOL_MARKER=<object object>)[source]

Split incoming stream into chunks.

add_compression_filter(encoding='deflate', *, EOF_MARKER=<object object>, EOL_MARKER=<object object>)[source]

Compress incoming stream with deflate or gzip encoding.

add_header(name, value)[source]

Analyze headers. Calculate content length, removes hop headers, etc.

add_headers(*headers)[source]

Adds headers to a http message.

enable_chunked_encoding()[source]
filter = None
force_close()[source]
has_chunked_hdr = False
is_headers_sent()[source]
keep_alive()[source]
send_headers(_sep=': ', _end='\r\n')[source]

Writes headers to a stream. Constructs payload writer.

status = None
status_line = b''
upgrade = False
websocket = False
write(chunk, *, drain=False, EOF_MARKER=<object object>, EOL_MARKER=<object object>)[source]

Writes chunk of data to a stream by using different writers.

writer uses filter to modify chunk of data. write_eof() indicates end of stream. writer can’t be used after write_eof() method being called. write() return drain future.

write_eof()[source]
writer = None
class aiohttp.protocol.Request(transport, method, path, http_version=HttpVersion(major=1, minor=1), close=False)[source]

Bases: aiohttp.protocol.HttpMessage

HOP_HEADERS = ()
class aiohttp.protocol.Response(transport, status, http_version=HttpVersion(major=1, minor=1), close=False, reason=None)[source]

Bases: aiohttp.protocol.HttpMessage

Create http response message.

Transport is a socket stream transport. status is a response status code, status has to be integer value. http_version is a tuple that represents http version, (1, 0) stands for HTTP/1.0 and (1, 1) is for HTTP/1.1

HOP_HEADERS = ()
static calc_reason(status)[source]
class aiohttp.protocol.HttpVersion(major, minor)

Bases: tuple

major

Alias for field number 0

minor

Alias for field number 1

class aiohttp.protocol.RawRequestMessage(method, path, version, headers, should_close, compression)

Bases: tuple

compression

Alias for field number 5

headers

Alias for field number 3

method

Alias for field number 0

path

Alias for field number 1

should_close

Alias for field number 4

version

Alias for field number 2

class aiohttp.protocol.RawResponseMessage(version, code, reason, headers, should_close, compression)

Bases: tuple

code

Alias for field number 1

compression

Alias for field number 5

headers

Alias for field number 3

reason

Alias for field number 2

should_close

Alias for field number 4

version

Alias for field number 0

class aiohttp.protocol.HttpPrefixParser(allowed_methods=())[source]

Bases: object

Waits for ‘HTTP’ prefix (non destructive)

class aiohttp.protocol.HttpRequestParser(max_line_size=8190, max_headers=32768, max_field_size=8190)[source]

Bases: aiohttp.protocol.HttpParser

Read request status line. Exception errors.BadStatusLine could be raised in case of any errors in status line. Returns RawRequestMessage.

class aiohttp.protocol.HttpResponseParser(max_line_size=8190, max_headers=32768, max_field_size=8190)[source]

Bases: aiohttp.protocol.HttpParser

Read response status line and headers.

BadStatusLine could be raised in case of any errors in status line. Returns RawResponseMessage

class aiohttp.protocol.HttpPayloadParser(message, length=None, compression=True, readall=False, response_with_body=True)[source]

Bases: object

parse_chunked_payload(out, buf)[source]

Chunked transfer encoding parser.

parse_eof_payload(out, buf)[source]

Read all bytes until eof.

parse_length_payload(out, buf, length=0)[source]

Read specified amount of bytes.

aiohttp.streams module

exception aiohttp.streams.EofStream[source]

Bases: Exception

eof stream indication.

class aiohttp.streams.StreamReader(limit=65536, loop=None)[source]

Bases: asyncio.streams.StreamReader

at_eof()[source]

Return True if the buffer is empty and ‘feed_eof’ was called.

exception()[source]
feed_data(data)[source]
feed_eof()[source]
is_eof()[source]

Return True if ‘feed_eof’ was called.

read(n=-1)[source]
read_nowait()[source]
readany()[source]
readexactly(n)[source]
readline()[source]
set_exception(exc)[source]
total_bytes = 0
wait_eof()[source]
class aiohttp.streams.DataQueue(*, loop=None)[source]

Bases: object

DataQueue is a general-purpose blocking queue with one reader.

at_eof()[source]
exception()[source]
feed_data(data, size=0)[source]
feed_eof()[source]
is_eof()[source]
read()[source]
set_exception(exc)[source]
class aiohttp.streams.ChunksQueue(*, loop=None)[source]

Bases: aiohttp.streams.DataQueue

Like a DataQueue, but for binary chunked data transfer.

read()[source]
readany()
class aiohttp.streams.FlowControlStreamReader(stream, limit=65536, *args, **kwargs)[source]

Bases: aiohttp.streams.StreamReader

feed_data(data, size=0)[source]
read(n=-1)[source]
readany()[source]
readexactly(n)[source]
readline()[source]
class aiohttp.streams.FlowControlDataQueue(stream, *, limit=65536, loop=None)[source]

Bases: aiohttp.streams.DataQueue

FlowControlDataQueue resumes and pauses an underlying stream.

It is a destination for parsed data.

feed_data(data, size)[source]
read()[source]
class aiohttp.streams.FlowControlChunksQueue(stream, *, limit=65536, loop=None)[source]

Bases: aiohttp.streams.FlowControlDataQueue

read()[source]
readany()

aiohttp.websocket module

WebSocket protocol versions 13 and 8.

aiohttp.websocket.WebSocketParser(out, buf)[source]
class aiohttp.websocket.WebSocketWriter(writer, *, use_mask=False, random=<random.Random object at 0x1ad59c8>)[source]

Bases: object

close(code=1000, message=b'')[source]

Close the websocket, sending the specified code and message.

ping(message=b'')[source]

Send ping message.

pong(message=b'')[source]

Send pong message.

send(message, binary=False)[source]

Send a frame over the websocket with message as its payload.

aiohttp.websocket.do_handshake(method, headers, transport, protocols=())[source]

Prepare WebSocket handshake.

It return http response code, response headers, websocket parser, websocket writer. It does not perform any IO.

protocols is a sequence of known protocols. On successful handshake, the returned response headers contain the first protocol in this list which the server also knows.

class aiohttp.websocket.Message(tp, data, extra)

Bases: tuple

data

Alias for field number 1

extra

Alias for field number 2

tp

Alias for field number 0

exception aiohttp.websocket.WebSocketError(code, message)[source]

Bases: Exception

WebSocket protocol parser error.

aiohttp.wsgi module

wsgi server.

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

SCRIPT_NAME = ''
create_wsgi_environ(message, payload)[source]
create_wsgi_response(message)[source]
handle_request(message, payload)[source]

Handle a single HTTP request