update changelog and docs

3 files changed, 141 insertions, 7 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 8159cea36..f1ccdf8e6 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -7,6 +7,19 @@ Features
 - Add support for Python 3.8.
   See https://github.com/Pylons/pyramid/pull/3547
 
+- New security APIs have been added to support a massive overhaul of the
+  authentication and authorization system. Read
+  "Upgrading Authentication/Authorization" in the "What's New in Pyramid 2.0"
+  document for information about using this new system.
+
+  - ``pyramid.config.Configurator.set_security_policy``.
+  - ``pyramid.interfaces.ISecurityPolicy``
+  - ``pyramid.request.Request.authenticated_identity``.
+  - ``pyramid.authentication.SessionAuthenticationHelper``
+  - ``pyramid.authorization.ACLHelper``
+
+  See https://github.com/Pylons/pyramid/pull/3465
+
 - Changed the default ``serializer`` on
   ``pyramid.session.SignedCookieSessionFactory`` to use
   ``pyramid.session.JSONSerializer`` instead of
@@ -94,9 +107,55 @@ Features
   and then we want to cache the data for the duration of the request.
   See https://github.com/Pylons/pyramid/pull/3561
 
+- Exposed ``pyramid.authorization.ALL_PERMISSIONS`` and
+  ``pyramid.authorization.DENY_ALL`` such that all of the ACL-related constants
+  are now importable from the ``pyramid.authorization`` namespace.
+  See https://github.com/Pylons/pyramid/pull/3563
+
 Deprecations
 ------------
 
+- Deprecated the authentication and authorization interfaces and
+  principal-based support. See "Upgrading Authentication/Authorization" in
+  the "What's New in Pyramid 2.0" document for information on equivalent APIs
+  and notes on upgrading. The following APIs are deprecated as a result of
+  this change:
+
+  - ``pyramid.config.Configurator.set_authentication_policy``
+  - ``pyramid.config.Configurator.set_authorization_policy``
+  - ``pyramid.interfaces.IAuthenticationPolicy``
+  - ``pyramid.interfaces.IAuthorizationPolicy``
+  - ``pyramid.request.Request.effective_principals``
+  - ``pyramid.request.Request.unauthenticated_userid``
+  - ``pyramid.authentication.AuthTktAuthenticationPolicy``
+  - ``pyramid.authentication.RemoteUserAuthenticationPolicy``
+  - ``pyramid.authentication.RepozeWho1AuthenticationPolicy``
+  - ``pyramid.authentication.SessionAuthenticationPolicy``
+  - ``pyramid.authentication.BasicAuthAuthenticationPolicy``
+  - ``pyramid.authorization.ACLAuthorizationPolicy``
+  - The ``effective_principals`` view and route predicates.
+
+  See https://github.com/Pylons/pyramid/pull/3465
+
+- Deprecated ``pyramid.security.principals_allowed_by_permission``. This
+  method continues to work with the deprecated
+  ``pyramid.interfaces.IAuthorizationPolicy`` interface but will not work with
+  the new ``pyramid.interfaces.ISecurityPolicy``.
+  See https://github.com/Pylons/pyramid/pull/3465
+
+- Deprecated several ACL-related aspects of ``pyramid.security``. Equivalent
+  objects should now be imported from the ``pyramid.authorization`` namespace.
+  This includes:
+
+  - ``pyramid.security.Everyone``
+  - ``pyramid.security.Authenticated``
+  - ``pyramid.security.ALL_PERMISSIONS``
+  - ``pyramid.security.DENY_ALL``
+  - ``pyramid.security.ACLAllowed``
+  - ``pyramid.security.ACLDenied``
+
+  See https://github.com/Pylons/pyramid/pull/3563
+
 - Deprecated ``pyramid.session.PickleSerializer``.
   See https://github.com/pylons/pyramid/issues/2709
   and https://github.com/pylons/pyramid/pull/3353
diff --git a/docs/api/authorization.rst b/docs/api/authorization.rst
index c6b3d090e..fac47490a 100644
--- a/docs/api/authorization.rst
+++ b/docs/api/authorization.rst
@@ -10,3 +10,46 @@
 
   .. autoclass:: ACLAuthorizationPolicy
 
+Constants
+---------
+
+.. attribute:: Everyone
+
+    The special principal id named 'Everyone'.  This principal id is
+    granted to all requests.  Its actual value is the string
+    'system.Everyone'.
+
+.. attribute:: Authenticated
+
+    The special principal id named 'Authenticated'.  This principal id
+    is granted to all requests which contain any other non-Everyone
+    principal id (according to the :term:`authentication policy`).
+    Its actual value is the string 'system.Authenticated'.
+
+.. attribute:: ALL_PERMISSIONS
+
+    An object that can be used as the ``permission`` member of an ACE
+    which matches all permissions unconditionally.  For example, an
+    ACE that uses ``ALL_PERMISSIONS`` might be composed like so:
+    ``('Deny', 'system.Everyone', ALL_PERMISSIONS)``.
+
+.. attribute:: DENY_ALL
+
+    A convenience shorthand ACE that defines ``('Deny',
+    'system.Everyone', ALL_PERMISSIONS)``.  This is often used as the
+    last ACE in an ACL in systems that use an "inheriting" security
+    policy, representing the concept "don't inherit any other ACEs".
+
+Return Values
+-------------
+
+.. autoclass:: ACLDenied
+   :members: msg
+
+   .. automethod:: __new__
+
+.. autoclass:: ACLAllowed
+   :members: msg
+
+   .. automethod:: __new__
+
diff --git a/docs/api/security.rst b/docs/api/security.rst
index edb66472e..3350f8207 100644
--- a/docs/api/security.rst
+++ b/docs/api/security.rst
@@ -10,7 +10,7 @@ Authentication API Functions
 
 .. autofunction:: forget
 
-.. autofunction:: remember(request, userid, **kwargs)
+.. autofunction:: remember
 
 Authorization API Functions
 ---------------------------
@@ -22,12 +22,24 @@ Authorization API Functions
 Constants
 ---------
 
+.. attribute:: NO_PERMISSION_REQUIRED
+
+	A special permission which indicates that the view should always
+	be executable by entirely anonymous users, regardless of the
+	default permission, bypassing any :term:`authorization policy`
+	that may be in effect.  Its actual value is the string
+	'__no_permission_required__'.
+
 .. attribute:: Everyone
 
     The special principal id named 'Everyone'.  This principal id is
     granted to all requests.  Its actual value is the string
     'system.Everyone'.
 
+    .. deprecated:: 2.0
+
+        Moved to :data:`pyramid.authorization.Everyone`.
+
 .. attribute:: Authenticated
 
     The special principal id named 'Authenticated'.  This principal id
@@ -35,6 +47,10 @@ Constants
     principal id (according to the :term:`authentication policy`).
     Its actual value is the string 'system.Authenticated'.
 
+    .. deprecated:: 2.0
+
+        Moved to :data:`pyramid.authorization.Authenticated`.
+
 .. attribute:: ALL_PERMISSIONS
 
     An object that can be used as the ``permission`` member of an ACE
@@ -42,6 +58,10 @@ Constants
     ACE that uses ``ALL_PERMISSIONS`` might be composed like so:
     ``('Deny', 'system.Everyone', ALL_PERMISSIONS)``.
 
+    .. deprecated:: 2.0
+
+        Moved to :data:`pyramid.authorization.ALL_PERMISSIONS`.
+
 .. attribute:: DENY_ALL
 
     A convenience shorthand ACE that defines ``('Deny',
@@ -49,13 +69,9 @@ Constants
     last ACE in an ACL in systems that use an "inheriting" security
     policy, representing the concept "don't inherit any other ACEs".
 
-.. attribute:: NO_PERMISSION_REQUIRED
+    .. deprecated:: 2.0
 
-	A special permission which indicates that the view should always
-	be executable by entirely anonymous users, regardless of the
-	default permission, bypassing any :term:`authorization policy`
-	that may be in effect.  Its actual value is the string
-	'__no_permission_required__'.
+        Moved to :data:`pyramid.authorization.DENY_ALL`.
 
 Return Values
 -------------
@@ -66,12 +82,20 @@ Return Values
     'read')`` that means allow access.  A sequence of ACEs makes up an
     ACL.  It is a string, and its actual value is "Allow".
 
+    .. deprecated:: 2.0
+
+        Moved to :data:`pyramid.authorization.Allow`.
+
 .. attribute:: Deny
 
     The ACE "action" (the first element in an ACE e.g. ``(Deny,
     'george', 'read')`` that means deny access.  A sequence of ACEs
     makes up an ACL.  It is a string, and its actual value is "Deny".
 
+    .. deprecated:: 2.0
+
+        Moved to :data:`pyramid.authorization.Deny`.
+
 .. autoclass:: Denied
    :members: msg
 
@@ -85,10 +109,18 @@ Return Values
 .. autoclass:: ACLDenied
    :members: msg
 
+    .. deprecated:: 2.0
+
+        Moved to :data:`pyramid.authorization.ACLDenied`.
+
    .. automethod:: __new__
 
 .. autoclass:: ACLAllowed
    :members: msg
 
+    .. deprecated:: 2.0
+
+        Moved to :data:`pyramid.authorization.ACLAllowed`.
+
    .. automethod:: __new__