diff options
Diffstat (limited to 'docs/api')
| -rw-r--r-- | docs/api/request.rst | 43 |
1 files changed, 43 insertions, 0 deletions
diff --git a/docs/api/request.rst b/docs/api/request.rst index 1112ea069..5e52cfd50 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -161,6 +161,49 @@ request, the value of this attribute will be ``None``. See :ref:`matched_route`. + .. method:: subrequest(request, use_tweens=False) + + Obtain a response object from the Pyramid application based on + information in the ``request`` object provided. The ``request`` object + 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 handler, and no tweens will + be invoked. This isn't *actually* a method of the Request object; it's + a callable added when the Pyramid router is invoked, or when a + subrequest is invoked. This 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) + + - Adds a ``registry`` attribute (the current Pyramid registry) and a + ``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 + :meth:`~pyramid.config.Configurator.set_request_property`) on the + request it's passed. + + - causes a :class:`~pyramid.event.NewRequest` event to be sent at the + beginning of request processing. + + - causes a :class:`~pyramid.event.ContextFound` event to be sent + when a context resource is found. + + - causes a :class:`~pyramid.event.NewResponse` event to be sent when + the Pyramid application returns a response. + + - Calls any :term:`response callback` functions defined within the + request's lifetime if a response is obtained from the Pyramid + application. + + - Calls any :term:`finished callback` functions defined within the + request's lifetime. + .. automethod:: add_response_callback .. automethod:: add_finished_callback |