.. module:: aiohttp.web
.. currentmodule:: aiohttp.web
The Request object contains all the information about an incoming HTTP request.
:class:`BaseRequest` is used for :ref:`Low-Level Servers<aiohttp-web-lowlevel>` (which have no applications, routers, signals and middlewares). :class:`Request` has an :attr:`Request.app` and :attr:`Request.match_info` attributes.
A :class:`BaseRequest` / :class:`Request` are :obj:`dict` like objects, allowing them to be used for :ref:`sharing data<aiohttp-web-data-sharing>` among :ref:`aiohttp-web-middlewares` and :ref:`aiohttp-web-signals` handlers.
.. attribute:: version *HTTP version* of request, Read-only property. Returns :class:`aiohttp.protocol.HttpVersion` instance... attribute:: method *HTTP method*, read-only property. The value is upper-cased :class:`str` like ``"GET"``, ``"POST"``, ``"PUT"`` etc... attribute:: url A :class:`~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... attribute:: rel_url A :class:`~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. .. seealso:: A note from :attr:`url`... attribute:: 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 :meth:`~BaseRequest.clone`. ``'http'`` otherwise. Read-only :class:`str` property. .. versionchanged:: 2.3 *Forwarded* and *X-Forwarded-Proto* are not used anymore. Call ``.clone(scheme=new_scheme)`` for setting up the value explicitly. .. seealso:: :ref:`aiohttp-web-forwarded-support`.. attribute:: secure Shorthand for ``request.url.scheme == 'https'`` Read-only :class:`bool` property. .. seealso:: :attr:`scheme`.. attribute:: forwarded A tuple containing all parsed Forwarded header(s). Makes an effort to parse Forwarded headers as specified by :rfc:`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 :rfc:`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 :rfc:`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 .. seealso:: :attr:`scheme` .. seealso:: :attr:`host`.. attribute:: host Host name of the request, resolved in this order: - Overridden value by :meth:`~BaseRequest.clone` call. - *Host* HTTP header - :func:`socket.gtfqdn` Read-only :class:`str` property. .. versionchanged:: 2.3 *Forwarded* and *X-Forwarded-Host* are not used anymore. Call ``.clone(host=new_host)`` for setting up the value explicitly. .. seealso:: :ref:`aiohttp-web-forwarded-support`.. attribute:: remote Originating IP address of a client initiated HTTP request. The IP is resolved through the following headers, in this order: - Overridden value by :meth:`~BaseRequest.clone` call. - Peer name of opened socket. Read-only :class:`str` property. Call ``.clone(remote=new_remote)`` for setting up the value explicitly. .. versionadded:: 2.3 .. seealso:: :ref:`aiohttp-web-forwarded-support`.. attribute:: path_qs The URL including PATH_INFO and the query string. e.g., ``/app/blog?id=10`` Read-only :class:`str` property... attribute:: path The URL including *PATH INFO* without the host or scheme. e.g., ``/app/blog``. The path is URL-unquoted. For raw path info see :attr:`raw_path`. Read-only :class:`str` property... attribute:: raw_path The URL including raw *PATH INFO* without the host or scheme. Warning, the path may be quoted and may contains non valid URL characters, e.g. ``/my%2Fpath%7Cwith%21some%25strange%24characters``. For unquoted version please take a look on :attr:`path`. Read-only :class:`str` property... attribute:: query A multidict with all the variables in the query string. Read-only :class:`~multidict.MultiDictProxy` lazy property... attribute:: query_string The query string in the URL, e.g., ``id=10`` Read-only :class:`str` property... attribute:: headers A case-insensitive multidict proxy with all headers. Read-only :class:`~multidict.CIMultiDictProxy` property... attribute:: raw_headers HTTP headers of response as unconverted bytes, a sequence of ``(key, value)`` pairs... attribute:: keep_alive ``True`` if keep-alive connection enabled by HTTP client and protocol version supports it, otherwise ``False``. Read-only :class:`bool` property... attribute:: transport An :ref:`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.. attribute:: loop An event loop instance used by HTTP request handling. Read-only :class:`asyncio.AbstractEventLoop` property. .. versionadded:: 2.3.. attribute:: cookies A multidict of all request's cookies. Read-only :class:`~multidict.MultiDictProxy` lazy property... attribute:: content A :class:`~aiohttp.StreamReader` instance, input stream for reading request's *BODY*. Read-only property... attribute:: body_exists Return ``True`` if request has *HTTP BODY*, ``False`` otherwise. Read-only :class:`bool` property. .. versionadded:: 2.3.. attribute:: can_read_body Return ``True`` if request's *HTTP BODY* can be read, ``False`` otherwise. Read-only :class:`bool` property. .. versionadded:: 2.3.. attribute:: has_body Return ``True`` if request's *HTTP BODY* can be read, ``False`` otherwise. Read-only :class:`bool` property. .. deprecated:: 2.3 Use :meth:`can_read_body` instead.
.. attribute:: content_type
Read-only property with *content* part of *Content-Type* header.
Returns :class:`str` like ``'text/html'``
.. note::
Returns value is ``'application/octet-stream'`` if no
Content-Type header present in HTTP headers according to
:rfc:`2616`
.. attribute:: charset
Read-only property that specifies the *encoding* for the request's BODY.
The value is parsed from the *Content-Type* HTTP header.
Returns :class:`str` like ``'utf-8'`` or ``None`` if
*Content-Type* has no charset information.
.. attribute:: content_length
Read-only property that returns length of the request's BODY.
The value is parsed from the *Content-Length* HTTP header.
Returns :class:`int` or ``None`` if *Content-Length* is absent.
.. attribute:: http_range
Read-only property that returns information about *Range* HTTP header.
Returns a :class:`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]
.. versionadded:: 1.2
.. attribute:: if_modified_since
Read-only property that returns the date specified in the
*If-Modified-Since* header.
Returns :class:`datetime.datetime` or ``None`` if
*If-Modified-Since* header is absent or is not a valid
HTTP date.
.. method:: 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, :class:`str` or :class:`~yarl.URL`
:param headers: :class:`~multidict.CIMultiDict` or compatible
headers container.
:return: a cloned :class:`Request` instance.
.. comethod:: read()
Read request body, returns :class:`bytes` object with body content.
.. note::
The method **does** store read data internally, subsequent
:meth:`~Request.read` call will return the same value.
.. comethod:: text()
Read request body, decode it using :attr:`charset` encoding or
``UTF-8`` if no encoding was specified in *MIME-type*.
Returns :class:`str` with body content.
.. note::
The method **does** store read data internally, subsequent
:meth:`~Request.text` call will return the same value.
.. comethod:: json(*, loads=json.loads)
Read request body decoded as *json*.
The method is just a boilerplate :ref:`coroutine <coroutine>`
implemented as::
async def json(self, *, loads=json.loads):
body = await self.text()
return loads(body)
:param callable loads: any :term:`callable` that accepts
:class:`str` and returns :class:`dict`
with parsed JSON (:func:`json.loads` by
default).
.. note::
The method **does** store read data internally, subsequent
:meth:`~Request.json` call will return the same value.
.. comethod:: multipart(*, reader=aiohttp.multipart.MultipartReader)
Returns :class:`aiohttp.multipart.MultipartReader` which processes
incoming *multipart* request.
The method is just a boilerplate :ref:`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.
.. seealso:: :ref:`aiohttp-multipart`
.. comethod:: post()
A :ref:`coroutine <coroutine>` that reads POST parameters from
request body.
Returns :class:`~multidict.MultiDictProxy` instance filled
with parsed data.
If :attr:`method` is not *POST*, *PUT*, *PATCH*, *TRACE* or *DELETE* or
:attr:`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
:meth:`~Request.post` call will return the same value.
.. comethod:: release()
Release request.
Eat unread part of HTTP BODY if present.
.. note::
User code may never call :meth:`~Request.release`, all
required work will be processed by :mod:`aiohttp.web`
internal machinery.
An request used for receiving request's information by web handler.
Every :ref:`handler<aiohttp-web-handler>` accepts a request instance as the first positional parameter.
The class in derived from :class:`BaseRequest`, shares all parent's attributes and methods but has a couple of additional properties:
.. attribute:: match_info
Read-only property with :class:`~aiohttp.abc.AbstractMatchInfo`
instance for result of route resolving.
.. note::
Exact type of property depends on used router. If
``app.router`` is :class:`UrlDispatcher` the property contains
:class:`UrlMappingMatchInfo` instance.
.. attribute:: app An :class:`Application` instance used to call :ref:`request handler <aiohttp-web-handler>`, Read-only property.
Note
You should never create the :class:`Request` instance manually -- :mod:`aiohttp.web` does it for you. But :meth:`~BaseRequest.clone` may be used for cloning modified request copy with changed path, method etc.
For now, :mod:`aiohttp.web` has three classes for the HTTP response: :class:`StreamResponse`, :class:`Response` and :class:`FileResponse`.
Usually you need to use the second one. :class:`StreamResponse` is intended for streaming data, while :class:`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 :class:`Response` is derived from :class:`StreamResponse` parent class.
The response supports keep-alive handling out-of-the-box if request supports it.
You can disable keep-alive by :meth:`~StreamResponse.force_close` though.
The common case for sending an answer from :ref:`web-handler<aiohttp-web-handler>` is returning a :class:`Response` instance:
def handler(request):
return Response("All right!")
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 :meth:`prepare` coroutine is called.
Once you call :meth:`prepare` any change of the HTTP header part will raise :exc:`RuntimeError` exception.
Any :meth:`write` call after :meth:`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 :class:`str` with
arbitrary status explanation.. |
.. attribute:: prepared Read-only :class:`bool` property, ``True`` if :meth:`prepare` has been called, ``False`` otherwise. .. versionadded:: 0.18
.. attribute:: task A task that serves HTTP request handling. May be useful for graceful shutdown of long-running requests (streaming, long polling or web-socket). .. versionadded:: 1.2
.. attribute:: status Read-only property for *HTTP response status code*, :class:`int`. ``200`` (OK) by default.
.. attribute:: reason Read-only property for *HTTP response reason*, :class:`str`.
.. method:: set_status(status, reason=None) Set :attr:`status` and :attr:`reason`. *reason* value is auto calculated if not specified (``None``).
.. attribute:: keep_alive Read-only property, copy of :attr:`Request.keep_alive` by default. Can be switched to ``False`` by :meth:`force_close` call.
.. method:: force_close Disable :attr:`keep_alive` for connection. There are no ways to enable it back.
.. attribute:: compression Read-only :class:`bool` property, ``True`` if compression is enabled. ``False`` by default. .. seealso:: :meth:`enable_compression`
.. method:: 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 :class:`ContentCoding`. .. seealso:: :attr:`compression`
.. attribute:: chunked Read-only property, indicates if chunked encoding is on. Can be enabled by :meth:`enable_chunked_encoding` call. .. seealso:: :attr:`enable_chunked_encoding`
.. method:: enable_chunked_encoding
Enables :attr:`chunked` encoding for response. There are no ways to
disable it back. With enabled :attr:`chunked` encoding each :meth:`write`
operation encoded in separate chunk.
.. warning:: chunked encoding can be enabled for ``HTTP/1.1`` only.
Setting up both :attr:`content_length` and chunked
encoding is mutually exclusive.
.. seealso:: :attr:`chunked`
.. attribute:: headers :class:`~multidict.CIMultiDict` instance for *outgoing* *HTTP headers*.
.. attribute:: cookies
An instance of :class:`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 :attr:`cookies` and
:meth:`set_cookie`, :meth:`del_cookie` for cookie
manipulations.
.. method:: set_cookie(name, value, *, path='/', expires=None, \
domain=None, max_age=None, \
secure=None, httponly=None, version=None)
Convenient way for setting :attr:`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
:class:`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)
.. 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``.
.. method:: 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
.. versionchanged:: 1.0
Fixed cookie expiration support for
Internet Explorer (version less than 11).
.. attribute:: content_length *Content-Length* for outgoing response.
.. attribute:: content_type *Content* part of *Content-Type* for outgoing response.
.. attribute:: charset *Charset* aka *encoding* part of *Content-Type* for outgoing response. The value converted to lower-case on attribute assigning.
.. attribute:: last_modified *Last-Modified* header for outgoing response. This property accepts raw :class:`str` values, :class:`datetime.datetime` objects, Unix timestamps specified as an :class:`int` or a :class:`float` object, and the value ``None`` to unset the header.
.. attribute:: tcp_cork :const:`~socket.TCP_CORK` (linux) or :const:`~socket.TCP_NOPUSH` (FreeBSD and MacOSX) is applied to underlying transport if the property is ``True``. Use :meth:`set_tcp_cork` to assign new value to the property. Default value is ``False``.
.. method:: set_tcp_cork(value) Set :attr:`tcp_cork` property to *value*. Clear :attr:`tcp_nodelay` if *value* is ``True``.
.. attribute:: tcp_nodelay :const:`~socket.TCP_NODELAY` is applied to underlying transport if the property is ``True``. Use :meth:`set_tcp_nodelay` to assign new value to the property. Default value is ``True``.
.. method:: set_tcp_nodelay(value) Set :attr:`tcp_nodelay` property to *value*. Clear :attr:`tcp_cork` if *value* is ``True``.
.. comethod:: 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 :attr:`~aiohttp.web.Application.on_response_prepare`
signal handlers.
.. versionadded:: 0.18
.. comethod:: write(data)
Send byte-ish data as the part of *response BODY*::
await resp.write(data)
:meth:`prepare` must be invoked before the call.
Raises :exc:`TypeError` if data is not :class:`bytes`,
:class:`bytearray` or :class:`memoryview` instance.
Raises :exc:`RuntimeError` if :meth:`prepare` has not been called.
Raises :exc:`RuntimeError` if :meth:`write_eof` has been called.
.. comethod:: write_eof() A :ref:`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 :meth:`write_eof` call any manipulations with the *response* object are forbidden.
.. seealso:: :ref:`WebSockets handling<aiohttp-web-websockets>`
A named tuple for returning result from :meth:`WebSocketResponse.can_prepare`.
Has :class:`bool` check implemented, e.g.:
if not await ws.can_prepare(...):
cannot_start_websocket()
.. attribute:: ok ``True`` if websocket connection can be established, ``False`` otherwise.
.. attribute:: protocol :class:`str` represented selected websocket sub-protocol.
.. seealso:: :meth:`WebSocketResponse.can_prepare`
.. function:: json_response([data], *, text=None, body=None, \
status=200, reason=None, headers=None, \
content_type='application/json', \
dumps=json.dumps)
Return :class:`Response` with predefined 'application/json'
content type and data encoded by dumps parameter
(:func:`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 create a server socket with :class:`~aiohttp.web.Server` as a protocol factory. Server could be constructed with :meth:`Application.make_handler`.
Application contains a router instance and a list of callbacks that will be called during application finishing.
:class:`Application` is a :obj:`dict`-like object, so you can use it for :ref:`sharing data<aiohttp-web-data-sharing>` globally by storing arbitrary properties for later access from a :ref:`handler<aiohttp-web-handler>` via the :attr:`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 :class:`Application` is a :obj:`dict`-like object, it can't be duplicated like one using :meth:`Application.copy`.
A protocol factory compatible with :meth:`~asyncio.AbstreactEventLoop.create_server`.
The class is responsible for creating HTTP protocol objects that can handle HTTP connections.
.. attribute:: Server.connections List of all currently opened connections... attribute:: requests_count Amount of processed requests. .. versionadded:: 1.0.. comethod:: Server.shutdown(timeout) A :ref:`coroutine<coroutine>` that should be called to close all opened connections.
For dispatching URLs to :ref:`handlers<aiohttp-web-handler>` :mod:`aiohttp.web` uses routers.
Router is any object that implements :class:`AbstractRouter` interface.
:mod:`aiohttp.web` provides an implementation called :class:`UrlDispatcher`.
:class:`Application` uses :class:`UrlDispatcher` as :meth:`router` by default.
Straightforward url-matching router, implements :class:`collections.abc.Mapping` for access to named routes.
Before running :class:`Application` you should fill route table first by calling :meth:`add_route` and :meth:`add_static`.
:ref:`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.
.. seealso:: :ref:`Route classes <aiohttp-web-route>`
.. method:: add_resource(path, *, name=None)
Append a :term:`resource` to the end of route table.
*path* may be either *constant* string like ``'/a/b/c'`` or
*variable rule* like ``'/a/{var}'`` (see
:ref:`handling variable paths <aiohttp-web-variable-handler>`)
:param str path: resource path spec.
:param str name: optional resource name.
:return: created resource instance (:class:`PlainResource` or
:class:`DynamicResource`).
.. method:: add_route(method, path, handler, *, \
name=None, expect_handler=None)
Append :ref:`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
:ref:`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 callable handler: route handler.
:param str name: optional route name.
:param coroutine expect_handler: optional *expect* header handler.
:returns: new :class:`PlainRoute` or :class:`DynamicRoute` instance.
.. method:: add_routes(routes_table) Register route definitions from *routes_table*. The table is a :class:`list` of :class:`RouteDef` items or :class:`RouteTableDef`. .. versionadded:: 2.3
.. method:: add_get(path, handler, *, name=None, allow_head=True, **kwargs)
Shortcut for adding a GET handler. Calls the :meth:`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'``.
.. versionadded:: 1.0
.. versionchanged:: 2.0
*allow_head* parameter added.
.. method:: add_post(path, handler, **kwargs) Shortcut for adding a POST handler. Calls the :meth:`add_route` with \ ``method`` equals to ``'POST'``. .. versionadded:: 1.0
.. method:: add_head(path, handler, **kwargs) Shortcut for adding a HEAD handler. Calls the :meth:`add_route` with \ ``method`` equals to ``'HEAD'``. .. versionadded:: 1.0
.. method:: add_put(path, handler, **kwargs) Shortcut for adding a PUT handler. Calls the :meth:`add_route` with \ ``method`` equals to ``'PUT'``. .. versionadded:: 1.0
.. method:: add_patch(path, handler, **kwargs) Shortcut for adding a PATCH handler. Calls the :meth:`add_route` with \ ``method`` equals to ``'PATCH'``. .. versionadded:: 1.0
.. method:: add_delete(path, handler, **kwargs) Shortcut for adding a DELETE handler. Calls the :meth:`add_route` with \ ``method`` equals to ``'DELETE'``. .. versionadded:: 1.0
.. method:: add_static(prefix, path, *, name=None, expect_handler=None, \
chunk_size=256*1024, \
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 :meth:`add_static` for development only. In production,
static content should be processed by web servers like *nginx*
or *apache*.
.. versionchanged:: 0.18.0
Transfer files using the ``sendfile`` system call on supported
platforms.
.. versionchanged:: 0.19.0
Disable ``sendfile`` by setting environment variable
``AIOHTTP_NOSENDFILE=1``
.. versionchanged:: 1.2.0
Send gzip version if file path + ``.gz`` exists.
:param str prefix: URL path prefix for handled static files
:param path: path to the folder in file system that contains
handled static files, :class:`str` or :class:`pathlib.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.
.. versionadded:: 0.16
:param callable response_factory: factory to use to generate a new
response, defaults to
:class:`StreamResponse` and should
expose a compatible API.
.. versionadded:: 0.17
: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 :meth:`StaticRoute.url`
and :meth:`StaticRoute.url_for` methods.
:returns: new :class:`StaticRoute` instance.
.. method:: 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 :class:`PrefixedSubAppResource` instance. .. versionadded:: 1.1
.. comethod:: resolve(request)
A :ref:`coroutine<coroutine>` that returns
:class:`AbstractMatchInfo` for *request*.
The method never raises exception, but returns
:class:`AbstractMatchInfo` instance with:
1. :attr:`~AbstractMatchInfo.http_exception` assigned to
:exc:`HTTPException` instance.
2. :attr:`~AbstractMatchInfo.handler` which raises
:exc:`HTTPNotFound` or :exc:`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 :attr:`Request.raw_path` for pattern
matching against registered routes.
.. method:: 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()
.. versionadded:: 0.21.1
.. method:: routes() The method returns a *view* for *all* registered routes. .. versionadded:: 0.18
.. method:: named_resources()
Returns a :obj:`dict`-like :class:`types.MappingProxyType` *view* over
*all* named **resources**.
The view maps every named resource's **name** to the
:class:`BaseResource` instance. It supports the usual
:obj:`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"]
.. versionadded:: 0.21
.. method:: named_routes()
An alias for :meth:`named_resources` starting from aiohttp 0.21.
.. versionadded:: 0.19
.. versionchanged:: 0.21
The method is an alias for :meth:`named_resources`, so it
iterates over resources instead of routes.
.. deprecated:: 0.21
Please use named **resources** instead of named **routes**.
Several routes which belongs to the same resource shares the
resource name.
Default router :class:`UrlDispatcher` operates with :term:`resource`s.
Resource is an item in routing table which has a path, an optional unique name and at least one :term:`route`.
:term:`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 found :term:`web-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 :class:`AbstractMatchInfo`
instance with :attr:`AbstractMatchInfo.http_exception` is not
Nonebut :exc:`HTTPException` with either HTTP 404 Not Found or HTTP 405 Method Not Allowed status code. Registered :attr:`AbstractMatchInfo.handler` raises this exception on call.
User should never instantiate resource classes but give it by :meth:`UrlDispatcher.add_resource` call.
After that he may add a :term:`route` by calling :meth:`Resource.add_route`.
:meth:`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 :class:`collections.abc.Sized` and :class:`collections.abc.Iterable`.
len(resource) returns amount of :term:`route`s belongs to the resource,
for route in resource allows to iterate over these routes.
.. attribute:: name Read-only *name* of resource or ``None``.
.. comethod:: resolve(method, path)
Resolve resource by finding appropriate :term:`web-handler` for
``(method, path)`` combination.
:param str method: requested HTTP method.
:param str path: *path* part of request.
:return: (*match_info*, *allowed_methods*) pair.
*allowed_methods* is a :class:`set` or HTTP methods accepted by
resource.
*match_info* is either :class:`UrlMappingMatchInfo` if
request is resolved or ``None`` if no :term:`route` is
found.
.. method:: 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]+)$``
.. method:: 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: :class:`~yarl.URL` -- resulting URL instance. .. versionadded:: 1.1
.. method:: url(**kwargs)
Construct an URL for route with additional params.
**kwargs** depends on a list accepted by inherited resource
class parameters.
:return: :class:`str` -- resulting URL string.
.. deprecated:: 1.1
Use :meth:`url_for` instead.
A base class for new-style resources, inherits :class:`AbstractResource`.
.. method:: add_route(method, handler, *, expect_handler=None)
Add a :term:`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 :class:`ResourceRoute` instance.
A resource, inherited from :class:`Resource`.
The class corresponds to resources with plain-text matching,
'/path/to' for example.
.. method:: url_for() Returns a :class:`~yarl.URL` for the resource. .. versionadded:: 1.1
A resource, inherited from :class:`Resource`.
The class corresponds to resources with
:ref:`variable <aiohttp-web-variable-handler>` matching,
e.g. '/path/{to}/{param}' etc.
.. method:: url_for(**params)
Returns a :class:`~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')``
.. versionadded:: 1.1
A resource, inherited from :class:`Resource`.
The class corresponds to resources for :ref:`static file serving <aiohttp-web-static-file-handling>`.
.. method:: url_for(filename, append_version=None)
Returns a :class:`~yarl.URL` for file path under resource prefix.
:param filename: -- a file name substitution for static file handler.
Accepts both :class:`str` and :class:`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 an 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
.. versionadded:: 1.1
A resource for serving nested applications. The class instance is returned by :class:`~aiohttp.web.Application.add_subapp` call.
.. versionadded:: 1.1
.. method:: url_for(**kwargs) The call is not allowed, it raises :exc:`RuntimeError`.
Route has HTTP method (wildcard '*' is an option),
:term:`web-handler` and optional expect handler.
Every route belong to some resource.
Route classes hierarchy:
AbstractRoute ResourceRoute SystemRoute
:class:`ResourceRoute` is the route used for resources, :class:`SystemRoute` serves URL resolving errors like 404 Not Found and 405 Method Not Allowed.
Base class for routes served by :class:`UrlDispatcher`.
.. attribute:: method HTTP method handled by the route, e.g. *GET*, *POST* etc.
.. attribute:: handler :ref:`handler<aiohttp-web-handler>` that processes the route.
.. attribute:: name Name of the route, always equals to name of resource which owns the route.
.. attribute:: resource Resource instance which holds the route, ``None`` for :class:`SystemRoute`.
.. method:: url_for(*args, **kwargs) Abstract method for constructing url handled by the route. Actually it's a shortcut for ``route.resource.url_for(...)``.
.. comethod:: handle_expect_header(request) ``100-continue`` handler.
The route class for handling different HTTP methods for :class:`Resource`.
The route class for handling URL resolution errors like like 404 Not Found and 405 Method Not Allowed.
.. attribute:: status HTTP status code
.. attribute:: 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 :func:`get` or :func:`post`, list of definitions could be added to router by :meth:`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 definition for not added yet route.
.. attribute:: method HTTP method (``GET``, ``POST`` etc.) (:class:`str`).
.. attribute:: path
Path to resource, e.g. ``/path/to``. Could contain ``{}``
brackets for :ref:`variable resources
<aiohttp-web-variable-handler>` (:class:`str`).
.. attribute:: handler An async function to handle HTTP request.
.. attribute:: kwargs A :class:`dict` of additional arguments.
.. versionadded:: 2.3
.. function:: get(path, handler, *, name=None, allow_head=True, \
expect_handler=None)
Return :class:`RouteDef` for processing ``GET`` requests. See
:meth:`UrlDispatcher.add_get` for information about parameters.
.. versionadded:: 2.3
.. function:: post(path, handler, *, name=None, expect_handler=None) Return :class:`RouteDef` for processing ``POST`` requests. See :meth:`UrlDispatcher.add_post` for information about parameters. .. versionadded:: 2.3
.. function:: head(path, handler, *, name=None, expect_handler=None) Return :class:`RouteDef` for processing ``HEAD`` requests. See :meth:`UrlDispatcher.add_head` for information about parameters. .. versionadded:: 2.3
.. function:: put(path, handler, *, name=None, expect_handler=None) Return :class:`RouteDef` for processing ``PUT`` requests. See :meth:`UrlDispatcher.add_put` for information about parameters. .. versionadded:: 2.3
.. function:: patch(path, handler, *, name=None, expect_handler=None) Return :class:`RouteDef` for processing ``PATCH`` requests. See :meth:`UrlDispatcher.add_patch` for information about parameters. .. versionadded:: 2.3
.. function:: delete(path, handler, *, name=None, expect_handler=None) Return :class:`RouteDef` for processing ``DELETE`` requests. See :meth:`UrlDispatcher.add_delete` for information about parameters. .. versionadded:: 2.3
.. function:: route(method, path, handler, *, name=None, expect_handler=None) Return :class:`RouteDef` for processing ``POST`` requests. See :meth:`UrlDispatcher.add_route` for information about parameters. .. versionadded:: 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)
A sequence of :class:`RouteDef` instances (implements :class:`abc.collections.Sequence` protocol).
In addition to all standard :class:`list` methods the class
provides also methods like get() and post() for adding new
route definition.
.. decoratormethod:: get(path, *, allow_head=True, \
name=None, expect_handler=None)
Add a new :class:`RouteDef` item for registering ``GET`` web-handler.
See :meth:`UrlDispatcher.add_get` for information about parameters.
.. decoratormethod:: post(path, *, name=None, expect_handler=None) Add a new :class:`RouteDef` item for registering ``POST`` web-handler. See :meth:`UrlDispatcher.add_post` for information about parameters.
.. decoratormethod:: head(path, *, name=None, expect_handler=None) Add a new :class:`RouteDef` item for registering ``HEAD`` web-handler. See :meth:`UrlDispatcher.add_head` for information about parameters.
.. decoratormethod:: put(path, *, name=None, expect_handler=None) Add a new :class:`RouteDef` item for registering ``PUT`` web-handler. See :meth:`UrlDispatcher.add_put` for information about parameters.
.. decoratormethod:: patch(path, *, name=None, expect_handler=None) Add a new :class:`RouteDef` item for registering ``PATCH`` web-handler. See :meth:`UrlDispatcher.add_patch` for information about parameters.
.. decoratormethod:: delete(path, *, name=None, expect_handler=None) Add a new :class:`RouteDef` item for registering ``DELETE`` web-handler. See :meth:`UrlDispatcher.add_delete` for information about parameters.
.. decoratormethod:: route(method, path, *, name=None, expect_handler=None) Add a new :class:`RouteDef` item for registering a web-handler for arbitrary HTTP method. See :meth:`UrlDispatcher.add_route` for information about parameters.
.. versionadded:: 2.3
After route matching web application calls found handler if any.
Matching result can be accessible from handler as :attr:`Request.match_info` attribute.
In general the result may be any object derived from :class:`AbstractMatchInfo` (:class:`UrlMappingMatchInfo` for default :class:`UrlDispatcher` router).
Inherited from :class:`dict` and :class:`AbstractMatchInfo`. Dict items are filled by matching info and is :term:`resource`-specific.
.. attribute:: expect_handler A coroutine for handling ``100-continue``.
.. attribute:: handler A coroutine for handling request.
.. attribute:: route :class:`Route` instance for url matching.
Inherited from :class:`AbstractView`.
Base class for class based views. Implementations should derive from
:class:`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_route('*', '/view', MyView)
The view raises 405 Method Not allowed (:class:`HTTPMethodNowAllowed`) if requested web verb is not supported.
| param request: | instance of :class:`Request` that has initiated a view processing. |
|---|
.. attribute:: request Request sent to view's constructor, read-only property.
Overridable coroutine methods: connect(), delete(),
get(), head(), options(), patch(), post(),
put(), trace().
.. seealso:: :ref:`aiohttp-web-class-based-views`
A :class:`~collections.namedtuple` instance that is returned as multidict value by :meth:`Request.POST` if field is uploaded file.
.. attribute:: name Field name
.. attribute:: filename File name as specified by uploading (client) side.
.. attribute:: file An :class:`io.IOBase` instance with content of uploaded file.
.. attribute:: content_type *MIME type* of uploaded file, ``'text/plain'`` by default.
.. seealso:: :ref:`aiohttp-web-file-upload`
.. function:: run_app(app, *, host=None, port=None, path=None, \
sock=None, shutdown_timeout=60.0, \
ssl_context=None, print=print, backlog=128, \
access_log_format=None, \
access_log=aiohttp.log.access_logger, \
handle_signals=True, loop=None)
A utility function for running an application, serving it until
keyboard interrupt and performing a
:ref:`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 function uses *app.loop* as event loop to run.
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 :doc:`deployment` for ways of
distributing work for increased performance.
:param app: :class:`Application` instance to run
: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 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
:ref:`aiohttp-web-graceful-shutdown`
implemented never waits for this
timeout but closes a server in a few
milliseconds.
:param ssl_context: :class:`ssl.SSLContext` for HTTPS server,
``None`` for HTTP connection.
:param print: a callable compatible with :func:`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:`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
:ref:`aiohttp-logging-access-log-format-spec`
for details.
:param bool handle_signals: override signal TERM handling to gracefully
exit the application.
:param loop: an *event loop* used for running the application
(``None`` by default).
If the loop is not explicitly specified the function
closes it by :meth:`~asyncio.AbstractEventLoop.close` call but
**does nothing** for **non-default** loop.
An :class:`enum.Enum` class of available Content Codings.
.. attribute:: deflate *DEFLATE compression*
.. attribute:: gzip *GZIP compression*
.. attribute:: identity
*no compression*
.. function:: normalize_path_middleware(*, \
append_slash=True, merge_slashes=True)
Middleware that normalizes the path of a request. By normalizing
it means:
- Add 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 all enabled is:
1. *merge_slashes*
2. *append_slash*
3. both *merge_slashes* and *append_slash*
If the path resolves with at least one of those conditions, it will
redirect to the new path.
If *append_slash* is ``True`` append slash when needed. If a resource is
defined with trailing slash and the request comes without it, it will
append it automatically.
If *merge_slashes* is ``True``, merge multiple consecutive slashes in the
path into one.