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

1 files changed, 49 insertions, 7 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 61f3b63f7..20b7726c4 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -4,13 +4,34 @@ Unreleased
 Features
 --------
 
-- The :mod:``pyramid.security`` authentication API methods should now be 
-  accessed via the request. The ``pyramid.security`` authoriztion API function 
-  :meth:`has_permission` should now be accessed via the request.
-  The methods :meth:``pyramid.request.Request.forget_userid``, 
-  meth:``pyramid.request.Request.remember_userid`` now automatically 
-  set the headers on the response, as returned by the corrosponding 
-  method of the current request's :term:``authentication policy``.
+- Authentication and authorization APIs have been added as as methods of the
+  request: ``request.has_permission``, ``request.forget_userid``, and
+  ``request.remember_userid``.
+
+  ``request.has_permission`` is a method-based alternative to the
+  ``pyramid.security.has_permission`` API and works exactly the same.  The
+  older API is now deprecated.
+
+  ``request.forget_userid`` and ``request.remember_userid`` are method-based
+  alternatives to ``pyramid.security.forget`` and
+  ``pyramid.security.remember``.  These do not work exacly the same as their
+  function counterparts, however.  These methods automatically set the headers
+  returned by the authentication policy on the response, whereas the older
+  function-based APIs returned a sequence of headers and required the caller to
+  set those headers.  The older function-based API still works but is now
+  deprecated.
+
+- Property API attributes have been added to the request for easier access to
+  authentication data: ``request.authenticated_userid``,
+  ``request.unauthenticated_userid``, and ``request.effective_principals``.
+
+  These are analogues, respectively, of
+  ``pyramid.security.authenticated_userid``,
+  ``pyramid.security.unauthenticated_userid``, and
+  ``pyramid.security.effective_principals``.  They operate exactly the same,
+  except they are attributes of the request instead of functions accepting a
+  request.  They are properties, so they cannot be assigned to.  The older
+  function-based APIs are now deprecated.
 
 - Pyramid's console scripts (``pserve``, ``pviews``, etc) can now be run
   directly, allowing custom arguments to be sent to the python interpreter
@@ -105,6 +126,27 @@ Deprecations
   the SignedCookieSessionFactory are not. See 
   https://github.com/Pylons/pyramid/pull/1142
 
+- The ``pyramid.security.has_permission`` API is now deprecated.  Instead, use
+  the newly-added ``has_permission`` method of the request object.
+
+- The ``pyramid.security.forget`` API is now deprecated.  Instead, use
+  the newly-added ``forget_userid`` method of the request object.
+
+- The ``pyramid.security.remember`` API is now deprecated.  Instead, use
+  the newly-added ``remember_userid`` method of the request object.
+
+- The ``pyramid.security.effective_principals`` API is now deprecated.
+  Instead, use the newly-added ``effective_principals`` attribute of the
+  request object.
+
+- The ``pyramid.security.authenticated_userid`` API is now deprecated.
+  Instead, use the newly-added ``authenticated_userid`` attribute of the
+  request object.
+
+- The ``pyramid.security.unauthenticated_userid`` API is now deprecated.
+  Instead, use the newly-added ``unauthenticated_userid`` attribute of the
+  request object.
+
 1.5a2 (2013-09-22)
 ==================