diff options
| author | Steve Piercy <web@stevepiercy.com> | 2015-10-09 00:21:09 -0700 |
|---|---|---|
| committer | Steve Piercy <web@stevepiercy.com> | 2015-10-09 00:25:59 -0700 |
| commit | abbe5040cf337c9224d356e6c0d637a6e995b6b7 (patch) | |
| tree | 4ca33a92ead85f9dd1b8bb0ffa71473fdd763c41 | |
| parent | 1ca86fb93bb8cbf7814718315d903b162e04f02e (diff) | |
| download | pyramid-abbe5040cf337c9224d356e6c0d637a6e995b6b7.tar.gz pyramid-abbe5040cf337c9224d356e6c0d637a6e995b6b7.tar.bz2 pyramid-abbe5040cf337c9224d356e6c0d637a6e995b6b7.zip | |
wrap 79 cols
(cherry picked from commit 703b958)
| -rw-r--r-- | docs/narr/router.rst | 64 |
1 files changed, 31 insertions, 33 deletions
diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 7037afcec..e02142e6e 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -35,41 +35,40 @@ request enters a :app:`Pyramid` application through to the point that #. A :class:`~pyramid.events.NewRequest` :term:`event` is sent to any subscribers. -#. If any :term:`route` has been defined within application configuration, - the :app:`Pyramid` :term:`router` calls a :term:`URL dispatch` "route - mapper." The job of the mapper is to examine the request to determine - whether any user-defined :term:`route` matches the current WSGI - environment. The :term:`router` passes the request as an argument to the - mapper. +#. If any :term:`route` has been defined within application configuration, the + :app:`Pyramid` :term:`router` calls a :term:`URL dispatch` "route mapper." + The job of the mapper is to examine the request to determine whether any + user-defined :term:`route` matches the current WSGI environment. The + :term:`router` passes the request as an argument to the mapper. #. If any route matches, the route mapper adds attributes to the request: ``matchdict`` and ``matched_route`` attributes are added to the request object. The former contains a dictionary representing the matched dynamic elements of the request's ``PATH_INFO`` value, and the latter contains the :class:`~pyramid.interfaces.IRoute` object representing the route which - matched. The root object associated with the route found is also - generated: if the :term:`route configuration` which matched has an - associated ``factory`` argument, this factory is used to generate the - root object, otherwise a default :term:`root factory` is used. - -#. If a route match was *not* found, and a ``root_factory`` argument was - passed to the :term:`Configurator` constructor, that callable is used to - generate the root object. If the ``root_factory`` argument passed to the + matched. The root object associated with the route found is also generated: + if the :term:`route configuration` which matched has an associated + ``factory`` argument, this factory is used to generate the root object, + otherwise a default :term:`root factory` is used. + +#. If a route match was *not* found, and a ``root_factory`` argument was passed + to the :term:`Configurator` constructor, that callable is used to generate + the root object. If the ``root_factory`` argument passed to the Configurator constructor was ``None``, a default root factory is used to generate a root object. -#. The :app:`Pyramid` router calls a "traverser" function with the root - object and the request. The traverser function attempts to traverse the - root object (using any existing ``__getitem__`` on the root object and +#. The :app:`Pyramid` router calls a "traverser" function with the root object + and the request. The traverser function attempts to traverse the root + object (using any existing ``__getitem__`` on the root object and subobjects) to find a :term:`context`. If the root object has no - ``__getitem__`` method, the root itself is assumed to be the context. The + ``__getitem__`` method, the root itself is assumed to be the context. The exact traversal algorithm is described in :ref:`traversal_chapter`. The traverser function returns a dictionary, which contains a :term:`context` and a :term:`view name` as well as other ancillary information. #. The request is decorated with various names returned from the traverser - (such as ``context``, ``view_name``, and so forth), so they can be - accessed via, for example, ``request.context`` within :term:`view` code. + (such as ``context``, ``view_name``, and so forth), so they can be accessed + via, for example, ``request.context`` within :term:`view` code. #. A :class:`~pyramid.events.ContextFound` :term:`event` is sent to any subscribers. @@ -87,8 +86,8 @@ request enters a :app:`Pyramid` application through to the point that protected by a :term:`permission`, :app:`Pyramid` determines whether the view callable being asked for can be executed by the requesting user based on credential information in the request and security information attached - to the context. If the view execution is allowed, :app:`Pyramid` calls - the view callable to obtain a response. If view execution is forbidden, + to the context. If the view execution is allowed, :app:`Pyramid` calls the + view callable to obtain a response. If view execution is forbidden, :app:`Pyramid` raises a :class:`~pyramid.httpexceptions.HTTPForbidden` exception. @@ -97,17 +96,16 @@ request enters a :app:`Pyramid` application through to the point that (such as when it raises :class:`~pyramid.httpexceptions.HTTPNotFound` or :class:`~pyramid.httpexceptions.HTTPForbidden`), the router catches the exception, and attaches it to the request as the ``exception`` attribute. - It then attempts to find a :term:`exception view` for the exception that - was caught. If it finds an exception view callable, that callable is - called, and is presumed to generate a response. If an :term:`exception - view` that matches the exception cannot be found, the exception is - reraised. - -#. The following steps occur only when a :term:`response` could be - successfully generated by a normal :term:`view callable` or an - :term:`exception view` callable. :app:`Pyramid` will attempt to execute - any :term:`response callback` functions attached via - :meth:`~pyramid.request.Request.add_response_callback`. A + It then attempts to find a :term:`exception view` for the exception that was + caught. If it finds an exception view callable, that callable is called, + and is presumed to generate a response. If an :term:`exception view` that + matches the exception cannot be found, the exception is reraised. + +#. The following steps occur only when a :term:`response` could be successfully + generated by a normal :term:`view callable` or an :term:`exception view` + callable. :app:`Pyramid` will attempt to execute any :term:`response + callback` functions attached via + :meth:`~pyramid.request.Request.add_response_callback`. A :class:`~pyramid.events.NewResponse` :term:`event` is then sent to any subscribers. The response object's ``__call__`` method is then used to generate a WSGI response. The response is sent back to the upstream WSGI |
