aiohttp.web
The Request object contains all the information about an incoming HTTP request.
BaseRequest
is used for Low-Level
Servers<aiohttp-web-lowlevel>
(which have no applications, routers, signals and middlewares). Request
has an Request.app
and Request.match_info
attributes.
A BaseRequest
/ Request
are dict
like objects, allowing them to be used for sharing
data<aiohttp-web-data-sharing>
among aiohttp-web-middlewares
and aiohttp-web-signals
handlers.
version
HTTP version of request, Read-only property.
Returns aiohttp.protocol.HttpVersion
instance.
method
HTTP method, read-only property.
The value is upper-cased str
like "GET"
, "POST"
, "PUT"
etc.
url
A ~yarl.URL
instance with absolute URL to resource (scheme, host and port are included).
Note
In case of malformed request (e.g. without "HOST"
HTTP header) the absolute url may be unavailable.
rel_url
A ~yarl.URL
instance with relative URL to resource (contains path, query and fragment parts only, scheme, host and port are excluded).
The property is equal to .url.relative()
but is always present.
A note from url
.
scheme
A string representing the scheme of the request.
The scheme is 'https'
if transport for request handling is SSL, 'http'
otherwise.
The value could be overridden by ~BaseRequest.clone
.
Read-only str
property.
2.3
Forwarded and X-Forwarded-Proto are not used anymore.
Call .clone(scheme=new_scheme)
for setting up the value explicitly.
aiohttp-web-forwarded-support
secure
Shorthand for request.url.scheme == 'https'
Read-only bool
property.
scheme
forwarded
A tuple containing all parsed Forwarded header(s).
Makes an effort to parse Forwarded headers as specified by 7239
:
- It adds one (immutable) dictionary per Forwarded
field-value
, i.e. per proxy. The element corresponds to the data in the Forwardedfield-value
added by the first proxy encountered by the client. Each subsequent item corresponds to those added by later proxies. - It checks that every value has valid syntax in general as specified in
7239#section-4
: either atoken
or aquoted-string
. - It un-escapes
quoted-pairs
. - It does NOT validate 'by' and 'for' contents as specified in
7239#section-6
. - It does NOT validate
host
contents (Host ABNF). - It does NOT validate
proto
contents for valid URI scheme names.
Returns a tuple containing one or more MappingProxy
objects
scheme
host
host
Host name of the request, resolved in this order:
- Overridden value by
~BaseRequest.clone
call. - Host HTTP header
socket.gtfqdn
Read-only str
property.
2.3
Forwarded and X-Forwarded-Host are not used anymore.
Call .clone(host=new_host)
for setting up the value explicitly.
aiohttp-web-forwarded-support
remote
Originating IP address of a client initiated HTTP request.
The IP is resolved through the following headers, in this order:
- Overridden value by
~BaseRequest.clone
call. - Peer name of opened socket.
Read-only str
property.
Call .clone(remote=new_remote)
for setting up the value explicitly.
2.3
aiohttp-web-forwarded-support
path_qs
The URL including PATH_INFO and the query string. e.g., /app/blog?id=10
Read-only str
property.
path
The URL including PATH INFO without the host or scheme. e.g., /app/blog
. The path is URL-decoded. For raw path info see raw_path
.
Read-only str
property.
raw_path
The URL including raw PATH INFO without the host or scheme. Warning, the path may be URL-encoded and may contain invalid URL characters, e.g. /my%2Fpath%7Cwith%21some%25strange%24characters
.
For URL-decoded version please take a look on path
.
Read-only str
property.
query
A multidict with all the variables in the query string.
Read-only ~multidict.MultiDictProxy
lazy property.
query_string
The query string in the URL, e.g., id=10
Read-only str
property.
headers
A case-insensitive multidict proxy with all headers.
Read-only ~multidict.CIMultiDictProxy
property.
raw_headers
HTTP headers of response as unconverted bytes, a sequence of (key, value)
pairs.
keep_alive
True
if keep-alive connection enabled by HTTP client and protocol version supports it, otherwise False
.
Read-only bool
property.
transport
A transport<asyncio-transport>
used to process request. Read-only property.
The property can be used, for example, for getting IP address of client's peer:
peername = request.transport.get_extra_info('peername')
if peername is not None:
host, port = peername
cookies
A multidict of all request's cookies.
Read-only ~multidict.MultiDictProxy
lazy property.
content
A ~aiohttp.StreamReader
instance, input stream for reading request's BODY.
Read-only property.
body_exists
Return True
if request has HTTP BODY, False
otherwise.
Read-only bool
property.
2.3
can_read_body
Return True
if request's HTTP BODY can be read, False
otherwise.
Read-only bool
property.
2.3
content_type
Read-only property with content part of Content-Type header.
Returns str
like 'text/html'
Note
Returns value is 'application/octet-stream'
if no Content-Type header present in HTTP headers according to 2616
charset
Read-only property that specifies the encoding for the request's BODY.
The value is parsed from the Content-Type HTTP header.
Returns str
like 'utf-8'
or None
if Content-Type has no charset information.
content_length
Read-only property that returns length of the request's BODY.
The value is parsed from the Content-Length HTTP header.
Returns int
or None
if Content-Length is absent.
http_range
Read-only property that returns information about Range HTTP header.
Returns a slice
where .start
is left inclusive bound, .stop
is right exclusive bound and .step
is 1
.
The property might be used in two manners:
Attribute-access style (example assumes that both left and right borders are set, the real logic for case of open bounds is more complex):
rng = request.http_range with open(filename, 'rb') as f: f.seek(rng.start) return f.read(rng.stop-rng.start)
Slice-style:
return buffer[request.http_range]
if_modified_since
Read-only property that returns the date specified in the If-Modified-Since header.
Returns datetime.datetime
or None
if If-Modified-Since header is absent or is not a valid HTTP date.
if_unmodified_since
Read-only property that returns the date specified in the If-Unmodified-Since header.
Returns datetime.datetime
or None
if If-Unmodified-Since header is absent or is not a valid HTTP date.
3.1
if_match
Read-only property that returns ETag
objects specified in the If-Match header.
Returns tuple
of ETag
or None
if If-Match header is absent.
3.8
if_none_match
Read-only property that returns ETag
objects specified If-None-Match header.
Returns tuple
of ETag
or None
if If-None-Match header is absent.
3.8
if_range
Read-only property that returns the date specified in the If-Range header.
Returns datetime.datetime
or None
if If-Range header is absent or is not a valid HTTP date.
3.1
clone(*, method=..., rel_url=..., headers=...)
Clone itself with replacement some attributes.
Creates and returns a new instance of Request object. If no parameters are given, an exact copy is returned. If a parameter is not passed, it will reuse the one from the current request object.
- param str method
http method
- param rel_url
url to use,
str
or~yarl.URL
- param headers
~multidict.CIMultiDict
or compatible headers container.- return
a cloned
Request
instance.
get_extra_info(name, default=None)
Reads extra information from the protocol's transport. If no value associated with name
is found, default
is returned.
- param str name
The key to look up in the transport extra information.
- param default
Default value to be used when no value for
name
is found (default isNone
).
3.7
read()
Read request body, returns bytes
object with body content.
Note
The method does store read data internally, subsequent ~Request.read
call will return the same value.
text()
Read request body, decode it using charset
encoding or UTF-8
if no encoding was specified in MIME-type.
Returns str
with body content.
Note
The method does store read data internally, subsequent ~Request.text
call will return the same value.
json(*, loads=json.loads, content_type='application/json')
Read request body decoded as json. If request's content-type does not match content_type parameter, web.HTTPBadRequest
get raised. To disable content type check pass None
value.
- param callable loads
any
callable
that acceptsstr
and returnsdict
with parsed JSON (json.loads
by default).- param str content_type
expected value of Content-Type header or
None
('application/json' by default)
Note
The method does store read data internally, subsequent ~Request.json
call will return the same value.
multipart()
Returns aiohttp.multipart.MultipartReader
which processes incoming multipart request.
The method is just a boilerplate coroutine <coroutine>
implemented as:
async def multipart(self, *, reader=aiohttp.multipart.MultipartReader):
return reader(self.headers, self._payload)
This method is a coroutine for consistency with the else reader methods.
Warning
The method does not store read data internally. That means once you exhausts multipart reader, you cannot get the request payload one more time.
aiohttp-multipart
3.4
Dropped reader parameter.
post()
A coroutine <coroutine>
that reads POST parameters from request body.
Returns ~multidict.MultiDictProxy
instance filled with parsed data.
If method
is not POST, PUT, PATCH, TRACE or DELETE or content_type
is not empty or application/x-www-form-urlencoded or multipart/form-data returns empty multidict.
Note
The method does store read data internally, subsequent ~Request.post
call will return the same value.
release()
Release request.
Eat unread part of HTTP BODY if present.
Note
User code may never call ~Request.release
, all required work will be processed by aiohttp.web
internal machinery.
wait_for_disconnection()
Returns when the connection that sent this request closes
If there is no client disconnection during request handling, this coroutine gets cancelled automatically at the end of this request being handled.
This can be used in handlers as a means of receiving a notification of premature client disconnection.
4.0
A request used for receiving request's information by web handler.
Every handler<aiohttp-web-handler>
accepts a request instance as the first positional parameter.
The class in derived from BaseRequest
, shares all parent's attributes and methods but has a couple of additional properties:
match_info
Read-only property with ~aiohttp.abc.AbstractMatchInfo
instance for result of route resolving.
Note
Exact type of property depends on used router. If app.router
is UrlDispatcher
the property contains UrlMappingMatchInfo
instance.
app
An Application
instance used to call request handler
<aiohttp-web-handler>
, Read-only property.
config_dict
A aiohttp.ChainMapProxy
instance for mapping all properties from the current application returned by app
property and all its parents.
aiohttp-web-data-sharing-app-config
3.2
Note
You should never create the Request
instance manually -- aiohttp.web
does it for you. But ~BaseRequest.clone
may be used for cloning modified request copy with changed path, method etc.
For now, aiohttp.web
has three classes for the HTTP response: StreamResponse
, Response
and FileResponse
.
Usually you need to use the second one. StreamResponse
is intended for streaming data, while Response
contains HTTP BODY as an attribute and sends own content as single piece with the correct Content-Length HTTP header.
For sake of design decisions Response
is derived from StreamResponse
parent class.
The response supports keep-alive handling out-of-the-box if request supports it.
You can disable keep-alive by ~StreamResponse.force_close
though.
The common case for sending an answer from web-handler<aiohttp-web-handler>
is returning a Response
instance:
async def handler(request):
return Response(text="All right!")
Response classes are dict
like objects, allowing them to be used for sharing
data<aiohttp-web-data-sharing>
among aiohttp-web-middlewares
and aiohttp-web-signals
handlers:
resp['key'] = value
3.0
Dict-like interface support.
The base class for the HTTP response handling.
Contains methods for setting HTTP response headers, cookies, response status code, writing HTTP response BODY and so on.
The most important thing you should know about response --- it is Finite State Machine.
That means you can do any manipulations with headers, cookies and status code only before prepare
coroutine is called.
Once you call prepare
any change of the HTTP header part will raise RuntimeError
exception.
Any write
call after write_eof
is also forbidden.
- param int status
HTTP status code,
200
by default.- param str reason
HTTP reason. If param is
None
reason will be calculated basing on status parameter. Otherwise passstr
with arbitrary status explanation..
prepared
Read-only bool
property, True
if prepare
has been called, False
otherwise.
task
A task that serves HTTP request handling.
May be useful for graceful shutdown of long-running requests (streaming, long polling or web-socket).
status
Read-only property for HTTP response status code, int
.
200
(OK) by default.
reason
Read-only property for HTTP response reason, str
.
set_status(status, reason=None)
Set status
and reason
.
reason value is auto calculated if not specified (None
).
keep_alive
Read-only property, copy of Request.keep_alive
by default.
Can be switched to False
by force_close
call.
force_close
Disable keep_alive
for connection. There are no ways to enable it back.
compression
Read-only bool
property, True
if compression is enabled.
False
by default.
enable_compression
enable_compression(force=None)
Enable compression.
When force is unset compression encoding is selected based on the request's Accept-Encoding header.
Accept-Encoding is not checked if force is set to a ContentCoding
.
compression
chunked
Read-only property, indicates if chunked encoding is on.
Can be enabled by enable_chunked_encoding
call.
enable_chunked_encoding
enable_chunked_encoding()
Enables chunked
encoding for response. There are no ways to disable it back. With enabled chunked
encoding each write
operation encoded in separate chunk.
Warning
chunked encoding can be enabled for HTTP/1.1
only.
Setting up both content_length
and chunked encoding is mutually exclusive.
chunked
headers
~multidict.CIMultiDict
instance for outgoing HTTP headers.
cookies
An instance of http.cookies.SimpleCookie
for outgoing cookies.
Warning
Direct setting up Set-Cookie header may be overwritten by explicit calls to cookie manipulation.
We are encourage using of cookies
and set_cookie
, del_cookie
for cookie manipulations.
set_cookie(name, value, *, path='/', expires=None, domain=None, max_age=None, secure=None, httponly=None, version=None, samesite=None)
Convenient way for setting cookies
, allows to specify some additional properties like max_age in a single call.
- param str name
cookie name
- param str value
cookie value (will be converted to
str
if value has another type).- param expires
expiration date (optional)
- param str domain
cookie domain (optional)
- param int max_age
defines the lifetime of the cookie, in seconds. The delta-seconds value is a decimal non- negative integer. After delta-seconds seconds elapse, the client should discard the cookie. A value of zero means the cookie should be discarded immediately. (optional)
- param str path
specifies the subset of URLs to which this cookie applies. (optional,
'/'
by default)- param bool secure
attribute (with no value) directs the user agent to use only (unspecified) secure means to contact the origin server whenever it sends back this cookie. The user agent (possibly under the user's control) may determine what level of security it considers appropriate for "secure" cookies. The secure should be considered security advice from the server to the user agent, indicating that it is in the session's interest to protect the cookie contents. (optional)
- param bool httponly
True
if the cookie HTTP only (optional)- param int version
a decimal integer, identifies to which version of the state management specification the cookie conforms. (Optional, version=1 by default)
- param str samesite
Asserts that a cookie must not be sent with cross-origin requests, providing some protection against cross-site request forgery attacks. Generally the value should be one of:
None
,Lax
orStrict
. (optional)3.7
Warning
In HTTP version 1.1, expires
was deprecated and replaced with the easier-to-use max-age
, but Internet Explorer (IE6, IE7, and IE8) does not support max-age
.
del_cookie(name, *, path='/', domain=None)
Deletes cookie.
- param str name
cookie name
- param str domain
optional cookie domain
- param str path
optional cookie path,
'/'
by default
content_length
Content-Length for outgoing response.
content_type
Content part of Content-Type for outgoing response.
charset
Charset aka encoding part of Content-Type for outgoing response.
The value converted to lower-case on attribute assigning.
last_modified
Last-Modified header for outgoing response.
This property accepts raw str
values, datetime.datetime
objects, Unix timestamps specified as an int
or a float
object, and the value None
to unset the header.
etag
ETag header for outgoing response.
This property accepts raw str
values, ETag
objects and the value None
to unset the header.
In case of str
input, etag is considered as strong by default.
Do not use double quotes "
in the etag value, they will be added automatically.
3.8
prepare(request)
- param aiohttp.web.Request request
HTTP request object, that the response answers.
Send HTTP header. You should not change any header data after calling this method.
The coroutine calls ~aiohttp.web.Application.on_response_prepare
signal handlers after default headers have been computed and directly before headers are sent.
write(data)
Send byte-ish data as the part of response BODY:
await resp.write(data)
prepare
must be invoked before the call.
Raises TypeError
if data is not bytes
, bytearray
or memoryview
instance.
Raises RuntimeError
if prepare
has not been called.
Raises RuntimeError
if write_eof
has been called.
write_eof()
A coroutine<coroutine>
may be called as a mark of the HTTP response processing finish.
Internal machinery will call this method at the end of the request processing if needed.
After write_eof
call any manipulations with the response object are forbidden.
The most usable response class, inherited from StreamResponse
.
Accepts body argument for setting the HTTP response BODY.
The actual body
sending happens in overridden ~StreamResponse.write_eof
.
- param bytes body
response's BODY
- param int status
HTTP status code, 200 OK by default.
- param collections.abc.Mapping headers
HTTP headers that should be added to response's ones.
- param str text
response's BODY
- param str content_type
response's content type.
'text/plain'
if text is passed also,'application/octet-stream'
otherwise.- param str charset
response's charset.
'utf-8'
if text is passed also,None
otherwise.- param int zlib_executor_size
length in bytes which will trigger zlib compression of body to happen in an executor
3.5
- param int zlib_executor
executor to use for zlib compression
3.5
body
Read-write attribute for storing response's content aka BODY, bytes
.
Setting body
also recalculates ~StreamResponse.content_length
value.
Assigning str
to body
will make the body
type of aiohttp.payload.StringPayload
, which tries to encode the given data based on Content-Type HTTP header, while defaulting to UTF-8
.
Resetting body
(assigning None
) sets ~StreamResponse.content_length
to None
too, dropping Content-Length HTTP header.
text
Read-write attribute for storing response's content, represented as string, str
.
Setting text
also recalculates ~StreamResponse.content_length
value and ~StreamResponse.body
value
Resetting text
(assigning None
) sets ~StreamResponse.content_length
to None
too, dropping Content-Length HTTP header.
The response class used to send files, inherited from StreamResponse
.
Supports the Content-Range
and If-Range
HTTP Headers in requests.
The actual body
sending happens in overridden ~StreamResponse.prepare
.
- param path
Path to file. Accepts both
str
andpathlib.Path
.- param int chunk_size
Chunk size in bytes which will be passed into
io.RawIOBase.read
in the event that thesendfile
system call is not supported.- param int status
HTTP status code,
200
by default.- param str reason
HTTP reason. If param is
None
reason will be calculated basing on status parameter. Otherwise passstr
with arbitrary status explanation..- param collections.abc.Mapping headers
HTTP headers that should be added to response's ones. The
Content-Type
response header will be overridden if provided.
Class for handling server-side websockets, inherited from StreamResponse
.
After starting (by prepare
call) the response you cannot use ~StreamResponse.write
method but should to communicate with websocket client by send_str
, receive
and others.
To enable back-pressure from slow websocket clients treat methods ping()
, pong()
, send_str()
, send_bytes()
, send_json()
as coroutines. By default write buffer size is set to 64k.
- param bool autoping
Automatically send
~aiohttp.WSMsgType.PONG
on~aiohttp.WSMsgType.PING
message from client, and handle~aiohttp.WSMsgType.PONG
responses from client. Note that server does not send~aiohttp.WSMsgType.PING
requests, you need to do this explicitly usingping
method.- param float heartbeat
Send ping message every heartbeat seconds and wait pong response, close connection if pong response is not received. The timer is reset on any data reception.
- param float receive_timeout
Timeout value for receive operations. Default value is None (no timeout for receive operation)
- param bool compress
Enable per-message deflate extension support. False for disabled, default value is True.
- param int max_msg_size
maximum size of read websocket message, 4 MB by default. To disable the size limit use
0
.
3.3
The class supports async for
statement for iterating over incoming messages:
ws = web.WebSocketResponse()
await ws.prepare(request)
async for msg in ws:
print(msg.data)
prepare(request)
Starts websocket. After the call you can use websocket methods.
- param aiohttp.web.Request request
HTTP request object, that the response answers.
- raises HTTPException
if websocket handshake has failed.
can_prepare(request)
Performs checks for request data to figure out if websocket can be started on the request.
If can_prepare
call is success then prepare
will success too.
- param aiohttp.web.Request request
HTTP request object, that the response answers.
- return
WebSocketReady
instance.
WebSocketReady.ok
isTrue
on success,WebSocketReady.protocol
is websocket subprotocol which is passed by client and accepted by server (one of protocols sequence fromWebSocketResponse
ctor).WebSocketReady.protocol
may beNone
if client and server subprotocols are not overlapping.
Note
The method never raises exception.
closed
Read-only property, True
if connection has been closed or in process of closing. ~aiohttp.WSMsgType.CLOSE
message has been received from peer.
close_code
Read-only property, close code from peer. It is set to None
on opened connection.
ws_protocol
Websocket subprotocol chosen after start
call.
May be None
if server and client protocols are not overlapping.
exception()
Returns last occurred exception or None.
ping(message=b'')
Send ~aiohttp.WSMsgType.PING
to peer.
- param message
optional payload of ping message,
str
(converted to UTF-8 encoded bytes) orbytes
.- raise RuntimeError
if connections is not started or closing.
3.0
The method is converted into coroutine
pong(message=b'')
Send unsolicited ~aiohttp.WSMsgType.PONG
to peer.
- param message
optional payload of pong message,
str
(converted to UTF-8 encoded bytes) orbytes
.- raise RuntimeError
if connections is not started or closing.
3.0
The method is converted into coroutine
send_str(data, compress=None)
Send data to peer as ~aiohttp.WSMsgType.TEXT
message.
- param str data
data to send.
- param int compress
sets specific level of compression for single message,
None
for not overriding per-socket setting.- raise RuntimeError
if connection is not started or closing
- raise TypeError
if data is not
str
3.0
The method is converted into coroutine
, compress parameter added.
send_bytes(data, compress=None)
Send data to peer as ~aiohttp.WSMsgType.BINARY
message.
- param data
data to send.
- param int compress
sets specific level of compression for single message,
None
for not overriding per-socket setting.- raise RuntimeError
if connection is not started or closing
- raise TypeError
if data is not
bytes
,bytearray
ormemoryview
.
3.0
The method is converted into coroutine
, compress parameter added.
send_json(data, compress=None, *, dumps=json.dumps)
Send data to peer as JSON string.
- param data
data to send.
- param int compress
sets specific level of compression for single message,
None
for not overriding per-socket setting.- param callable dumps
any
callable
that accepts an object and returns a JSON string (json.dumps
by default).- raise RuntimeError
if connection is not started or closing
- raise ValueError
if data is not serializable object
- raise TypeError
if value returned by
dumps
param is notstr
3.0
The method is converted into coroutine
, compress parameter added.
close(*, code=WSCloseCode.OK, message=b'')
A coroutine<coroutine>
that initiates closing handshake by sending ~aiohttp.WSMsgType.CLOSE
message.
It is safe to call close() from different task.
- param int code
closing code. See also
~aiohttp.WSCloseCode
.- param message
optional payload of close message,
str
(converted to UTF-8 encoded bytes) orbytes
.- raise RuntimeError
if connection is not started
receive(timeout=None)
A coroutine<coroutine>
that waits upcoming data message from peer and returns it.
The coroutine implicitly handles ~aiohttp.WSMsgType.PING
, ~aiohttp.WSMsgType.PONG
and ~aiohttp.WSMsgType.CLOSE
without returning the message.
It process ping-pong game and performs closing handshake internally.
Note
Can only be called by the request handling task.
- param timeout
timeout for receive operation.
timeout value overrides response`s receive_timeout attribute.
- return
~aiohttp.WSMessage
- raise RuntimeError
if connection is not started
receive_str(*, timeout=None)
A coroutine<coroutine>
that calls receive
but also asserts the message type is ~aiohttp.WSMsgType.TEXT
.
Note
Can only be called by the request handling task.
- param timeout
timeout for receive operation.
timeout value overrides response`s receive_timeout attribute.
- return str
peer's message content.
- raise TypeError
if message is
~aiohttp.WSMsgType.BINARY
.
receive_bytes(*, timeout=None)
A coroutine<coroutine>
that calls receive
but also asserts the message type is ~aiohttp.WSMsgType.BINARY
.
Note
Can only be called by the request handling task.
- param timeout
timeout for receive operation.
timeout value overrides response`s receive_timeout attribute.
- return bytes
peer's message content.
- raise TypeError
if message is
~aiohttp.WSMsgType.TEXT
.
receive_json(*, loads=json.loads, timeout=None)
A coroutine<coroutine>
that calls receive_str
and loads the JSON string to a Python dict.
Note
Can only be called by the request handling task.
- param callable loads
any
callable
that acceptsstr
and returnsdict
with parsed JSON (json.loads
by default).- param timeout
timeout for receive operation.
timeout value overrides response`s receive_timeout attribute.
- return dict
loaded JSON content
- raise TypeError
if message is
~aiohttp.WSMsgType.BINARY
.- raise ValueError
if message is not valid JSON.
WebSockets handling<aiohttp-web-websockets>
A named tuple for returning result from WebSocketResponse.can_prepare
.
Has bool
check implemented, e.g.:
if not await ws.can_prepare(...):
cannot_start_websocket()
ok
True
if websocket connection can be established, False
otherwise.
protocol
str
represented selected websocket sub-protocol.
WebSocketResponse.can_prepare
json_response([data], *, text=None, body=None, status=200, reason=None, headers=None, content_type='application/json', dumps=json.dumps)
Return Response
with predefined 'application/json'
content type and data encoded by dumps
parameter (json.dumps
by default).
Application is a synonym for web-server.
To get fully working example, you have to make application, register supported urls in router and pass it to aiohttp.web.run_app
or aiohttp.web.AppRunner
.
Application contains a router instance and a list of callbacks that will be called during application finishing.
Application
is a dict
-like object, so you can use it for sharing data<aiohttp-web-data-sharing>
globally by storing arbitrary properties for later access from a handler<aiohttp-web-handler>
via the Request.app
property:
app = Application()
app['database'] = await aiopg.create_engine(**db_config)
async def handler(request):
with (await request.app['database']) as conn:
conn.execute("DELETE * FROM table")
Although Application
is a dict
-like object, it can't be duplicated like one using Application.copy
.
The class inherits dict
.
- param logger
logging.Logger
instance for storing application logs.
By default the value is
logging.getLogger("aiohttp.web")
- param middlewares
list
of middleware factories, seeaiohttp-web-middlewares
for details.- param handler_args
dict-like object that overrides keyword arguments of
AppRunner
constructor.- param client_max_size
client's maximum size in a request, in bytes. If a POST request exceeds this value, it raises an HTTPRequestEntityTooLarge exception.
- param debug
Switches debug mode.
3.5
The argument does nothing starting from 4.0, use asyncio
asyncio-debug-mode
instead.
router
Read-only property that returns router instance.
logger
logging.Logger
instance for storing application logs.
debug
Boolean value indicating whether the debug mode is turned on or off.
3.5
Use asyncio asyncio-debug-mode
instead.
on_response_prepare
A ~aiohttp.Signal
that is fired near the end of StreamResponse.prepare
with parameters request and response. It can be used, for example, to add custom headers to each response, or to modify the default headers computed by the application, directly before sending the headers to the client.
Signal handlers should have the following signature:
async def on_prepare(request, response):
pass
on_startup
A ~aiohttp.Signal
that is fired on application start-up.
Subscribers may use the signal to run background tasks in the event loop along with the application's request handler just after the application start-up.
Signal handlers should have the following signature:
async def on_startup(app):
pass
aiohttp-web-signals
and aiohttp-web-cleanup-ctx
.
on_shutdown
A ~aiohttp.Signal
that is fired on application shutdown.
Subscribers may use the signal for gracefully closing long running connections, e.g. websockets and data streaming.
Signal handlers should have the following signature:
async def on_shutdown(app):
pass
It's up to end user to figure out which web-handler
s are still alive and how to finish them properly.
We suggest keeping a list of long running handlers in Application
dictionary.
aiohttp-web-graceful-shutdown
and on_cleanup
.
on_cleanup
A ~aiohttp.Signal
that is fired on application cleanup.
Subscribers may use the signal for gracefully closing connections to database server etc.
Signal handlers should have the following signature:
async def on_cleanup(app):
pass
aiohttp-web-signals
and on_shutdown
.
cleanup_ctx
A list of context generators for startup/cleanup handling.
Signal handlers should have the following signature:
async def context(app):
# do startup stuff
yield
# do cleanup
3.1
aiohttp-web-cleanup-ctx
.
add_subapp(prefix, subapp)
Register nested sub-application under given path prefix.
In resolving process if request's path starts with prefix then further resolving is passed to subapp.
- param str prefix
path's prefix for the resource.
- param Application subapp
nested application attached under prefix.
- returns
a
PrefixedSubAppResource
instance.
add_domain(domain, subapp)
Register nested sub-application that serves the domain name or domain name mask.
In resolving process if request.headers['host'] matches the pattern domain then further resolving is passed to subapp.
- param str domain
domain or mask of domain for the resource.
- param Application subapp
nested application.
- returns
a
MatchedSubAppResource
instance.
add_routes(routes_table)
Register route definitions from routes_table.
The table is a list
of RouteDef
items or RouteTableDef
.
- returns
list
of registeredAbstractRoute
instances.
The method is a shortcut for app.router.add_routes(routes_table)
, see also UrlDispatcher.add_routes
.
3.1
3.7
Return value updated from None
to list
of AbstractRoute
instances.
startup()
A coroutine<coroutine>
that will be called along with the application's request handler.
The purpose of the method is calling on_startup
signal handlers.
shutdown()
A coroutine<coroutine>
that should be called on server stopping but before cleanup()
.
The purpose of the method is calling on_shutdown
signal handlers.
cleanup()
A coroutine<coroutine>
that should be called on server stopping but after shutdown
.
The purpose of the method is calling on_cleanup
signal handlers.
Note
Application object has router
attribute but has no add_route()
method. The reason is: we want to support different router implementations (even maybe not url-matching based but traversal ones).
For sake of that fact we have very trivial ABC for AbstractRouter
: it should have only AbstractRouter.resolve
coroutine.
No methods for adding routes or route reversing (getting URL by route name). All those are router implementation details (but, sure, you need to deal with that methods after choosing the router for your application).
A protocol factory compatible with ~asyncio.AbstreactEventLoop.create_server
.
The class is responsible for creating HTTP protocol objects that can handle HTTP connections.
connections
List of all currently opened connections.
requests_count
Amount of processed requests.
Server.shutdown(timeout)
A coroutine<coroutine>
that should be called to close all opened connections.
For dispatching URLs to handlers<aiohttp-web-handler>
aiohttp.web
uses routers.
Router is any object that implements AbstractRouter
interface.
aiohttp.web
provides an implementation called UrlDispatcher
.
Application
uses UrlDispatcher
as router
by default.
Straightforward url-matching router, implements collections.abc.Mapping
for access to named routes.
Before running Application
you should fill route table first by calling add_route
and add_static
.
Handler<aiohttp-web-handler>
lookup is performed by iterating on added routes in FIFO order. The first matching route will be used to call corresponding handler.
If on route creation you specify name parameter the result is named route.
Named route can be retrieved by app.router[name]
call, checked for existence by name in app.router
etc.
Route classes <aiohttp-web-route>
add_resource(path, *, name=None)
Append a resource
to the end of route table.
path may be either constant string like '/a/b/c'
or variable rule like '/a/{var}'
(see handling variable paths <aiohttp-web-variable-handler>
)
- param str path
resource path spec.
- param str name
optional resource name.
- return
created resource instance (
PlainResource
orDynamicResource
).
add_route(method, path, handler, *, name=None, expect_handler=None)
Append handler<aiohttp-web-handler>
to the end of route table.
- path may be either constant string like
'/a/b/c'
or variable rule like
'/a/{var}'
(seehandling variable paths <aiohttp-web-variable-handler>
)
Pay attention please: handler must be a coroutine.
- param str method
HTTP method for route. Should be one of
'GET'
,'POST'
,'PUT'
,'DELETE'
,'PATCH'
,'HEAD'
,'OPTIONS'
or'*'
for any method.The parameter is case-insensitive, e.g. you can push
'get'
as well as'GET'
.- param str path
route path. Should be started with slash (
'/'
).- param callable handler
route handler.
- param str name
optional route name.
- param coroutine expect_handler
optional expect header handler.
- returns
new
PlainRoute
orDynamicRoute
instance.
add_routes(routes_table)
Register route definitions from routes_table.
The table is a list
of RouteDef
items or RouteTableDef
.
- returns
list
of registeredAbstractRoute
instances.
2.3
3.7
Return value updated from None
to list
of AbstractRoute
instances.
add_get(path, handler, , name=None, allow_head=True,*kwargs)
Shortcut for adding a GET handler. Calls the add_route
with method
equals to 'GET'
.
If allow_head is True
(default) the route for method HEAD is added with the same handler as for GET.
If name is provided the name for HEAD route is suffixed with '-head'
. For example router.add_get(path, handler, name='route')
call adds two routes: first for GET with name 'route'
and second for HEAD with name 'route-head'
.
add_post(path, handler, **kwargs)
Shortcut for adding a POST handler. Calls the add_route
with
method
equals to 'POST'
.
add_head(path, handler, **kwargs)
Shortcut for adding a HEAD handler. Calls the add_route
with method
equals to 'HEAD'
.
add_put(path, handler, **kwargs)
Shortcut for adding a PUT handler. Calls the add_route
with method
equals to 'PUT'
.
add_patch(path, handler, **kwargs)
Shortcut for adding a PATCH handler. Calls the add_route
with method
equals to 'PATCH'
.
add_delete(path, handler, **kwargs)
Shortcut for adding a DELETE handler. Calls the add_route
with method
equals to 'DELETE'
.
add_view(path, handler, **kwargs)
Shortcut for adding a class-based view handler. Calls the add_route
with method
equals to '*'
.
3.0
add_static(prefix, path, , name=None, expect_handler=None, chunk_size=2561024, response_factory=StreamResponse, show_index=False, follow_symlinks=False, append_version=False)
Adds a router and a handler for returning static files.
Useful for serving static content like images, javascript and css files.
On platforms that support it, the handler will transfer files more efficiently using the sendfile
system call.
In some situations it might be necessary to avoid using the sendfile
system call even if the platform supports it. This can be accomplished by by setting environment variable AIOHTTP_NOSENDFILE=1
.
If a gzip version of the static content exists at file path + .gz
, it will be used for the response.
Warning
Use add_static
for development only. In production, static content should be processed by web servers like nginx or apache.
- param str prefix
URL path prefix for handled static files
- param path
path to the folder in file system that contains handled static files,
str
orpathlib.Path
.- param str name
optional route name.
- param coroutine expect_handler
optional expect header handler.
- param int chunk_size
size of single chunk for file downloading, 256Kb by default.
Increasing chunk_size parameter to, say, 1Mb may increase file downloading speed but consumes more memory.
- param bool show_index
flag for allowing to show indexes of a directory, by default it's not allowed and HTTP/403 will be returned on directory access.
- param bool follow_symlinks
flag for allowing to follow symlinks from a directory, by default it's not allowed and HTTP/404 will be returned on access.
- param bool append_version
flag for adding file version (hash) to the url query string, this value will be used as default when you call to
StaticRoute.url
andStaticRoute.url_for
methods.- returns
new
StaticRoute
instance.
resolve(request)
A coroutine<coroutine>
that returns AbstractMatchInfo
for request.
The method never raises exception, but returns AbstractMatchInfo
instance with:
~AbstractMatchInfo.http_exception
assigned toHTTPException
instance.~AbstractMatchInfo.handler
which raisesHTTPNotFound
orHTTPMethodNotAllowed
on handler's execution if there is no registered route for request.Middlewares can process that exceptions to render pretty-looking error page for example.
Used by internal machinery, end user unlikely need to call the method.
Note
The method uses Request.raw_path
for pattern matching against registered routes.
resources()
The method returns a view for all registered resources.
The view is an object that allows to:
Get size of the router table:
len(app.router.resources())
Iterate over registered resources:
for resource in app.router.resources(): print(resource)
Make a check if the resources is registered in the router table:
route in app.router.resources()
routes()
The method returns a view for all registered routes.
named_resources()
Returns a dict
-like types.MappingProxyType
view over all named resources.
The view maps every named resource's name to the BaseResource
instance. It supports the usual dict
-like operations, except for any mutable operations (i.e. it's read-only):
len(app.router.named_resources())
for name, resource in app.router.named_resources().items():
print(name, resource)
"name" in app.router.named_resources()
app.router.named_resources()["name"]
Default router UrlDispatcher
operates with resource
s.
Resource is an item in routing table which has a path, an optional unique name and at least one route
.
web-handler
lookup is performed in the following way:
- Router iterates over resources one-by-one.
- If resource matches to requested URL the resource iterates over own routes.
- If route matches to requested HTTP method (or
'*'
wildcard) the route's handler is used as foundweb-handler
. The lookup is finished. - Otherwise router tries next resource from the routing table.
- If the end of routing table is reached and no resource / route pair found the router returns special
AbstractMatchInfo
instance withAbstractMatchInfo.http_exception
is notNone
butHTTPException
with either HTTP 404 Not Found or HTTP 405 Method Not Allowed status code. RegisteredAbstractMatchInfo.handler
raises this exception on call.
User should never instantiate resource classes but give it by UrlDispatcher.add_resource
call.
After that he may add a route
by calling Resource.add_route
.
UrlDispatcher.add_route
is just shortcut for:
router.add_resource(path).add_route(method, handler)
Resource with a name is called named resource. The main purpose of named resource is constructing URL by route name for passing it into template engine for example:
url = app.router['resource_name'].url_for().with_query({'a': 1, 'b': 2})
Resource classes hierarchy:
AbstractResource
Resource
PlainResource
DynamicResource
StaticResource
A base class for all resources.
Inherited from collections.abc.Sized
and collections.abc.Iterable
.
len(resource)
returns amount of route
s belongs to the resource, for route in resource
allows to iterate over these routes.
name
Read-only name of resource or None
.
canonical
Read-only canonical path associate with the resource. For example /path/to
or /path/{to}
3.3
resolve(request)
Resolve resource by finding appropriate web-handler
for (method, path)
combination.
- return
(match_info, allowed_methods) pair.
allowed_methods is a
set
or HTTP methods accepted by resource.match_info is either
UrlMappingMatchInfo
if request is resolved orNone
if noroute
is found.
get_info()
A resource description, e.g. {'path': '/path/to'}
or {'formatter': '/path/{to}', 'pattern': re.compile(r'^/path/(?P<to>[a-zA-Z][_a-zA-Z0-9]+)$
url_for(args,*kwargs)
Construct an URL for route with additional params.
args and kwargs depend on a parameters list accepted by inherited resource class.
- return
~yarl.URL
-- resulting URL instance.
A base class for new-style resources, inherits AbstractResource
.
add_route(method, handler, *, expect_handler=None)
Add a web-handler
to resource.
- param str method
HTTP method for route. Should be one of
'GET'
,'POST'
,'PUT'
,'DELETE'
,'PATCH'
,'HEAD'
,'OPTIONS'
or'*'
for any method.The parameter is case-insensitive, e.g. you can push
'get'
as well as'GET'
.The method should be unique for resource.
- param callable handler
route handler.
- param coroutine expect_handler
optional expect header handler.
- returns
new
ResourceRoute
instance.
A resource, inherited from Resource
.
The class corresponds to resources with plain-text matching, '/path/to'
for example.
canonical
Read-only canonical path associate with the resource. Returns the path used to create the PlainResource. For example /path/to
3.3
url_for()
Returns a ~yarl.URL
for the resource.
A resource, inherited from Resource
.
The class corresponds to resources with variable <aiohttp-web-variable-handler>
matching, e.g. '/path/{to}/{param}'
etc.
canonical
Read-only canonical path associate with the resource. Returns the formatter obtained from the path used to create the DynamicResource. For example, from a path /get/{num:^\d+}
, it returns /get/{num}
3.3
url_for(**params)
Returns a ~yarl.URL
for the resource.
- param params
-- a variable substitutions for dynamic resource.
E.g. for
'/path/{to}/{param}'
pattern the method should be called asresource.url_for(to='val1', param='val2')
A resource, inherited from Resource
.
The class corresponds to resources for static file serving
<aiohttp-web-static-file-handling>
.
canonical
Read-only canonical path associate with the resource. Returns the prefix used to create the StaticResource. For example /prefix
3.3
url_for(filename, append_version=None)
Returns a ~yarl.URL
for file path under resource prefix.
- param filename
-- a file name substitution for static file handler.
Accepts both
str
andpathlib.Path
.E.g. an URL for
'/prefix/dir/file.txt'
should be generated asresource.url_for(filename='dir/file.txt')
- param bool append_version
-- a flag for adding file version (hash) to the url query string for cache boosting
By default has value from a constructor (
False
by default) When set toTrue
-v=FILE_HASH
query string param will be added When set toFalse
has no impactif file not found has no impact
A resource for serving nested applications. The class instance is returned by ~aiohttp.web.Application.add_subapp
call.
canonical
Read-only canonical path associate with the resource. Returns the prefix used to create the PrefixedSubAppResource. For example /prefix
3.3
url_for(**kwargs)
The call is not allowed, it raises RuntimeError
.
Route has HTTP method (wildcard '*'
is an option), web-handler
and optional expect handler.
Every route belong to some resource.
Route classes hierarchy:
AbstractRoute
ResourceRoute
SystemRoute
ResourceRoute
is the route used for resources, SystemRoute
serves URL resolving errors like 404 Not Found and 405 Method Not Allowed.
Base class for routes served by UrlDispatcher
.
method
HTTP method handled by the route, e.g. GET, POST etc.
handler
handler<aiohttp-web-handler>
that processes the route.
name
Name of the route, always equals to name of resource which owns the route.
resource
Resource instance which holds the route, None
for SystemRoute
.
url_for(args,*kwargs)
Abstract method for constructing url handled by the route.
Actually it's a shortcut for route.resource.url_for(...)
.
handle_expect_header(request)
100-continue
handler.
The route class for handling different HTTP methods for Resource
.
The route class for handling URL resolution errors like like 404 Not Found and 405 Method Not Allowed.
status
HTTP status code
reason
HTTP status reason
Route definition, a description for not registered yet route.
Could be used for filing route table by providing a list of route definitions (Django style).
The definition is created by functions like get
or post
, list of definitions could be added to router by UrlDispatcher.add_routes
call:
from aiohttp import web
async def handle_get(request):
...
async def handle_post(request):
...
app.router.add_routes([web.get('/get', handle_get),
web.post('/post', handle_post),
A base class for route definitions.
Inherited from abc.ABC
.
3.1
register(router)
Register itself into UrlDispatcher
.
Abstract method, should be overridden by subclasses.
- returns
list
of registeredAbstractRoute
objects.
3.7
Return value updated from None
to list
of AbstractRoute
instances.
A definition of not registered yet route.
Implements AbstractRouteDef
.
2.3
3.1
The class implements AbstractRouteDef
interface.
method
HTTP method (GET
, POST
etc.) (str
).
path
Path to resource, e.g. /path/to
. Could contain {}
brackets for variable resources
<aiohttp-web-variable-handler>
(str
).
handler
An async function to handle HTTP request.
kwargs
A dict
of additional arguments.
A definition of static file resource.
Implements AbstractRouteDef
.
3.1
prefix
A prefix used for static file handling, e.g. /static
.
path
File system directory to serve, str
or pathlib.Path
(e.g. '/home/web-service/path/to/static'
.
kwargs
A dict
of additional arguments, see UrlDispatcher.add_static
for a list of supported options.
get(path, handler, *, name=None, allow_head=True, expect_handler=None)
Return RouteDef
for processing GET
requests. See UrlDispatcher.add_get
for information about parameters.
2.3
post(path, handler, *, name=None, expect_handler=None)
Return RouteDef
for processing POST
requests. See UrlDispatcher.add_post
for information about parameters.
2.3
head(path, handler, *, name=None, expect_handler=None)
Return RouteDef
for processing HEAD
requests. See UrlDispatcher.add_head
for information about parameters.
2.3
put(path, handler, *, name=None, expect_handler=None)
Return RouteDef
for processing PUT
requests. See UrlDispatcher.add_put
for information about parameters.
2.3
patch(path, handler, *, name=None, expect_handler=None)
Return RouteDef
for processing PATCH
requests. See UrlDispatcher.add_patch
for information about parameters.
2.3
delete(path, handler, *, name=None, expect_handler=None)
Return RouteDef
for processing DELETE
requests. See UrlDispatcher.add_delete
for information about parameters.
2.3
view(path, handler, *, name=None, expect_handler=None)
Return RouteDef
for processing ANY
requests. See UrlDispatcher.add_view
for information about parameters.
3.0
static(prefix, path, , name=None, expect_handler=None, chunk_size=2561024, show_index=False, follow_symlinks=False, append_version=False)
Return StaticDef
for processing static files.
See UrlDispatcher.add_static
for information about supported parameters.
3.1
route(method, path, handler, *, name=None, expect_handler=None)
Return RouteDef
for processing requests that decided by method
. See UrlDispatcher.add_route
for information about parameters.
2.3
A routes table definition used for describing routes by decorators (Flask style):
from aiohttp import web
routes = web.RouteTableDef()
@routes.get('/get')
async def handle_get(request):
...
@routes.post('/post')
async def handle_post(request):
...
app.router.add_routes(routes)
@routes.view("/view")
class MyView(web.View):
async def get(self):
...
async def post(self):
...
A sequence of RouteDef
instances (implements abc.collections.Sequence
protocol).
In addition to all standard list
methods the class provides also methods like get()
and post()
for adding new route definition.
2.3
get(path, *, allow_head=True, name=None, expect_handler=None)
Add a new RouteDef
item for registering GET
web-handler.
See UrlDispatcher.add_get
for information about parameters.
post(path, *, name=None, expect_handler=None)
Add a new RouteDef
item for registering POST
web-handler.
See UrlDispatcher.add_post
for information about parameters.
head(path, *, name=None, expect_handler=None)
Add a new RouteDef
item for registering HEAD
web-handler.
See UrlDispatcher.add_head
for information about parameters.
put(path, *, name=None, expect_handler=None)
Add a new RouteDef
item for registering PUT
web-handler.
See UrlDispatcher.add_put
for information about parameters.
patch(path, *, name=None, expect_handler=None)
Add a new RouteDef
item for registering PATCH
web-handler.
See UrlDispatcher.add_patch
for information about parameters.
delete(path, *, name=None, expect_handler=None)
Add a new RouteDef
item for registering DELETE
web-handler.
See UrlDispatcher.add_delete
for information about parameters.
view(path, *, name=None, expect_handler=None)
Add a new RouteDef
item for registering ANY
methods against a class-based view.
See UrlDispatcher.add_view
for information about parameters.
3.0
static(prefix, path, , name=None, expect_handler=None, chunk_size=2561024, show_index=False, follow_symlinks=False, append_version=False)
Add a new StaticDef
item for registering static files processor.
See UrlDispatcher.add_static
for information about supported parameters.
3.1
route(method, path, *, name=None, expect_handler=None)
Add a new RouteDef
item for registering a web-handler for arbitrary HTTP method.
See UrlDispatcher.add_route
for information about parameters.
After route matching web application calls found handler if any.
Matching result can be accessible from handler as Request.match_info
attribute.
In general the result may be any object derived from AbstractMatchInfo
(UrlMappingMatchInfo
for default UrlDispatcher
router).
Inherited from dict
and AbstractMatchInfo
. Dict items are filled by matching info and is resource
-specific.
expect_handler
A coroutine for handling 100-continue
.
handler
A coroutine for handling request.
route
Route
instance for url matching.
Inherited from AbstractView
.
Base class for class based views. Implementations should derive from View
and override methods for handling HTTP verbs like get()
or post()
:
class MyView(View):
async def get(self):
resp = await get_response(self.request)
return resp
async def post(self):
resp = await post_response(self.request)
return resp
app.router.add_view('/view', MyView)
The view raises 405 Method Not allowed (HTTPMethodNotAllowed
) if requested web verb is not supported.
- param request
instance of
Request
that has initiated a view processing.
request
Request sent to view's constructor, read-only property.
Overridable coroutine methods: connect()
, delete()
, get()
, head()
, options()
, patch()
, post()
, put()
, trace()
.
aiohttp-web-class-based-views
To start web application there is AppRunner
and site classes.
Runner is a storage for running application, sites are for running application on specific TCP or Unix socket, e.g.:
runner = web.AppRunner(app)
await runner.setup()
site = web.TCPSite(runner, 'localhost', 8080)
await site.start()
# wait for finish signal
await runner.cleanup()
3.0
AppRunner
/ ServerRunner
and TCPSite
/ UnixSite
/ SockSite
are added in aiohttp 3.0
A base class for runners. Use AppRunner
for serving Application
, ServerRunner
for low-level Server
.
server
Low-level web Server
for handling HTTP requests, read-only attribute.
addresses
A list
of served sockets addresses.
See socket.getsockname
for items type.
3.3
sites
A read-only set
of served sites (TCPSite
/ UnixSite
/ NamedPipeSite
/ SockSite
instances).
setup()
Initialize the server. Should be called before adding sites.
cleanup()
Stop handling all registered sites and cleanup used resources.
A runner for Application
. Used with conjunction with sites to serve on specific port.
Inherited from BaseRunner
.
- param Application app
web application instance to serve.
- param bool handle_signals
add signal handlers for
signal.SIGINT
andsignal.SIGTERM
(False
by default).- param kwargs
named parameters to pass into web protocol.
Supported kwargs:
- param bool tcp_keepalive
Enable TCP Keep-Alive. Default:
True
.- param int keepalive_timeout
Number of seconds before closing Keep-Alive connection. Default:
75
seconds (NGINX's default value).- param logger
Custom logger object. Default:
aiohttp.log.server_logger
.- param access_log
Custom logging object. Default:
aiohttp.log.access_logger
.- param access_log_class
Class for access_logger. Default:
aiohttp.helpers.AccessLogger
. Must to be a subclass ofaiohttp.abc.AbstractAccessLogger
.- param str access_log_format
Access log format string. Default:
helpers.AccessLogger.LOG_FORMAT
.- param int max_line_size
Optional maximum header line size. Default:
8190
.- param int max_headers
Optional maximum header size. Default:
32768
.- param int max_field_size
Optional maximum header field size. Default:
8190
.- param float lingering_time
Maximum time during which the server reads and ignores additional data coming from the client when lingering close is on. Use
0
to disable lingering on server channel closing.- param int read_bufsize
Size of the read buffer (
BaseRequest.content
).None
by default, it means that the session global value is used.
3.7
app
Read-only attribute for accessing to Application
served instance.
setup()
Initialize application. Should be called before adding sites.
The method calls Application.on_startup
registered signals.
cleanup()
Stop handling all registered sites and cleanup used resources.
Application.on_shutdown
and Application.on_cleanup
signals are called internally.
A runner for low-level Server
. Used with conjunction with sites to serve on specific port.
Inherited from BaseRunner
.
- param Server web_server
low-level web server instance to serve.
- param bool handle_signals
add signal handlers for
signal.SIGINT
andsignal.SIGTERM
(False
by default).- param kwargs
named parameters to pass into web protocol.
aiohttp-web-lowlevel
demonstrates low-level server usage
An abstract class for handled sites.
name
An identifier for site, read-only str
property. Could be a handled URL or UNIX socket path.
start()
Start handling a site.
stop()
Stop handling a site.
Serve a runner on TCP socket.
- param runner
a runner to serve.
- param str host
HOST to listen on, all interfaces if
None
(default).- param int port
PORT to listed on,
8080
ifNone
(default).- param float shutdown_timeout
a timeout for closing opened connections on
BaseSite.stop
call.- param ssl_context
a
ssl.SSLContext
instance for serving SSL/TLS secure server,None
for plain HTTP server (default).- param int backlog
a number of unaccepted connections that the system will allow before refusing new connections, see
socket.listen
for details.128
by default.- param bool reuse_address
tells the kernel to reuse a local socket in TIME_WAIT state, without waiting for its natural timeout to expire. If not specified will automatically be set to True on UNIX.
- param bool reuse_port
tells the kernel to allow this endpoint to be bound to the same port as other existing endpoints are bound to, so long as they all set this flag when being created. This option is not supported on Windows.
Serve a runner on UNIX socket.
- param runner
a runner to serve.
- param str path
PATH to UNIX socket to listen.
- param float shutdown_timeout
a timeout for closing opened connections on
BaseSite.stop
call.- param ssl_context
a
ssl.SSLContext
instance for serving SSL/TLS secure server,None
for plain HTTP server (default).- param int backlog
a number of unaccepted connections that the system will allow before refusing new connections, see
socket.listen
for details.128
by default.
Serve a runner on Named Pipe in Windows.
- param runner
a runner to serve.
- param str path
PATH of named pipe to listen.
- param float shutdown_timeout
a timeout for closing opened connections on
BaseSite.stop
call.
Serve a runner on UNIX socket.
- param runner
a runner to serve.
- param sock
socket.socket
to listen.- param float shutdown_timeout
a timeout for closing opened connections on
BaseSite.stop
call.- param ssl_context
a
ssl.SSLContext
instance for serving SSL/TLS secure server,None
for plain HTTP server (default).- param int backlog
a number of unaccepted connections that the system will allow before refusing new connections, see
socket.listen
for details.128
by default.
A ~collections.namedtuple
instance that is returned as multidict value by Request.POST
if field is uploaded file.
name
Field name
filename
File name as specified by uploading (client) side.
file
An io.IOBase
instance with content of uploaded file.
content_type
MIME type of uploaded file, 'text/plain'
by default.
aiohttp-web-file-upload
run_app(app, *, debug=False, host=None, port=None, path=None, sock=None, shutdown_timeout=60.0, keepalive_timeout=75.0, ssl_context=None, print=print, backlog=128, access_log_class=aiohttp.helpers.AccessLogger, access_log_format=aiohttp.helpers.AccessLogger.LOG_FORMAT, access_log=aiohttp.log.access_logger, handle_signals=True, reuse_address=None, reuse_port=None)
A utility function for running an application, serving it until keyboard interrupt and performing a aiohttp-web-graceful-shutdown
.
Suitable as handy tool for scaffolding aiohttp based projects. Perhaps production config will use more sophisticated runner but it good enough at least at very beginning stage.
The server will listen on any host or Unix domain socket path you supply. If no hosts or paths are supplied, or only a port is supplied, a TCP server listening on 0.0.0.0 (all hosts) will be launched.
Distributing HTTP traffic to multiple hosts or paths on the same application process provides no performance benefit as the requests are handled on the same event loop. See deployment
for ways of distributing work for increased performance.
- param app
Application
instance to run or a coroutine that returns an application.- param bool debug
enable
asyncio debug mode <asyncio-debug-mode>
ifTrue
.- param str host
TCP/IP host or a sequence of hosts for HTTP server. Default is
'0.0.0.0'
if port has been specified or if path is not supplied.- param int port
TCP/IP port for HTTP server. Default is
8080
for plain text HTTP and8443
for HTTP via SSL (when ssl_context parameter is specified).- param str path
file system path for HTTP server Unix domain socket. A sequence of file system paths can be used to bind multiple domain sockets. Listening on Unix domain sockets is not supported by all operating systems.
- param socket sock
a preexisting socket object to accept connections on. A sequence of socket objects can be passed.
- param int shutdown_timeout
a delay to wait for graceful server shutdown before disconnecting all open client sockets hard way.
A system with properly
aiohttp-web-graceful-shutdown
implemented never waits for this timeout but closes a server in a few milliseconds.- param float keepalive_timeout
a delay before a TCP connection is closed after a HTTP request. The delay allows for reuse of a TCP connection.
3.8
- param ssl_context
ssl.SSLContext
for HTTPS server,None
for HTTP connection.- param print
a callable compatible with
print
. May be used to override STDOUT output or suppress it. Passing None disables output.- param int backlog
the number of unaccepted connections that the system will allow before refusing new connections (
128
by default).- param access_log_class
class for access_logger. Default:
aiohttp.helpers.AccessLogger
. Must to be a subclass ofaiohttp.abc.AbstractAccessLogger
.- param access_log
logging.Logger
instance used for saving access logs. UseNone
for disabling logs for sake of speedup.- param access_log_format
access log format, see
aiohttp-logging-access-log-format-spec
for details.- param bool handle_signals
override signal TERM handling to gracefully exit the application.
- param bool reuse_address
tells the kernel to reuse a local socket in TIME_WAIT state, without waiting for its natural timeout to expire. If not specified will automatically be set to True on UNIX.
- param bool reuse_port
tells the kernel to allow this endpoint to be bound to the same port as other existing endpoints are bound to, so long as they all set this flag when being created. This option is not supported on Windows.
3.0
Support access_log_class parameter.
Support reuse_address, reuse_port parameter.
3.1
Accept a coroutine as app parameter.
An enum.Enum
class of available Content Codings.
deflate
DEFLATE compression
gzip
GZIP compression
identity
no compression
normalize_path_middleware(*, append_slash=True, remove_slash=False, merge_slashes=True, redirect_class=HTTPPermanentRedirect)
Middleware factory which produces a middleware that normalizes the path of a request. By normalizing it means:
- Add or remove a trailing slash to the path.
- Double slashes are replaced by one.
The middleware returns as soon as it finds a path that resolves correctly. The order if both merge and append/remove are enabled is:
- merge_slashes
- append_slash or remove_slash
- both merge_slashes and append_slash or remove_slash
If the path resolves with at least one of those conditions, it will redirect to the new path.
Only one of append_slash and remove_slash can be enabled. If both are True
the factory will raise an AssertionError
If append_slash is True
the middleware will append a slash when needed. If a resource is defined with trailing slash and the request comes without it, it will append it automatically.
If remove_slash is True
, append_slash must be False
. When enabled the middleware will remove trailing slashes and redirect if the resource is defined.
If merge_slashes is True
, merge multiple consecutive slashes in the path into one.
3.4
Support for remove_slash