More docs

docs/web.rst

@@ -100,16 +100,46 @@ The *HTTP method* can be queried later in the request handler using the
 :attr:`Request.method` property.
 
 .. versionadded:: 0.15.2
+
    Support for wildcard *HTTP method* routes.
 
 
+.. _aiohttp-web-resource-and-route:
+
+Resources and Routes
+--------------------
+
+Internally *router* is a list of *resources*.
+
+Resource is an entry in *route table* which corresponds to requested URL.
+
+Resource in turn has at least one *route*.
+
+Route corresponds to handling *HTTP method* by calling *web handler*.
+
+:meth:`UrlDispatcher.add_route` is just a shortcut for pair of
+:meth:`UrlDispatcher.add_resource` and :meth:`Resource.add_route`::
+
+   resource = app.router.add_resource(path, name=name)
+   route = resource.add_route(method, handler)
+   return route
+
+.. seealso::
+
+   :ref:`aiohttp-router-refactoring-021` for more details
+
+.. versionadded:: 0.21.0
+
+   Introduce resources.
+
+
 .. _aiohttp-web-variable-handler:
 
-Variable Routes
-^^^^^^^^^^^^^^^
+Variable Resources
+^^^^^^^^^^^^^^^^^^
 
-Handlers can also be attached to routes with *variable paths*. For instance,
-a route with the path ``'/a/{name}/c'`` would match all incoming requests with
+Resource may have *variable path* also. For instance, a resource with
+the path ``'/a/{name}/c'`` would match all incoming requests with
 paths such as ``'/a/b/c'``, ``'/a/1/c'``, and ``'/a/etc/c'``.
 
 A variable *part* is specified in the form ``{identifier}``, where the
@@ -122,38 +152,38 @@ that *part*. This is done by looking up the ``identifier`` in the
        return web.Response(
            text="Hello, {}".format(request.match_info['name']))
 
-   app.router.add_route('GET', '/{name}', variable_handler)
+   resource = app.router.add_route('/{name}')
+   resource.add_route('GET', variable_handler)
 
 By default, each *part* matches the regular expression ``[^{}/]+``.
 
 You can also specify a custom regex in the form ``{identifier:regex}``::
 
-   app.router.add_route('GET', r'/{name:\d+}', variable_handler)
+   resource = app.router.add_resource(r'/{name:\d+}')
 
 .. versionadded:: 0.13
    Support for custom regexs in variable routes.
 
 
 .. _aiohttp-web-named-routes:
 
-Reverse URL Constructing using Named Routes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Reverse URL Constructing using Named Resources
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Routes can also be given a *name*::
 
-   app.router.add_route('GET', '/root', handler, name='root')
+   resource = app.router.add_resource('/root', name='root')
 
-Which can then be used to access and build a *URL* for that route later (e.g.
+Which can then be used to access and build a *URL* for that resource later (e.g.
 in a :ref:`request handler <aiohttp-web-handler>`)::
 
-   >>> request.app.router['root'].url(query={"a": "b", "c": "d"})
+   >>> request.app.named_resource['root'].url(query={"a": "b", "c": "d"})
    '/root?a=b&c=d'
 
 A more interesting example is building *URLs* for :ref:`variable
-routes <aiohttp-web-variable-handler>`::
+resources <aiohttp-web-variable-handler>`::
 
-   app.router.add_route('GET', r'/{user}/info',
-                        variable_handler, name='user-info')
+   app.router.add_resource(r'/{user}/info', name='user-info')
 
 
 In this case you can also pass in the *parts* of the route::
@@ -228,20 +258,20 @@ registered in application's router::
 Example will process GET and POST requests for */path/to* but raise
 *405 Method not allowed* exception for unimplemented HTTP methods.
 
-Route Views
-^^^^^^^^^^^
+Resource Views
+^^^^^^^^^^^^^^
 
-*All* registered routes in a router can be viewed using the
-:meth:`UrlDispatcher.routes` method::
+*All* registered ressources in a router can be viewed using the
+:meth:`UrlDispatcher.resources` method::
 
-   for route in app.router.routes():
-       print(route)
+   for resource in app.router.resources():
+       print(resource)
 
-Similarly, a *subset* of the routes that were registered with a *name* can be
-viewed using the :meth:`UrlDispatcher.named_routes` method::
+Similarly, a *subset* of the resources that were registered with a *name* can be
+viewed using the :meth:`UrlDispatcher.named_resources` method::
 
-   for name, route in app.router.named_routes().items():
-       print(name, route)
+   for name, resource in app.router.named_resources().items():
+       print(name, resource)
 
 
 
@@ -251,6 +281,11 @@ viewed using the :meth:`UrlDispatcher.named_routes` method::
 .. versionadded:: 0.19
    :meth:`UrlDispatcher.named_routes`
 
+.. deprecated:: 0.21
+
+   Use :meth:`UrlDispatcher.named_resources` /
+   :meth:`UrlDispatcher.resources` instead of
+   :meth:`UrlDispatcher.named_routes` / :meth:`UrlDispatcher.routes`.
 
 Custom Routing Criteria
 -----------------------

docs/web_reference.rst

@@ -1464,6 +1464,29 @@ Resource classes hierarchy::
    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 str path: route path. Should be started with slash (``'/'``).
+
+      :param callable handler: route handler.
+
+      :param coroutine expect_handler: optional *expect* header handler.
+
+      :returns: new :class:`ResourceRoute` instance.
+
+
 .. class:: PlainResource
 
    A new-style resource, inherited from :class:`Resource`.