diff options
| -rw-r--r-- | CHANGES.txt | 12 | ||||
| -rw-r--r-- | docs/api/request.rst | 4 | ||||
| -rw-r--r-- | docs/narr/subrequest.rst | 53 | ||||
| -rw-r--r-- | docs/whatsnew-1.4.rst | 12 | ||||
| -rw-r--r-- | pyramid/router.py | 13 | ||||
| -rw-r--r-- | pyramid/tests/pkgs/subrequestapp/__init__.py | 2 |
6 files changed, 53 insertions, 43 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 6736f6d3e..66ac42136 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -163,8 +163,8 @@ Features - Added the ``pyramid.testing.testConfig`` context manager, which can be used to generate a configurator in a test, e.g. ``with testing.testConfig(...):``. -- Users can now invoke a subrequest from within view code using the - ``request.subrequest`` API. +- Users can now invoke a subrequest from within view code using a new + ``request.invoke_subrequest`` API. Deprecations ------------ @@ -252,6 +252,12 @@ Backwards Incompatibilities * ``registerSettings``, use ``pyramid.config.Configurator.add_settings`` instead. +- In Pyramid 1.3 and previous, the ``__call__`` method of a Response object + was invoked before any finished callbacks were executed. As of this + release, the ``__call__`` method of a Response object is invoked *after* + finished callbacks are executed. This is in support of the + ``request.invoke_subrequest`` feature. + Documentation ------------- @@ -261,7 +267,7 @@ Documentation while running a server. - Added a "Invoking a Subrequest" chapter to the documentation. It describes - how to use the new ``request.subrequest`` API. + how to use the new ``request.invoke_subrequest`` API. Dependencies ------------ diff --git a/docs/api/request.rst b/docs/api/request.rst index 603807abe..1718d0743 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -161,7 +161,7 @@ request, the value of this attribute will be ``None``. See :ref:`matched_route`. - .. method:: subrequest(request, use_tweens=False) + .. method:: invoke_subrequest(request, use_tweens=False) .. warning:: @@ -184,7 +184,7 @@ request) - Adds a ``registry`` attribute (the current Pyramid registry) and a - ``subrequest`` attribute (a callable) to the request object it's + ``invoke_subrequest`` attribute (a callable) to the request object it's handed. - sets request extensions (such as those added via diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst index 4f132f72f..bd50b6053 100644 --- a/docs/narr/subrequest.rst +++ b/docs/narr/subrequest.rst @@ -26,7 +26,7 @@ Here's an example application which uses a subrequest: def view_one(request): subreq = Request.blank('/view_two') - response = request.subrequest(subreq) + response = request.invoke_subrequest(subreq) return response def view_two(request): @@ -45,13 +45,14 @@ Here's an example application which uses a subrequest: 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.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.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. +: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 @@ -66,7 +67,7 @@ adapter will work too: def view_one(request): subreq = Request.blank('/view_two') - response = request.subrequest(subreq) + response = request.invoke_subrequest(subreq) return response def view_two(request): @@ -89,8 +90,8 @@ 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.subrequest` instead of simply importing the -view callable and executing it directly. Note that there's not much +:meth:`pyramid.request.Request.invoke_subrequest` instead of simply importing +the 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 @@ -107,7 +108,7 @@ exception will usually bubble up to the invoking code: def view_one(request): subreq = Request.blank('/view_two') - response = request.subrequest(subreq) + response = request.invoke_subrequest(subreq) return response def view_two(request): @@ -123,13 +124,13 @@ exception will usually bubble up to the invoking code: server = make_server('0.0.0.0', 8080, app) server.serve_forever() -In the above application, the call to ``request.subrequest(subreq)`` will -actually raise a :exc:`ValueError` exception instead of retrieving a "500" -response from the attempted invocation of ``view_two``. +In the above application, the call to ``request.invoke_subrequest(subreq)`` +will actually raise a :exc:`ValueError` exception instead of retrieving a +"500" response from the attempted invocation of ``view_two``. -The :meth:`pyramid.request.Request.subrequest` API accepts two arguments: a -positional argument ``request`` that must be provided, and and ``use_tweens`` -keyword argument that is optional; it defaults to ``False``. +The :meth:`pyramid.request.Request.invoke_subrequest` API accepts two +arguments: a positional argument ``request`` that must be provided, and and +``use_tweens`` keyword argument that is optional; it 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` @@ -138,16 +139,16 @@ instance). If ``use_tweens`` is ``True``, the request will be sent to the ``use_tweens`` is ``False``, the request will be sent to the main router handler, and no tweens will be invoked. It's usually best to not invoke any tweens when executing a subrequest, because the original request will invoke -any tween logic as necessary. The :meth:`pyramid.request.Request.subrequest` -function also: +any tween logic as necessary. The +:meth:`pyramid.request.Request.invoke_subrequest` function also: - 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) -- Adds a ``registry`` attribute and a ``subrequest`` attribute to the request - object it's handed. +- Adds a ``registry`` attribute and a ``invoke_subrequest`` attribute (a + callable) to the request object it's handed. - sets request extensions (such as those added via :meth:`~pyramid.config.Configurator.add_request_method` or @@ -170,8 +171,8 @@ function also: lifetime. It's a poor idea to use the original ``request`` object as an argument to -:meth:`~pyramid.request.Request.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 the it to match the view callable you'd like to be executed during the subrequest. This can be done by adjusting the @@ -181,5 +182,5 @@ massage your new request object into something that will 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.subrequest` API from within a -tween or an event handler as well. +can use the :meth:`~pyramid.request.Request.invoke_subrequest` API from +within a tween or an event handler as well. diff --git a/docs/whatsnew-1.4.rst b/docs/whatsnew-1.4.rst index 70d5f12a7..8e333bf5d 100644 --- a/docs/whatsnew-1.4.rst +++ b/docs/whatsnew-1.4.rst @@ -69,9 +69,9 @@ Subrequest Support ~~~~~~~~~~~~~~~~~~ - Developers may invoke a subrequest by using the - :meth:`pyramid.request.Request.subrequest` API. This allows a developer to - obtain a response from one view callable by issuing a subrequest from within - a different view callable. + :meth:`pyramid.request.Request.invoke_subrequest` API. This allows a + developer to obtain a response from one view callable by issuing a subrequest + from within a different view callable. Minor Feature Additions ----------------------- @@ -230,6 +230,12 @@ Backwards Incompatibilities * ``registerSettings``, use :meth:`pyramid.config.Configurator.add_settings` instead. +- In Pyramid 1.3 and previous, the ``__call__`` method of a Response object + returned by a view was invoked before any finished callbacks were executed. + As of this release, the ``__call__`` method of a Response object is invoked + *after* finished callbacks are executed. This is in support of the + :meth:`pyramid.request.Request.invoke_subrequest` feature. + Deprecations ------------ diff --git a/pyramid/router.py b/pyramid/router.py index 75bf70f07..18624376c 100644 --- a/pyramid/router.py +++ b/pyramid/router.py @@ -162,7 +162,7 @@ class Router(object): return response - def subrequest(self, request, use_tweens=False): + def invoke_subrequest(self, request, use_tweens=False): """ Obtain a response object from the Pyramid application based on information in the ``request`` object provided. The ``request`` @@ -178,8 +178,8 @@ class Router(object): :func:`~pyramid.threadlocal.get_current_registry` work during a request) - - Adds a ``registry`` attribute and a ``subrequest`` attribute to the - request object it's handed. + - Adds a ``registry`` attribute and a ``invoke_subrequest`` attribute + (a callable) to the request object it's handed. - sets request extensions (such as those added via :meth:`~pyramid.config.Configurator.add_request_method` or @@ -211,7 +211,7 @@ class Router(object): manager = self.threadlocal_manager manager.push(threadlocals) request.registry = registry - request.subrequest = self.subrequest + request.invoke_subrequest = self.invoke_subrequest if use_tweens: handle_request = self.handle_request else: @@ -228,9 +228,6 @@ class Router(object): if request.response_callbacks: request._process_response_callbacks(response) - # XXX before subrequest factoring, the below line - # actually invoked Response.__call__, passing it - # the start_response return response finally: @@ -249,6 +246,6 @@ class Router(object): return an iterable. """ request = self.request_factory(environ) - response = self.subrequest(request, use_tweens=True) + response = self.invoke_subrequest(request, use_tweens=True) return response(request.environ, start_response) diff --git a/pyramid/tests/pkgs/subrequestapp/__init__.py b/pyramid/tests/pkgs/subrequestapp/__init__.py index c59993fb7..06a4d9d16 100644 --- a/pyramid/tests/pkgs/subrequestapp/__init__.py +++ b/pyramid/tests/pkgs/subrequestapp/__init__.py @@ -3,7 +3,7 @@ from pyramid.request import Request def view_one(request): subreq = Request.blank('/view_two') - response = request.subrequest(subreq) + response = request.invoke_subrequest(subreq) return response def view_two(request): |