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.

1 files changed, 48 insertions, 11 deletions

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