From a7e625785f65c41e5a6dc017b31bd0d74821474e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 31 May 2011 14:40:05 -0400 Subject: the canonical import location for HTTP exceptions/responses is now pyramid.response --- docs/narr/router.rst | 53 +++++++++++++++++++++++++--------------------------- 1 file changed, 25 insertions(+), 28 deletions(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 11f84d4ea..44fa9835b 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -77,40 +77,37 @@ processing? #. A :class:`~pyramid.events.ContextFound` :term:`event` is sent to any subscribers. -#. :app:`Pyramid` looks up a :term:`view` callable using the - context, the request, and the view name. If a view callable - doesn't exist for this combination of objects (based on the type of - the context, the type of the request, and the value of the view - name, and any :term:`predicate` attributes applied to the view - configuration), :app:`Pyramid` raises a - :class:`~pyramid.exceptions.NotFound` exception, which is meant - to be caught by a surrounding exception handler. +#. :app:`Pyramid` looks up a :term:`view` callable using the context, the + request, and the view name. If a view callable doesn't exist for this + combination of objects (based on the type of the context, the type of the + request, and the value of the view name, and any :term:`predicate` + attributes applied to the view configuration), :app:`Pyramid` raises a + :class:`~pyramid.response.HTTPNotFound` exception, which is meant to be + caught by a surrounding exception handler. #. If a view callable was found, :app:`Pyramid` attempts to call the view function. -#. If an :term:`authorization policy` is in use, and the view was - protected by a :term:`permission`, :app:`Pyramid` passes the - context, the request, and the view_name to a function which - determines whether the view 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 it returns - ``True``, :app:`Pyramid` calls the view callable to obtain a - response. If it returns ``False``, it raises a - :class:`~pyramid.exceptions.Forbidden` exception, which is meant - to be called by a surrounding exception handler. +#. If an :term:`authorization policy` is in use, and the view was protected + by a :term:`permission`, :app:`Pyramid` passes the context, the request, + and the view_name to a function which determines whether the view 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 it returns ``True``, :app:`Pyramid` calls the view callable + to obtain a response. If it returns ``False``, it raises a + :class:`~pyramid.response.HTTPForbidden` exception, which is meant to be + called by a surrounding exception handler. #. If any exception was raised within a :term:`root factory`, by - :term:`traversal`, by a :term:`view callable` or by - :app:`Pyramid` itself (such as when it raises - :class:`~pyramid.exceptions.NotFound` or - :class:`~pyramid.exceptions.Forbidden`), 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. + :term:`traversal`, by a :term:`view callable` or by :app:`Pyramid` itself + (such as when it raises :class:`~pyramid.response.HTTPNotFound` or + :class:`~pyramid.response.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 -- cgit v1.2.3 From 99edc51a3b05309c7f5d98ff96289ec51b1d7660 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 11 Jun 2011 05:35:27 -0400 Subject: - Pyramid now expects Response objects to have a __call__ method which implements the WSGI application interface instead of the three webob attrs status, headerlist and app_iter. Backwards compatibility exists for code which returns response objects that do not have a __call__. - pyramid.response.Response is no longer an exception (and therefore cannot be raised in order to generate a response). - Changed my mind about moving stuff from pyramid.httpexceptions to pyramid.response. The stuff I moved over has been moved back to pyramid.httpexceptions. --- docs/narr/router.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 44fa9835b..30d54767e 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -82,8 +82,8 @@ processing? combination of objects (based on the type of the context, the type of the request, and the value of the view name, and any :term:`predicate` attributes applied to the view configuration), :app:`Pyramid` raises a - :class:`~pyramid.response.HTTPNotFound` exception, which is meant to be - caught by a surrounding exception handler. + :class:`~pyramid.httpexceptions.HTTPNotFound` exception, which is meant to + be caught by a surrounding :term:`exception view`. #. If a view callable was found, :app:`Pyramid` attempts to call the view function. @@ -95,13 +95,13 @@ processing? information in the request and security information attached to the context. If it returns ``True``, :app:`Pyramid` calls the view callable to obtain a response. If it returns ``False``, it raises a - :class:`~pyramid.response.HTTPForbidden` exception, which is meant to be - called by a surrounding exception handler. + :class:`~pyramid.httpexceptions.HTTPForbidden` exception, which is meant + to be called by a surrounding :term:`exception view`. #. If any exception was raised within a :term:`root factory`, by :term:`traversal`, by a :term:`view callable` or by :app:`Pyramid` itself - (such as when it raises :class:`~pyramid.response.HTTPNotFound` or - :class:`~pyramid.response.HTTPForbidden`), the router catches the + (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 -- cgit v1.2.3 From d868fff7597c5a05acd1f5c024fc45dde9880413 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 13 Jun 2011 06:17:00 -0400 Subject: - Remove IResponder abstraction in favor of more general IResponse abstraction. - It is now possible to return an arbitrary object from a Pyramid view callable even if a renderer is not used, as long as a suitable adapter to ``pyramid.interfaces.IResponse`` is registered for the type of the returned object. See the section in the Hooks chapter of the documentation entitled "Changing How Pyramid Treats View Responses". - The Pyramid router now, by default, expects response objects returned from view callables to implement the ``pyramid.interfaces.IResponse`` interface. Unlike the Pyramid 1.0 version of this interface, objects which implement IResponse now must define a ``__call__`` method that accepts ``environ`` and ``start_response``, and which returns an ``app_iter`` iterable, among other things. Previously, it was possible to return any object which had the three WebOb ``app_iter``, ``headerlist``, and ``status`` attributes as a response, so this is a backwards incompatibility. It is possible to get backwards compatibility back by registering an adapter to IResponse from the type of object you're now returning from view callables. See the section in the Hooks chapter of the documentation entitled "Changing How Pyramid Treats View Responses". - The ``pyramid.interfaces.IResponse`` interface is now much more extensive. Previously it defined only ``app_iter``, ``status`` and ``headerlist``; now it is basically intended to directly mirror the ``webob.Response`` API, which has many methods and attributes. - Documentation changes to support above. --- docs/narr/router.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 30d54767e..0812f7ec7 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -115,9 +115,9 @@ processing? 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 ``app_iter``, ``status``, and - ``headerlist`` attributes are then used to generate a WSGI response. The - response is sent back to the upstream WSGI server. + subscribers. The response object's ``__call__`` method is then used to + generate a WSGI response. The response is sent back to the upstream WSGI + server. #. :app:`Pyramid` will attempt to execute any :term:`finished callback` functions attached via -- cgit v1.2.3 From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/router.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 0812f7ec7..d08261b17 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -2,6 +2,7 @@ single: request processing single: request single: router + single: request lifecycle .. _router_chapter: -- cgit v1.2.3 From 99520ee274400c246ab073f598dff32acc256fa9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 10 Dec 2011 22:50:58 -0500 Subject: update router document --- docs/narr/router.rst | 141 ++++++++++++++++++++++++--------------------------- 1 file changed, 65 insertions(+), 76 deletions(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index d08261b17..b78362066 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -9,74 +9,67 @@ Request Processing ================== -Once a :app:`Pyramid` application is up and running, it is ready to -accept requests and return responses. +Once a :app:`Pyramid` application is up and running, it is ready to accept +requests and return responses. What happens from the time a :term:`WSGI` +request enters a :app:`Pyramid` application through to the point that +:app:`Pyramid` hands off a response back to WSGI for upstream processing? -What happens from the time a :term:`WSGI` request enters a -:app:`Pyramid` application through to the point that -:app:`Pyramid` hands off a response back to WSGI for upstream -processing? +#. A user initiates a request from his browser to the hostname and port + number of the WSGI server used by the :app:`Pyramid` application. -#. A user initiates a request from his browser to the hostname and - port number of the WSGI server used by the :app:`Pyramid` - application. - -#. The WSGI server used by the :app:`Pyramid` application passes - the WSGI environment to the ``__call__`` method of the - :app:`Pyramid` :term:`router` object. +#. The WSGI server used by the :app:`Pyramid` application passes the WSGI + environment to the ``__call__`` method of the :app:`Pyramid` + :term:`router` object. #. A :term:`request` object is created based on the WSGI environment. -#. The :term:`application registry` and the :term:`request` object - created in the last step are pushed on to the :term:`thread local` - stack that :app:`Pyramid` uses to allow the functions named +#. The :term:`application registry` and the :term:`request` object created in + the last step are pushed on to the :term:`thread local` stack that + :app:`Pyramid` uses to allow the functions named :func:`~pyramid.threadlocal.get_current_request` and :func:`~pyramid.threadlocal.get_current_registry` to work. #. 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 route matches, the request is mutated; a ``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, 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 a ``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 subobjects) to find a :term:`context`. If the root - object has no ``__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 e.g. ``request.context`` within - :term:`view` code. - -#. A :class:`~pyramid.events.ContextFound` :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 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, 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 a ``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 + subobjects) to find a :term:`context`. If the root object has no + ``__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 e.g. ``request.context`` within :term:`view` code. + +#. A :class:`~pyramid.events.ContextFound` :term:`event` is sent to any + subscribers. #. :app:`Pyramid` looks up a :term:`view` callable using the context, the request, and the view name. If a view callable doesn't exist for this @@ -86,20 +79,17 @@ processing? :class:`~pyramid.httpexceptions.HTTPNotFound` exception, which is meant to be caught by a surrounding :term:`exception view`. -#. If a view callable was found, :app:`Pyramid` attempts to call - the view function. - -#. If an :term:`authorization policy` is in use, and the view was protected - by a :term:`permission`, :app:`Pyramid` passes the context, the request, - and the view_name to a function which determines whether the view 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 it returns ``True``, :app:`Pyramid` calls the view callable - to obtain a response. If it returns ``False``, it raises a - :class:`~pyramid.httpexceptions.HTTPForbidden` exception, which is meant - to be called by a surrounding :term:`exception view`. - -#. If any exception was raised within a :term:`root factory`, by +#. If a view callable was found, :app:`Pyramid` attempts to call it. If an + :term:`authorization policy` is in use, and the view configuration is + 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, + :app:`Pyramid` raises a :class:`~pyramid.httpexceptions.HTTPForbidden` + exception. + +#. If any exception is raised within a :term:`root factory`, by :term:`traversal`, by a :term:`view callable` or by :app:`Pyramid` itself (such as when it raises :class:`~pyramid.httpexceptions.HTTPNotFound` or :class:`~pyramid.httpexceptions.HTTPForbidden`), the router catches the @@ -128,9 +118,8 @@ processing? .. image:: router.png -This is a very high-level overview that leaves out various details. -For more detail about subsystems invoked by the :app:`Pyramid` router -such as traversal, URL dispatch, views, and event processing, see -:ref:`urldispatch_chapter`, :ref:`views_chapter`, and -:ref:`events_chapter`. +This is a very high-level overview that leaves out various details. For more +detail about subsystems invoked by the :app:`Pyramid` router such as +traversal, URL dispatch, views, and event processing, see +:ref:`urldispatch_chapter`, :ref:`views_chapter`, and :ref:`events_chapter`. -- cgit v1.2.3 From 2605e0cc2ad089d4f25c00a5f2c4d99ffbfa4567 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 22:57:05 +0200 Subject: grammar fixes --- docs/narr/router.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index b78362066..ac3deefdc 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -46,7 +46,7 @@ request enters a :app:`Pyramid` application through to the point that :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 a ``factory`` argument, this factory is used to generate the + 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 -- cgit v1.2.3 From 370862eb748f74dacee6b2bb1a5a2e35f865018a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 22 Nov 2014 23:31:50 -0800 Subject: add request processing diagram to docs/narr/router.rst --- docs/narr/router.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index ac3deefdc..745c2faa1 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -9,6 +9,9 @@ Request Processing ================== +.. image:: ../_static/pyramid_router.svg + :alt: Request Processing + Once a :app:`Pyramid` application is up and running, it is ready to accept requests and return responses. What happens from the time a :term:`WSGI` request enters a :app:`Pyramid` application through to the point that -- cgit v1.2.3 From 3408269bd291b771efef8e54f039038fc5b59a26 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Dec 2014 13:40:39 -0800 Subject: - rename pyramid_router.svg to pyramid_request_processing.svg to be consistent with its content - add source files for future modifications --- docs/narr/router.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 745c2faa1..e82b66801 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -9,7 +9,7 @@ Request Processing ================== -.. image:: ../_static/pyramid_router.svg +.. image:: ../_static/pyramid_request_processing.svg :alt: Request Processing Once a :app:`Pyramid` application is up and running, it is ready to accept -- cgit v1.2.3 From 29e7a7d80149e84b844b68f093a7676ba9e400ee Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Dec 2014 13:45:01 -0800 Subject: replace router.png with pyramid_router.svg and make design consistent --- docs/narr/router.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index e82b66801..693217a6b 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -119,7 +119,8 @@ request enters a :app:`Pyramid` application through to the point that #. The :term:`thread local` stack is popped. -.. image:: router.png +.. image:: ../_static/pyramid_router.svg + :alt: Pyramid Router This is a very high-level overview that leaves out various details. For more detail about subsystems invoked by the :app:`Pyramid` router such as -- cgit v1.2.3 From 8c54a34d5d3211537b8705b04ae8662274641828 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 26 Dec 2014 02:32:58 -0800 Subject: - adding back .png file because PDF cannot include and build SVG files. Also renamed images to use a 'imagename.*' wildcard so that the correct format is chosen. See http://stackoverflow.com/questions/6473660/using-sphinx-docs-how-can-i-specify-png-image-formats-for-html-builds-and-pdf-im --- docs/narr/router.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 693217a6b..6f90c70cc 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -9,7 +9,7 @@ Request Processing ================== -.. image:: ../_static/pyramid_request_processing.svg +.. image:: ../_static/pyramid_request_processing.* :alt: Request Processing Once a :app:`Pyramid` application is up and running, it is ready to accept @@ -119,7 +119,7 @@ request enters a :app:`Pyramid` application through to the point that #. The :term:`thread local` stack is popped. -.. image:: ../_static/pyramid_router.svg +.. image:: ../_static/pyramid_router.* :alt: Pyramid Router This is a very high-level overview that leaves out various details. For more -- cgit v1.2.3 From c2913465ba64532b05d77508aa8a847c9e1af8d9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 5 Oct 2015 04:20:46 -0700 Subject: - neutral gender, grammar, rewrapping --- docs/narr/router.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index 6f90c70cc..7037afcec 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -17,12 +17,12 @@ requests and return responses. What happens from the time a :term:`WSGI` request enters a :app:`Pyramid` application through to the point that :app:`Pyramid` hands off a response back to WSGI for upstream processing? -#. A user initiates a request from his browser to the hostname and port +#. A user initiates a request from their browser to the hostname and port number of the WSGI server used by the :app:`Pyramid` application. #. The WSGI server used by the :app:`Pyramid` application passes the WSGI - environment to the ``__call__`` method of the :app:`Pyramid` - :term:`router` object. + environment to the ``__call__`` method of the :app:`Pyramid` :term:`router` + object. #. A :term:`request` object is created based on the WSGI environment. @@ -45,7 +45,7 @@ request enters a :app:`Pyramid` application through to the point that #. 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, the latter contains the + 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 @@ -69,7 +69,7 @@ request enters a :app:`Pyramid` application through to the point that #. 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 e.g. ``request.context`` within :term:`view` code. + accessed via, for example, ``request.context`` within :term:`view` code. #. A :class:`~pyramid.events.ContextFound` :term:`event` is sent to any subscribers. @@ -93,7 +93,7 @@ request enters a :app:`Pyramid` application through to the point that exception. #. If any exception is raised within a :term:`root factory`, by - :term:`traversal`, by a :term:`view callable` or by :app:`Pyramid` itself + :term:`traversal`, by a :term:`view callable`, or by :app:`Pyramid` itself (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. @@ -113,8 +113,8 @@ request enters a :app:`Pyramid` application through to the point that generate a WSGI response. The response is sent back to the upstream WSGI server. -#. :app:`Pyramid` will attempt to execute any :term:`finished - callback` functions attached via +#. :app:`Pyramid` will attempt to execute any :term:`finished callback` + functions attached via :meth:`~pyramid.request.Request.add_finished_callback`. #. The :term:`thread local` stack is popped. @@ -123,7 +123,6 @@ request enters a :app:`Pyramid` application through to the point that :alt: Pyramid Router This is a very high-level overview that leaves out various details. For more -detail about subsystems invoked by the :app:`Pyramid` router such as +detail about subsystems invoked by the :app:`Pyramid` router, such as traversal, URL dispatch, views, and event processing, see :ref:`urldispatch_chapter`, :ref:`views_chapter`, and :ref:`events_chapter`. - -- cgit v1.2.3 From abbe5040cf337c9224d356e6c0d637a6e995b6b7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 9 Oct 2015 00:21:09 -0700 Subject: wrap 79 cols (cherry picked from commit 703b958) --- docs/narr/router.rst | 64 +++++++++++++++++++++++++--------------------------- 1 file changed, 31 insertions(+), 33 deletions(-) (limited to 'docs/narr/router.rst') 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 -- cgit v1.2.3 From 5b918737fb361584d820893fc82c6b898ae1fc69 Mon Sep 17 00:00:00 2001 From: Bert JW Regeer Date: Sun, 10 Apr 2016 22:18:21 -0600 Subject: Update router documentation --- docs/narr/router.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index e02142e6e..d4c0cc885 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -46,16 +46,22 @@ request enters a :app:`Pyramid` application through to the point that 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: + matched. + + A :class:`~pyramid.events.BeforeTraversal` :term:`event` is sent to any + subscribers. + + 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 root object after a :class:`~pyramid.events.BeforeTraversal` + :term:`event` is sent to any subscribers. 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 -- cgit v1.2.3 From 0da7b0de590b835d6d7df361394b8bf70797f566 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 11 Apr 2016 13:29:50 -0700 Subject: - upgrade `BeforeTraversal` event in router.rst --- docs/narr/router.rst | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) (limited to 'docs/narr/router.rst') diff --git a/docs/narr/router.rst b/docs/narr/router.rst index d4c0cc885..e45e6f4a8 100644 --- a/docs/narr/router.rst +++ b/docs/narr/router.rst @@ -41,27 +41,26 @@ request enters a :app:`Pyramid` application through to the point that 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 +#. If any route matches, the route mapper adds the attributes ``matchdict`` + and ``matched_route`` 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. - - A :class:`~pyramid.events.BeforeTraversal` :term:`event` is sent to any + +#. A :class:`~pyramid.events.BeforeTraversal` :term:`event` is sent to any subscribers. - 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. +#. Continuing, if any route matches, the root object associated with the found + route is generated. If the :term:`route configuration` which matched has an + associated ``factory`` argument, then 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 + However, if no route matches, and if a ``root_factory`` argument was passed to the :term:`Configurator` constructor, that callable is used to generate - the root object after a :class:`~pyramid.events.BeforeTraversal` - :term:`event` is sent to any subscribers. If the ``root_factory`` argument - passed to the Configurator constructor was ``None``, a default root factory - is used to generate a root object. + 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 -- cgit v1.2.3