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, 18 deletions

diff --git a/tests/test_config/test_routes.py b/tests/test_config/test_routes.py
index 423da5834..a75fdd776 100644
--- a/tests/test_config/test_routes.py
+++ b/tests/test_config/test_routes.py
@@ -316,7 +316,7 @@ class RoutesConfiguratorMixinTests(unittest.TestCase):
             warnings.simplefilter('always', DeprecationWarning)
             config.add_route('foo', '/bar', effective_principals=['any'])
             self.assertIn(
-                'removed the concept of principals', str(w[-1].message)
+                'deprecated effective_principals', str(w[-1].message)
             )
 
 
diff --git a/tests/test_config/test_views.py b/tests/test_config/test_views.py
index d133aedbd..353749ed6 100644
--- a/tests/test_config/test_views.py
+++ b/tests/test_config/test_views.py
@@ -2933,7 +2933,7 @@ class TestViewsConfigurationMixin(unittest.TestCase):
             warnings.simplefilter('always', DeprecationWarning)
             config.add_view(lambda: None, effective_principals=['any'])
             self.assertIn(
-                'removed the concept of principals', str(w[-1].message)
+                'deprecated effective_principals', str(w[-1].message)
             )
 
 
diff --git a/tests/test_predicates.py b/tests/test_predicates.py
index 4029faf9d..c0a6c59ec 100644
--- a/tests/test_predicates.py
+++ b/tests/test_predicates.py
@@ -454,8 +454,9 @@ class Test_EffectivePrincipalsPredicate(unittest.TestCase):
         return EffectivePrincipalsPredicate(val, config)
 
     def _testing_authn_policy(self, userid, groupids=tuple()):
-        from pyramid.interfaces import IAuthenticationPolicy
+        from pyramid.interfaces import IAuthenticationPolicy, ISecurityPolicy
         from pyramid.security import Everyone, Authenticated
+        from pyramid.security import LegacySecurityPolicy
 
         class DummyPolicy:
             def effective_principals(self, request):
@@ -468,6 +469,7 @@ class Test_EffectivePrincipalsPredicate(unittest.TestCase):
 
         registry = self.config.registry
         registry.registerUtility(DummyPolicy(), IAuthenticationPolicy)
+        registry.registerUtility(LegacySecurityPolicy(), ISecurityPolicy)
 
     def test_text(self):
         inst = self._makeOne(('verna', 'fred'), None)
diff --git a/tests/test_router.py b/tests/test_router.py
index f6b7f64d3..6fa9f9a5b 100644
--- a/tests/test_router.py
+++ b/tests/test_router.py
@@ -1699,10 +1699,6 @@ class DummyResponse(object):
         return self.app_iter
 
 
-class DummyAuthenticationPolicy:
-    pass
-
-
 class DummyLogger:
     def __init__(self):
         self.messages = []
diff --git a/tests/test_security.py b/tests/test_security.py
index f39e3c730..fa3d165ea 100644
--- a/tests/test_security.py
+++ b/tests/test_security.py
@@ -346,16 +346,22 @@ class TestAuthenticatedUserId(unittest.TestCase):
         request = _makeRequest()
         self.assertEqual(request.authenticated_userid, None)
 
+    def test_with_security_policy(self):
+        request = _makeRequest()
+        _registerSecurityPolicy(request.registry, '123')
+        self.assertEqual(request.authenticated_userid, '123')
+
     def test_with_authentication_policy(self):
         request = _makeRequest()
         _registerAuthenticationPolicy(request.registry, 'yo')
-        _registerSecurityPolicy(request.registry, 'wat')
-        self.assertEqual(request.authenticated_userid, 'wat')
+        _registerLegacySecurityPolicy(request.registry)
+        self.assertEqual(request.authenticated_userid, 'yo')
 
-    def test_with_security_policy(self):
+    def test_security_policy_trumps_authentication_policy(self):
         request = _makeRequest()
-        _registerSecurityPolicy(request.registry, '123')
-        self.assertEqual(request.authenticated_userid, '123')
+        _registerAuthenticationPolicy(request.registry, 'yo')
+        _registerSecurityPolicy(request.registry, 'wat')
+        self.assertEqual(request.authenticated_userid, 'wat')
 
 
 class TestUnAuthenticatedUserId(unittest.TestCase):
@@ -369,17 +375,23 @@ class TestUnAuthenticatedUserId(unittest.TestCase):
         request = _makeRequest()
         self.assertEqual(request.unauthenticated_userid, None)
 
-    def test_with_authentication_policy(self):
+    def test_with_security_policy(self):
         request = _makeRequest()
-        _registerAuthenticationPolicy(request.registry, 'yo')
-        _registerSecurityPolicy(request.registry, 'wat')
+        _registerSecurityPolicy(request.registry, 'yo')
         self.assertEqual(request.unauthenticated_userid, 'yo')
 
-    def test_with_security_policy(self):
+    def test_legacy_authentication_policy(self):
         request = _makeRequest()
-        _registerSecurityPolicy(request.registry, 'yo')
+        _registerAuthenticationPolicy(request.registry, 'yo')
+        _registerLegacySecurityPolicy(request.registry)
         self.assertEqual(request.unauthenticated_userid, 'yo')
 
+    def test_security_policy_trumps_authentication_policy(self):
+        request = _makeRequest()
+        _registerAuthenticationPolicy(request.registry, 'yo')
+        _registerSecurityPolicy(request.registry, 'wat')
+        self.assertEqual(request.unauthenticated_userid, 'wat')
+
 
 class TestEffectivePrincipals(unittest.TestCase):
     def setUp(self):
@@ -394,11 +406,27 @@ class TestEffectivePrincipals(unittest.TestCase):
         request = _makeRequest()
         self.assertEqual(request.effective_principals, [Everyone])
 
-    def test_with_authentication_policy(self):
+    def test_with_security_policy(self):
+        from pyramid.security import Everyone
+
+        request = _makeRequest()
+        _registerSecurityPolicy(request.registry, 'yo')
+        self.assertEqual(request.effective_principals, [Everyone])
+
+    def test_legacy_authentication_policy(self):
         request = _makeRequest()
         _registerAuthenticationPolicy(request.registry, 'yo')
+        _registerLegacySecurityPolicy(request.registry)
         self.assertEqual(request.effective_principals, 'yo')
 
+    def test_security_policy_trumps_authentication_policy(self):
+        from pyramid.security import Everyone
+
+        request = _makeRequest()
+        _registerAuthenticationPolicy(request.registry, 'wat')
+        _registerSecurityPolicy(request.registry, 'yo')
+        self.assertEqual(request.effective_principals, [Everyone])
+
 
 class TestHasPermission(unittest.TestCase):
     def setUp(self):
@@ -567,6 +595,15 @@ def _registerSecurityPolicy(reg, result):
     return policy
 
 
+def _registerLegacySecurityPolicy(reg):
+    from pyramid.interfaces import ISecurityPolicy
+    from pyramid.security import LegacySecurityPolicy
+
+    policy = LegacySecurityPolicy()
+    reg.registerUtility(policy, ISecurityPolicy)
+    return policy
+
+
 def _registerAuthenticationPolicy(reg, result):
     from pyramid.interfaces import IAuthenticationPolicy