Merge remote-tracking branch 'refs/remotes/Pylons/master'

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)