diff options
Diffstat (limited to 'docs/api/request.rst')
| -rw-r--r-- | docs/api/request.rst | 232 |
1 files changed, 211 insertions, 21 deletions
diff --git a/docs/api/request.rst b/docs/api/request.rst index 8cb424658..52bf50078 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -8,6 +8,13 @@ .. autoclass:: Request :members: :inherited-members: + :exclude-members: add_response_callback, add_finished_callback, + route_url, route_path, current_route_url, + current_route_path, static_url, static_path, + model_url, resource_url, resource_path, set_property, + effective_principals, authenticated_userid, + unauthenticated_userid, has_permission, + invoke_exception_view .. attribute:: context @@ -85,6 +92,17 @@ of ``request.exception`` will be ``None`` within response and finished callbacks. + .. attribute:: exc_info + + If an exception was raised by a :term:`root factory` or a :term:`view + callable`, or at various other points where :app:`Pyramid` executes + user-defined code during the processing of a request, result of + ``sys.exc_info()`` will be available as the ``exc_info`` attribute of + the request within a :term:`exception view`, a :term:`response callback` + or a :term:`finished callback`. If no exception occurred, the value of + ``request.exc_info`` will be ``None`` within response and finished + callbacks. + .. attribute:: response This attribute is actually a "reified" property which returns an @@ -107,7 +125,9 @@ return {'text':'Value that will be used by the renderer'} Mutations to this response object will be preserved in the response sent - to the client after rendering. + to the client after rendering. For more information about using + ``request.response`` in conjunction with a renderer, see + :ref:`request_response_attr`. Non-renderer code can also make use of request.response instead of creating a response "by hand". For example, in view code:: @@ -128,10 +148,6 @@ ``request.session`` attribute will cause a :class:`pyramid.exceptions.ConfigurationError` to be raised. - .. attribute:: tmpl_context - - The template context for Pylons-style applications. - .. attribute:: matchdict If a :term:`route` has matched during this request, this attribute will @@ -143,11 +159,111 @@ .. attribute:: matched_route If a :term:`route` has matched during this request, this attribute will - be an obect representing the route matched by the URL pattern + be an object representing the route matched by the URL pattern associated with the route. If a route has not matched during this request, the value of this attribute will be ``None``. See :ref:`matched_route`. + .. attribute:: authenticated_userid + + .. versionadded:: 1.5 + + A property which returns the :term:`userid` of the currently + authenticated user or ``None`` if there is no :term:`authentication + policy` in effect or there is no currently authenticated user. This + differs from :attr:`~pyramid.request.Request.unauthenticated_userid`, + because the effective authentication policy will have ensured that a + record associated with the :term:`userid` exists in persistent storage; + if it has not, this value will be ``None``. + + .. attribute:: unauthenticated_userid + + .. versionadded:: 1.5 + + A property which returns a value which represents the *claimed* (not + verified) :term:`userid` of the credentials present in the + request. ``None`` if there is no :term:`authentication policy` in effect + or there is no user data associated with the current request. This + differs from :attr:`~pyramid.request.Request.authenticated_userid`, + because the effective authentication policy will not ensure that a + record associated with the :term:`userid` exists in persistent storage. + Even if the :term:`userid` does not exist in persistent storage, this + value will be the value of the :term:`userid` *claimed* by the request + data. + + .. attribute:: effective_principals + + .. versionadded:: 1.5 + + A property which returns the list of 'effective' :term:`principal` + identifiers for this request. This list typically includes the + :term:`userid` of the currently authenticated user if a user is + currently authenticated, but this depends on the + :term:`authentication policy` in effect. If no :term:`authentication + policy` is in effect, this will return a sequence containing only the + :attr:`pyramid.security.Everyone` principal. + + .. method:: invoke_subrequest(request, use_tweens=False) + + .. versionadded:: 1.4a1 + + 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 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 + ``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 + :meth:`~pyramid.config.Configurator.set_request_property`) on the + request it's passed. + + - 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 context resource is found. + + - Ensures that the user implied by the request passed has the necessary + authorization to invoke view callable before calling it. + + - Calls any :term:`response callback` functions defined within the + request'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. + + - Calls any :term:`finished callback` functions defined within the + request's lifetime. + + ``invoke_subrequest`` 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 means that it's not available for use on a + request provided by e.g. the ``pshell`` environment. + + .. seealso:: + + See also :ref:`subrequest_chapter`. + + .. automethod:: invoke_exception_view + + .. automethod:: has_permission + .. automethod:: add_response_callback .. automethod:: add_finished_callback @@ -156,26 +272,99 @@ .. automethod:: route_path - .. automethod:: resource_url + .. automethod:: current_route_url + + .. automethod:: current_route_path .. automethod:: static_url - .. attribute:: response_* + .. automethod:: static_path + + .. automethod:: resource_url + + .. automethod:: resource_path + + .. attribute:: json_body + + This property will return the JSON-decoded variant of the request + body. If the request body is not well-formed JSON, or there is no + body associated with this request, this property will raise an + exception. + + .. seealso:: + + See also :ref:`request_json_body`. + + .. method:: set_property(callable, name=None, reify=False) + + Add a callable or a property descriptor to the request instance. + + Properties, unlike attributes, are lazily evaluated by executing + an underlying callable when accessed. They can be useful for + adding features to an object without any cost if those features + go unused. + + A property may also be reified via the + :class:`pyramid.decorator.reify` decorator by setting + ``reify=True``, allowing the result of the evaluation to be + cached. Thus the value of the property is only computed once for + the lifetime of the object. + + ``callable`` can either be a callable that accepts the request as + its single positional parameter, or it can be a property + descriptor. + + If the ``callable`` is a property descriptor a ``ValueError`` + will be raised if ``name`` is ``None`` or ``reify`` is ``True``. + + If ``name`` is None, the name of the property will be computed + from the name of the ``callable``. + + .. code-block:: python + :linenos: + + def _connect(request): + conn = request.registry.dbsession() + def cleanup(request): + # since version 1.5, request.exception is no + # longer eagerly cleared + if request.exception is not None: + conn.rollback() + else: + conn.commit() + conn.close() + request.add_finished_callback(cleanup) + return conn + + @subscriber(NewRequest) + def new_request(event): + request = event.request + request.set_property(_connect, 'db', reify=True) + + The subscriber doesn't actually connect to the database, it just + provides the API which, when accessed via ``request.db``, will + create the connection. Thanks to reify, only one connection is + made per-request even if ``request.db`` is accessed many times. + + This pattern provides a way to augment the ``request`` object + without having to subclass it, which can be useful for extension + authors. + + .. versionadded:: 1.3 + + .. attribute:: localizer + + A :term:`localizer` which will use the current locale name to + translate values. + + .. versionadded:: 1.5 + + .. attribute:: locale_name - .. warning:: As of Pyramid 1.1, assignment to ``response_*`` attrs are - deprecated. Assigning to one will cause a deprecation warning to be - emitted. Instead of assigning ``response_*`` attributes to the - request, use API of the the :attr:`pyramid.request.Request.response` - object (exposed to view code as ``request.response``) to influence - response behavior. + The locale name of the current request as computed by the + :term:`locale negotiator`. - You can set attributes on a :class:`pyramid.request.Request` which will - influence the behavor of *rendered* responses (views which use a - :term:`renderer` and which don't directly return a response). These - attributes begin with ``response_``, such as ``response_headerlist``. If - you need to influence response values from a view that uses a renderer - (such as the status code, a header, the content type, etc) see, - :ref:`response_prefixed_attrs`. + .. versionadded:: 1.5 .. note:: @@ -183,3 +372,4 @@ that used as ``request.GET``, ``request.POST``, and ``request.params``), see :class:`pyramid.interfaces.IMultiDict`. +.. autofunction:: apply_request_extensions(request) |