security policy docs and legacy policy improvements

- Added `set_security_policy`` to more places in the docs.
- Ensure that the authn/authz policies are not used at all if the legacy
  policy is not in effect to avoid edge cases where the code would skip
  the security policy and use the authn/authz policy on accident.
- Change deprecation warnings in code to reference the docs by name
  instead of by URL.

5 files changed, 53 insertions, 37 deletions

diff --git a/src/pyramid/config/routes.py b/src/pyramid/config/routes.py
index daef8e9f2..ad846a107 100644
--- a/src/pyramid/config/routes.py
+++ b/src/pyramid/config/routes.py
@@ -335,9 +335,10 @@ class RoutesConfiguratorMixin(object):
         if 'effective_principals' in predicates:
             warnings.warn(
                 (
-                    'The new security policy has removed the concept of '
-                    'principals. See "Upgrading Authentication/Authorization" '
-                    'in "What\'s New in Pyramid 2.0" for more information.'
+                    'The new security policy has deprecated '
+                    'effective_principals. See "Upgrading '
+                    'Authentication/Authorization" in "What\'s New in '
+                    'Pyramid 2.0" for more information.'
                 ),
                 DeprecationWarning,
                 stacklevel=3,
diff --git a/src/pyramid/config/security.py b/src/pyramid/config/security.py
index 99eb5792c..8d6a417c0 100644
--- a/src/pyramid/config/security.py
+++ b/src/pyramid/config/security.py
@@ -1,5 +1,5 @@
+import warnings
 from zope.interface import implementer
-from zope.deprecation import deprecate
 
 from pyramid.interfaces import (
     IAuthorizationPolicy,
@@ -57,13 +57,6 @@ class SecurityConfiguratorMixin(object):
             introspectables=(intr,),
         )
 
-    @deprecate(
-        'Authentication and authorization policies have been deprecated in '
-        'favor of security policies.  See '
-        'https://docs.pylonsproject.org/projects/pyramid/en/latest'
-        '/whatsnew-2.0.html#upgrading-authentication-authorization '
-        'for more information.'
-    )
     @action_method
     def set_authentication_policy(self, policy):
         """
@@ -84,6 +77,14 @@ class SecurityConfiguratorMixin(object):
            achieve the same purpose.
 
         """
+        warnings.warn(
+            'Authentication and authorization policies have been deprecated '
+            'in favor of security policies.  See "Upgrading '
+            'Authentication/Authorization" in "What\'s New in Pyramid 2.0" '
+            'for more information.',
+            DeprecationWarning,
+            stacklevel=3,
+        )
 
         def register():
             self.registry.registerUtility(policy, IAuthenticationPolicy)
@@ -137,6 +138,14 @@ class SecurityConfiguratorMixin(object):
            achieve the same purpose.
 
         """
+        warnings.warn(
+            'Authentication and authorization policies have been deprecated '
+            'in favor of security policies.  See "Upgrading '
+            'Authentication/Authorization" in "What\'s New in Pyramid 2.0" '
+            'for more information.',
+            DeprecationWarning,
+            stacklevel=3,
+        )
 
         def register():
             self.registry.registerUtility(policy, IAuthorizationPolicy)
diff --git a/src/pyramid/config/views.py b/src/pyramid/config/views.py
index 324462d1a..2260d5d54 100644
--- a/src/pyramid/config/views.py
+++ b/src/pyramid/config/views.py
@@ -794,9 +794,10 @@ class ViewsConfiguratorMixin(object):
         if 'effective_principals' in view_options:
             warnings.warn(
                 (
-                    'The new security policy has removed the concept of '
-                    'principals. See "Upgrading Authentication/Authorization" '
-                    'in "What\'s New in Pyramid 2.0" for more information.'
+                    'The new security policy has deprecated '
+                    'effective_principals. See "Upgrading '
+                    'Authentication/Authorization" in "What\'s New in '
+                    'Pyramid 2.0" for more information.'
                 ),
                 DeprecationWarning,
                 stacklevel=4,
diff --git a/src/pyramid/security.py b/src/pyramid/security.py
index e3a978c52..2a0fb1279 100644
--- a/src/pyramid/security.py
+++ b/src/pyramid/security.py
@@ -41,10 +41,6 @@ def _get_security_policy(request):
     return request.registry.queryUtility(ISecurityPolicy)
 
 
-def _get_authentication_policy(request):
-    return request.registry.queryUtility(IAuthenticationPolicy)
-
-
 def remember(request, userid, **kw):
     """
     Returns a sequence of header tuples (e.g. ``[('Set-Cookie', 'foo=abc')]``)
@@ -71,7 +67,7 @@ def remember(request, userid, **kw):
 
     .. versionchanged:: 1.6
         Deprecated the ``principal`` argument in favor of ``userid`` to clarify
-        its relationship to the authentication policy.
+        its relationship to the security policy.
 
     .. versionchanged:: 1.10
         Removed the deprecated ``principal`` argument.
@@ -141,8 +137,7 @@ def principals_allowed_by_permission(context, permission):
 deprecated(
     'principals_allowed_by_permission',
     'The new security policy has removed the concept of principals.  See '
-    'https://docs.pylonsproject.org/projects/pyramid/en/latest'
-    '/whatsnew-2.0.html#upgrading-authentication-authorization '
+    '"Upgrading Authentication/Authorization" in "What\'s New in Pyramid 2.0" '
     'for more information.',
 )
 
@@ -152,7 +147,7 @@ def view_execution_permitted(context, request, name=''):
     by a :term:`permission`, check the permission associated with the
     view using the effective authentication/authorization policies and
     the ``request``.  Return a boolean result.  If no
-    :term:`authorization policy` is in effect, or if the view is not
+    :term:`security policy` is in effect, or if the view is not
     protected by a permission, return ``True``. If no view can view found,
     an exception will be raised.
 
@@ -376,14 +371,22 @@ class AuthenticationAPIMixin(object):
         associated with the userid exists in persistent storage.
 
         """
-        authn = _get_authentication_policy(self)
         security = _get_security_policy(self)
-        if authn is not None:
-            return authn.unauthenticated_userid(self)
-        elif security is not None:
-            return security.authenticated_userid(self)
-        else:
+        if security is None:
             return None
+        if isinstance(security, LegacySecurityPolicy):
+            authn = security._get_authn_policy(self)
+            return authn.unauthenticated_userid(self)
+        return security.authenticated_userid(self)
+
+    unauthenticated_userid = deprecated(
+        unauthenticated_userid,
+        (
+            'The new security policy has deprecated unauthenticated_userid. '
+            'See "Upgrading Authentication/Authorization" in "What\'s New in '
+            'Pyramid 2.0" for more information.'
+        ),
+    )
 
     @property
     def effective_principals(self):
@@ -399,17 +402,19 @@ class AuthenticationAPIMixin(object):
         :data:`pyramid.security.Everyone` principal.
 
         """
-        policy = _get_authentication_policy(self)
-        if policy is None:
-            return [Everyone]
-        return policy.effective_principals(self)
+        security = _get_security_policy(self)
+        if security is not None and isinstance(security, LegacySecurityPolicy):
+            authn = security._get_authn_policy(self)
+            return authn.effective_principals(self)
+        return [Everyone]
 
     effective_principals = deprecated(
         effective_principals,
-        'The new security policy has removed the concept of principals.  See '
-        'https://docs.pylonsproject.org/projects/pyramid/en/latest'
-        '/whatsnew-2.0.html#upgrading-authentication-authorization '
-        'for more information.',
+        (
+            'The new security policy has deprecated effective_principals. '
+            'See "Upgrading Authentication/Authorization" in "What\'s New in '
+            'Pyramid 2.0" for more information.'
+        ),
     )
 
 
diff --git a/src/pyramid/view.py b/src/pyramid/view.py
index eeac4e783..201e8af7c 100644
--- a/src/pyramid/view.py
+++ b/src/pyramid/view.py
@@ -102,7 +102,7 @@ def render_view_to_iterable(context, request, name='', secure=True):
     If ``secure`` is ``True``, and the view is protected by a permission, the
     permission will be checked before the view function is invoked.  If the
     permission check disallows view execution (based on the current
-    :term:`authentication policy`), a
+    :term:`security policy`), a
     :exc:`pyramid.httpexceptions.HTTPForbidden` exception will be raised; its
     ``args`` attribute explains why the view access was disallowed.