Skip to content

Latest commit

 

History

History
3040 lines (1865 loc) · 94 KB

web_reference.rst

File metadata and controls

3040 lines (1865 loc) · 94 KB
Raw

Server Reference

aiohttp.web

Request and Base Request

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 Forwarded field-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 a token or a quoted-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.getfqdn

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

loop

An event loop instance used by HTTP request handling.

Read-only asyncio.AbstractEventLoop property.

3.5

cookies

A read-only dictionary-like object containing the request's cookies.

Read-only ~types.MappingProxyType 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

has_body

Return True if request's HTTP BODY can be read, False otherwise.

Read-only bool property.

2.3

Use can_read_body instead.

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:

  1. 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)

  2. 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 ~aiohttp.ETag objects specified in the If-Match header.

Returns tuple of ~aiohttp.ETag or None if If-Match header is absent.

3.8

if_none_match

Read-only property that returns ~aiohttp.ETag objects specified If-None-Match header.

Returns tuple of ~aiohttp.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 is None).

3.7

read()

Read request body, returns bytes object with body content.

Note

The method does store read data internally, subsequent ~aiohttp.web.BaseRequest.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 ~aiohttp.web.BaseRequest.text call will return the same value.

json(*, loads=json.loads)

Read request body decoded as json.

The method is just a boilerplate coroutine <coroutine> implemented as:

async def json(self, *, loads=json.loads):
    body = await self.text()
    return loads(body)
param collections.abc.Callable loads

any callable that accepts str and returns dict with parsed JSON (json.loads by default).

Note

The method does store read data internally, subsequent ~aiohttp.web.BaseRequest.json call will return the same value.

multipart()

Returns aiohttp.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 ~aiohttp.web.BaseRequest.post call will return the same value.

release()

Release request.

Eat unread part of HTTP BODY if present.

Note

User code may never call ~aiohttp.web.BaseRequest.release, all required work will be processed by aiohttp.web internal machinery.

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.

Response classes

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.

StreamResponse

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 pass str 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 aiohttp.web.BaseRequest.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)

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 or Strict. (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, ~aiohttp.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.

Response

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 ~aiohttp.StreamResponse.body value

Resetting text (assigning None) sets ~StreamResponse.content_length to None too, dropping Content-Length HTTP header.

WebSocketResponse

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 using ping 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 is True on success, WebSocketReady.protocol is websocket subprotocol which is passed by client and accepted by server (one of protocols sequence from WebSocketResponse ctor). WebSocketReady.protocol may be None 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) or bytes.

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) or bytes.

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 or memoryview.

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 collections.abc.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 not str

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) or bytes.

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 collections.abc.Callable loads

any callable that accepts str and returns dict 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>

WebSocketReady

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

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

HTTP Exceptions

Errors can also be returned by raising a HTTP exception instance from within the handler.

Low-level HTTP failure.

param headers

headers for the response

type headers

dict or multidict.CIMultiDict

param str reason

reason included in the response

param str text

response's body

param str content_type

response's content type. This is passed through to the Response initializer.

Sub-classes of HTTPException exist for the standard HTTP response codes as described in aiohttp-web-exceptions and the expected usage is to simply raise the appropriate exception type to respond with a specific HTTP response code.

Since HTTPException is a sub-class of Response, it contains the methods and properties that allow you to directly manipulate details of the response.

status_code

HTTP status code for this exception class. This attribute is usually defined at the class level. self.status_code is passed to the Response initializer.

Application and Router

Application

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 ~aiohttp.web.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 router

aiohttp.abc.AbstractRouter instance, the system creates UrlDispatcher by default if router is None.

3.3

The custom routers support is deprecated, the parameter will be removed in 4.0.

param middlewares

list of middleware factories, see aiohttp-web-middlewares for details.

param handler_args

dict-like object that overrides keyword arguments of Application.make_handler

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 loop

event loop

2.0

The parameter is deprecated. Loop is get set during freeze stage.

param debug

Switches debug mode.

3.5

Use asyncio asyncio-debug-mode instead.

router

Read-only property that returns router instance.

logger

logging.Logger instance for storing application logs.

loop

event loop<asyncio-event-loop> used for processing HTTP requests.

3.5

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 ~aiosignal.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 ~aiosignal.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.

on_shutdown

A ~aiosignal.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-handlers 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 ~aiosignal.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 ~aiohttp.web.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 registered AbstractRoute 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.

make_handler(loop=None, **kwargs)

Creates HTTP protocol factory for handling requests.

param loop

event loop<asyncio-event-loop> used for processing HTTP requests.

If param is None asyncio.get_event_loop used for getting default event loop.

2.0

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 of aiohttp.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.

You should pass result of the method as protocol_factory to ~asyncio.AbstractEventLoop.create_server, e.g.:

loop = asyncio.get_event_loop()

app = Application()

# setup route table
# app.router.add_route(...)

await loop.create_server(app.make_handler(),
                         '0.0.0.0', 8080)

3.2

The method is deprecated and will be removed in future aiohttp versions. Please use aiohttp-web-app-runners instead.

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 ~aiohttp.abc.AbstractRouter: it should have only aiohttp.abc.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).

Server

A protocol factory compatible with ~asyncio.AbstractEventLoop.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.

Router

For dispatching URLs to handlers<aiohttp-web-handler> aiohttp.web uses routers.

Router is any object that implements ~aiohttp.abc.AbstractRouter interface.

aiohttp.web provides an implementation called UrlDispatcher.

Application uses UrlDispatcher as ~aiohttp.web.Application.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 or DynamicResource).

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}' (see handling variable paths <aiohttp-web-variable-handler>)

Pay attention please: handler is converted to coroutine internally when it is a regular function.

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 collections.abc.Callable handler

route handler.

param str name

optional route name.

param collections.abc.Coroutine expect_handler

optional expect header handler.

returns

new AbstractRoute instance.

add_routes(routes_table)

Register route definitions from routes_table.

The table is a list of RouteDef items or RouteTableDef.

returns

list of registered AbstractRoute 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 or pathlib.Path.

param str name

optional route name.

param collections.abc.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 ~aiohttp.web.AbstractRoute.url and ~aiohttp.web.AbstractRoute.url_for methods.

returns

new ~aiohttp.web.AbstractRoute instance.

resolve(request)

A coroutine<coroutine> that returns ~aiohttp.abc.AbstractMatchInfo for request.

The method never raises exception, but returns ~aiohttp.abc.AbstractMatchInfo instance with:

  1. ~aiohttp.abc.AbstractMatchInfo.http_exception assigned to HTTPException instance.

  2. ~aiohttp.abc.AbstractMatchInfo.handler which raises HTTPNotFound or HTTPMethodNotAllowed 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 aiohttp.web.BaseRequest.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:

  1. Get size of the router table:

    len(app.router.resources())

  2. Iterate over registered resources:

    for resource in app.router.resources():
    print(resource)

  3. 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 AbstractResource 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"]

Resource

Default router UrlDispatcher operates with resources.

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:

  1. Router iterates over resources one-by-one.
  2. If resource matches to requested URL the resource iterates over own routes.
  3. If route matches to requested HTTP method (or '*' wildcard) the route's handler is used as found web-handler. The lookup is finished.
  4. Otherwise router tries next resource from the routing table.
  5. If the end of routing table is reached and no resource / route pair found the router returns special ~aiohttp.abc.AbstractMatchInfo instance with aiohttp.abc.AbstractMatchInfo.http_exception is not None but HTTPException with either HTTP 404 Not Found or HTTP 405 Method Not Allowed status code. Registered ~aiohttp.abc.AbstractMatchInfo.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 routes 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 or None if no route 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 collections.abc.Callable handler

route handler.

param collections.abc.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 as resource.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 and pathlib.Path.

E.g. an URL for '/prefix/dir/file.txt' should be generated as resource.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 to True - v=FILE_HASH query string param will be added When set to False has no impact

if 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

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

RouteDef and StaticDef

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 registered AbstractRoute 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

RouteTableDef

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 collections.abc.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.

MatchInfo

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 ~aiohttp.abc.AbstractMatchInfo (UrlMappingMatchInfo for default UrlDispatcher router).

Inherited from dict and ~aiohttp.abc.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

AbstractRoute instance for url matching.

View

Inherited from ~aiohttp.abc.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

Running Applications

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() <socket.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 and signal.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 of aiohttp.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

param bool auto_decompress

Automatically decompress request body, True by default.

3.8

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 and signal.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 if None (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.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.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

A socket instance <socket-objects> to listen to.

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.socket.listen for details.

128 by default.

Utilities

A dataclass <dataclasses> instance that is returned as multidict value by aiohttp.web.BaseRequest.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, *, 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 high-level function for running an application, serving it until keyboard interrupt and performing a aiohttp-web-graceful-shutdown.

This is a high-level function very similar to asyncio.run and should be used as the main entry point for an application. The Application object essentially becomes our main() function. If additional tasks need to be run in parallel, see aiohttp-web-complex-applications.

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 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 and 8443 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.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 of aiohttp.abc.AbstractAccessLogger.

param access_log

logging.Logger instance used for saving access logs. Use None 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.

Constants

An enum.Enum class of available Content Codings.

deflate

DEFLATE compression

gzip

GZIP compression

identity

no compression

Middlewares

Normalize path middleware

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:

  1. merge_slashes
  2. append_slash or remove_slash
  3. 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