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.
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
= 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 than200 OK
onCONNECT
request.
-
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:
-
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]¶
-
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 orFalse
otherwise.Return type: bool
-
classmethod
from_response
(response)[source]¶ Constructs reader instance from HTTP response.
Parameters: response – ClientResponse
instance
-
multipart_reader_cls
= None¶ Multipart reader class, used to handle multipart/* body parts. None points to type(self)
-
part_reader_cls
¶ Body part reader class for non multipart/* content types.
alias of
BodyPartReader
-
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.
-
boundary
¶
-
part_writer_cls
¶ Body part reader class for non multipart/* content types.
alias of
BodyPartWriter
-
-
class
aiohttp.multipart.
BodyPartReader
(boundary, headers, content)[source]¶ Bases:
object
Multipart reader for single body part.
-
chunk_size
= 8192¶
-
decode
(data)[source]¶ Decodes data according the specified Content-Encoding or Content-Transfer-Encoding headers value.
Supports
gzip
,deflate
andidentity
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
-
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
-
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
-
-
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.
-
-
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:
Application creates StreamParser object for storing incoming data.
StreamParser creates ParserBuffer as internal data buffer.
Application create parser and set it into stream buffer:
parser = HttpRequestParser() data_queue = stream.set_parser(parser)
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
Application waits data on output.read()
- while True:
msg = yield form output.read() ...
Data flow:
- asyncio’s transport reads data from socket and sends data to protocol with data_received() call.
- Protocol sends data to StreamParser with feed_data() call.
- StreamParser sends data into parser with generator’s send() method.
- Parser processes incoming data and sends parsed data to DataQueue with feed_data()
- Application received parsed data from DataQueue.read()
Eof:
- StreamParser receives eof with feed_eof() call.
- StreamParser throws EofStream exception into parser.
- Then it unsets parser.
- _SocketSocketTransport ->
- -> “protocol” -> StreamParser -> “parser” -> DataQueue <- “application”
-
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.
-
output
¶
-
-
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:
bytearray
ParserBuffer is a bytearray extension.
ParserBuffer provides helper methods for parsers.
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.0'¶
-
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.
-
filter
= None¶
-
has_chunked_hdr
= False¶
-
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.
-
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
= ()¶
-
-
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
aiohttp.streams module¶
-
class
aiohttp.streams.
StreamReader
(limit=65536, loop=None)[source]¶ Bases:
asyncio.streams.StreamReader
-
total_bytes
= 0¶
-
-
class
aiohttp.streams.
DataQueue
(*, loop=None)[source]¶ Bases:
object
DataQueue is a general-purpose blocking queue with one reader.
-
class
aiohttp.streams.
ChunksQueue
(*, loop=None)[source]¶ Bases:
aiohttp.streams.DataQueue
Like a
DataQueue
, but for binary chunked data transfer.-
readany
()¶
-
-
class
aiohttp.streams.
FlowControlStreamReader
(stream, limit=65536, *args, **kwargs)[source]¶ Bases:
aiohttp.streams.StreamReader
-
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.
aiohttp.websocket module¶
WebSocket protocol versions 13 and 8.
-
class
aiohttp.websocket.
WebSocketWriter
(writer, *, use_mask=False, random=<random.Random object at 0x2be8758>)[source]¶ Bases:
object
-
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.
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
= ''¶
-