Merge branch 'feature.lazy-request-properties' into 1.3-branch

2 files changed, 17 insertions, 12 deletions

diff --git a/docs/api/request.rst b/docs/api/request.rst
index 9596e5621..1ab84e230 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -208,9 +208,7 @@
        body associated with this request, this property will raise an
        exception.  See also :ref:`request_json_body`.
 
-   .. method:: set_property(func, name=None, reify=False)
-
-       .. versionadded:: 1.3
+   .. method:: set_property(callable, name=None, reify=False)
 
        Add a callable or a property descriptor to the request instance.
 
@@ -225,15 +223,15 @@
        cached. Thus the value of the property is only computed once for
        the lifetime of the object.
 
-       ``func`` can either be a callable that accepts the request as
+       ``callable`` can either be a callable that accepts the request as
        its single positional parameter, or it can be a property
        descriptor.
 
-       If the ``func`` is a property descriptor a ``ValueError`` will
-       be raised if ``name`` is ``None`` or ``reify`` is ``True``.
+       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 ``func``.
+       from the name of the ``callable``.
 
        .. code-block:: python
           :linenos:
@@ -259,6 +257,8 @@
        without having to subclass it, which can be useful for extension
        authors.
 
+       .. versionadded:: 1.3
+
 .. note::
 
    For information about the API of a :term:`multidict` structure (such as
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index eb8617ff1..ee4e2ccb5 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -198,11 +198,16 @@ Extending a Request without Subclassing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is now possible to extend a :class:`pyramid.request.Request` object
-with property descriptors without having to create a subclass via
-:meth:`pyramid.request.Request.set_property`. New properties may be
-reified, effectively caching the value for the lifetime of the instance.
-Common use-cases for this would be to get a database connection for the
-request or identify the current user.
+with property descriptors without having to create a custom request factory.
+The new method :meth:`pyramid.config.Configurator.set_request_property`
+provides an entry point for addons to register properties which will be
+added to each request. New properties may be reified, effectively caching
+the return value for the lifetime of the instance. Common use-cases for this
+would be to get a database connection for the request or identify the current
+user. The new method :meth:`pyramid.request.Request.set_property` has been
+added, as well, but the configurator method should be preferred as it
+provides conflict detection and consistency in the lifetime of the
+properties.
 
 Minor Feature Additions
 -----------------------