From f3d20e19807bc1a86acccdd74cff10698d249350 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 28 Oct 2015 23:42:12 -0700 Subject: minor grammar, rewrap 79 columns, some .rst syntax fixes, add a header and index entry --- docs/narr/subrequest.rst | 152 ++++++++++++++++++++++++----------------------- 1 file changed, 78 insertions(+), 74 deletions(-) (limited to 'docs/narr/subrequest.rst') diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst index 4b4e99d41..13b00efb6 100644 --- a/docs/narr/subrequest.rst +++ b/docs/narr/subrequest.rst @@ -41,23 +41,22 @@ Here's an example application which uses a subrequest: server = make_server('0.0.0.0', 8080, app) server.serve_forever() -When ``/view_one`` is visted in a browser, the text printed in the browser -pane will be ``This came from view_two``. The ``view_one`` view used the -:meth:`pyramid.request.Request.invoke_subrequest` API to obtain a response -from another view (``view_two``) within the same application when it -executed. It did so by constructing a new request that had a URL that it -knew would match the ``view_two`` view registration, and passed that new -request along to :meth:`pyramid.request.Request.invoke_subrequest`. The -``view_two`` view callable was invoked, and it returned a response. The -``view_one`` view callable then simply returned the response it obtained from -the ``view_two`` view callable. +When ``/view_one`` is visted in a browser, the text printed in the browser pane +will be ``This came from view_two``. The ``view_one`` view used the +:meth:`pyramid.request.Request.invoke_subrequest` API to obtain a response from +another view (``view_two``) within the same application when it executed. It +did so by constructing a new request that had a URL that it knew would match +the ``view_two`` view registration, and passed that new request along to +:meth:`pyramid.request.Request.invoke_subrequest`. The ``view_two`` view +callable was invoked, and it returned a response. The ``view_one`` view +callable then simply returned the response it obtained from the ``view_two`` +view callable. Note that it doesn't matter if the view callable invoked via a subrequest actually returns a *literal* Response object. Any view callable that uses a renderer or which returns an object that can be interpreted by a response adapter when found and invoked via -:meth:`pyramid.request.Request.invoke_subrequest` will return a Response -object: +:meth:`pyramid.request.Request.invoke_subrequest` will return a Response object: .. code-block:: python @@ -83,19 +82,19 @@ object: server = make_server('0.0.0.0', 8080, app) server.serve_forever() -Even though the ``view_two`` view callable returned a string, it was invoked -in such a way that the ``string`` renderer associated with the view -registration that was found turned it into a "real" response object for -consumption by ``view_one``. +Even though the ``view_two`` view callable returned a string, it was invoked in +such a way that the ``string`` renderer associated with the view registration +that was found turned it into a "real" response object for consumption by +``view_one``. Being able to unconditionally obtain a response object by invoking a view callable indirectly is the main advantage to using -:meth:`pyramid.request.Request.invoke_subrequest` instead of simply importing -a view callable and executing it directly. Note that there's not much -advantage to invoking a view using a subrequest if you *can* invoke a view -callable directly. Subrequests are slower and are less convenient if you -actually do want just the literal information returned by a function that -happens to be a view callable. +:meth:`pyramid.request.Request.invoke_subrequest` instead of simply importing a +view callable and executing it directly. Note that there's not much advantage +to invoking a view using a subrequest if you *can* invoke a view callable +directly. Subrequests are slower and are less convenient if you actually do +want just the literal information returned by a function that happens to be a +view callable. Note that, by default, if a view callable invoked by a subrequest raises an exception, the exception will be raised to the caller of @@ -136,15 +135,21 @@ When we run the above code and visit ``/view_one`` in a browser, the ``excview`` :term:`exception view` will *not* be executed. Instead, the call to :meth:`~pyramid.request.Request.invoke_subrequest` will cause a :exc:`ValueError` exception to be raised and a response will never be -generated. We can change this behavior; how to do so is described below in -our discussion of the ``use_tweens`` argument. +generated. We can change this behavior; how to do so is described below in our +discussion of the ``use_tweens`` argument. + +.. index:: + pair: subrequest; use_tweens + +Subrequests with Tweens +----------------------- The :meth:`pyramid.request.Request.invoke_subrequest` API accepts two -arguments: a positional argument ``request`` that must be provided, and -``use_tweens`` keyword argument that is optional; it defaults to ``False``. +arguments: a required positional argument ``request``, and an optional keyword +argument ``use_tweens`` which defaults to ``False``. -The ``request`` object passed to the API must be an object that implements -the Pyramid request interface (such as a :class:`pyramid.request.Request` +The ``request`` object passed to the API must be an object that implements the +Pyramid request interface (such as a :class:`pyramid.request.Request` instance). If ``use_tweens`` is ``True``, the request will be sent to the :term:`tween` in the tween stack closest to the request ingress. If ``use_tweens`` is ``False``, the request will be sent to the main router @@ -153,9 +158,9 @@ handler, and no tweens will be invoked. In the example above, the call to :meth:`~pyramid.request.Request.invoke_subrequest` will always raise an exception. This is because it's using the default value for ``use_tweens``, -which is ``False``. You can pass ``use_tweens=True`` instead to ensure that -it will convert an exception to a Response if an :term:`exception view` is -configured instead of raising the exception. This is because exception views +which is ``False``. Alternatively, you can pass ``use_tweens=True`` to ensure +that it will convert an exception to a Response if an :term:`exception view` is +configured, instead of raising the exception. This is because exception views are called by the exception view :term:`tween` as described in :ref:`exception_views` when any view raises an exception. @@ -199,71 +204,70 @@ attempted invocation of ``view_two``, because the tween which invokes an exception view to generate a response is run, and therefore ``excview`` is executed. -This is one of the major differences between specifying the -``use_tweens=True`` and ``use_tweens=False`` arguments to +This is one of the major differences between specifying the ``use_tweens=True`` +and ``use_tweens=False`` arguments to :meth:`~pyramid.request.Request.invoke_subrequest`. ``use_tweens=True`` may -also imply invoking transaction commit/abort for the logic executed in the -subrequest if you've got ``pyramid_tm`` in the tween list, injecting debug -HTML if you've got ``pyramid_debugtoolbar`` in the tween list, and other +also imply invoking a transaction commit or abort for the logic executed in the +subrequest if you've got ``pyramid_tm`` in the tween list, injecting debug HTML +if you've got ``pyramid_debugtoolbar`` in the tween list, and other tween-related side effects as defined by your particular tween list. The :meth:`~pyramid.request.Request.invoke_subrequest` function also -unconditionally: - -- manages the threadlocal stack so that +unconditionally does the following: + +- It manages the threadlocal stack so that :func:`~pyramid.threadlocal.get_current_request` and - :func:`~pyramid.threadlocal.get_current_registry` work during a request - (they will return the subrequest instead of the original request) + :func:`~pyramid.threadlocal.get_current_registry` work during a request (they + will return the subrequest instead of the original request). -- Adds a ``registry`` attribute and a ``invoke_subrequest`` attribute (a - callable) to the request object it's handed. +- It adds a ``registry`` attribute and an ``invoke_subrequest`` attribute (a + callable) to the request object to which it is handed. -- sets request extensions (such as those added via +- It sets request extensions (such as those added via :meth:`~pyramid.config.Configurator.add_request_method` or :meth:`~pyramid.config.Configurator.set_request_property`) on the subrequest - object passed as ``request`` + object passed as ``request``. -- causes a :class:`~pyramid.events.NewRequest` event to be sent at the +- It causes a :class:`~pyramid.events.NewRequest` event to be sent at the beginning of request processing. -- causes a :class:`~pyramid.events.ContextFound` event to be sent when a +- It causes a :class:`~pyramid.events.ContextFound` event to be sent when a context resource is found. -- Ensures that the user implied by the request passed has the necessary - authorization to invoke view callable before calling it. +- It ensures that the user implied by the request passed in has the necessary + authorization to invoke the view callable before calling it. -- Calls any :term:`response callback` functions defined within the subrequest's - lifetime if a response is obtained from the Pyramid application. +- It calls any :term:`response callback` functions defined within the + subrequest's lifetime if a response is obtained from the Pyramid application. -- causes a :class:`~pyramid.events.NewResponse` event to be sent if a response - is obtained. +- It causes a :class:`~pyramid.events.NewResponse` event to be sent if a + response is obtained. -- Calls any :term:`finished callback` functions defined within the subrequest's - lifetime. +- It calls any :term:`finished callback` functions defined within the + subrequest's lifetime. -The invocation of a subrequest has more or less exactly the same effect as -the invocation of a request received by the Pyramid router from a web client +The invocation of a subrequest has more or less exactly the same effect as the +invocation of a request received by the :app:`Pyramid` router from a web client when ``use_tweens=True``. When ``use_tweens=False``, the tweens are skipped but all the other steps take place. It's a poor idea to use the original ``request`` object as an argument to -:meth:`~pyramid.request.Request.invoke_subrequest`. You should construct a -new request instead as demonstrated in the above example, using +:meth:`~pyramid.request.Request.invoke_subrequest`. You should construct a new +request instead as demonstrated in the above example, using :meth:`pyramid.request.Request.blank`. Once you've constructed a request -object, you'll need to massage it to match the view callable you'd like -to be executed during the subrequest. This can be done by adjusting the +object, you'll need to massage it to match the view callable that you'd like to +be executed during the subrequest. This can be done by adjusting the subrequest's URL, its headers, its request method, and other attributes. The documentation for :class:`pyramid.request.Request` exposes the methods you -should call and attributes you should set on the request you create to -massage it into something that will actually match the view you'd like to -call via a subrequest. - -We've demonstrated use of a subrequest from within a view callable, but you -can use the :meth:`~pyramid.request.Request.invoke_subrequest` API from -within a tween or an event handler as well. It's usually a poor idea to -invoke :meth:`~pyramid.request.Request.invoke_subrequest` from within a -tween, because tweens already by definition have access to a function that -will cause a subrequest (they are passed a ``handle`` function), but you can -do it. It's fine to invoke -:meth:`~pyramid.request.Request.invoke_subrequest` from within an event -handler, however. +should call and attributes you should set on the request that you create, then +massage it into something that will actually match the view you'd like to call +via a subrequest. + +We've demonstrated use of a subrequest from within a view callable, but you can +use the :meth:`~pyramid.request.Request.invoke_subrequest` API from within a +tween or an event handler as well. Even though you can do it, it's usually a +poor idea to invoke :meth:`~pyramid.request.Request.invoke_subrequest` from +within a tween, because tweens already, by definition, have access to a +function that will cause a subrequest (they are passed a ``handle`` function). +It's fine to invoke :meth:`~pyramid.request.Request.invoke_subrequest` from +within an event handler, however. -- cgit v1.2.3