Bring change log, API docs, and deprecations in line with normal policies/processes

1 files changed, 46 insertions, 1 deletions

diff --git a/docs/api/request.rst b/docs/api/request.rst
index 72abddb68..3d1fe020c 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -11,7 +11,10 @@
    :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, set_property
+                     model_url, resource_url, set_property, 
+                     effective_principals, authenticated_userid,
+                     unauthenticated_userid, has_permission, forget_userid,
+                     remember_userid
 
    .. attribute:: context
 
@@ -161,6 +164,42 @@
       request, the value of this attribute will be ``None``. See
       :ref:`matched_route`.
 
+   .. attribute:: authenticated_userid
+
+      .. versionadded:: 1.5
+
+      A property which returns the 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
+      :meth:`~pyramid.request.Request.unauthenticated_userid`, because the
+      effective authentication policy will have ensured that a record
+      associated with the 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) user id 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
+      :meth:`~pyramid.request.Request.authenticated_userid`, because the
+      effective authentication policy will not ensure that a record associated
+      with the userid exists in persistent storage.  Even if the userid
+      does not exist in persistent storage, this value will be the value
+      of the 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 will include the userid of the
+      currently authenticated user if a user is currently authenticated. 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
@@ -215,6 +254,12 @@
       request provided by e.g. the ``pshell`` environment.  For more
       information, see :ref:`subrequest_chapter`.
 
+   .. automethod:: remember_userid
+
+   .. automethod:: forget_userid
+
+   .. automethod:: has_permission
+
    .. automethod:: add_response_callback
 
    .. automethod:: add_finished_callback