add tests and docs

CHANGES.rst

@@ -22,10 +22,13 @@ Features
   - ``pyramid.config.Configurator.set_security_policy``.
   - ``pyramid.interfaces.ISecurityPolicy``
   - ``pyramid.request.Request.authenticated_identity``.
+  - ``pyramid.request.Request.is_authenticated``
   - ``pyramid.authentication.SessionAuthenticationHelper``
   - ``pyramid.authorization.ACLHelper``
+  - ``is_authenticated=True/False`` predicate for route and view configs
 
-  See https://github.com/Pylons/pyramid/pull/3465
+  See https://github.com/Pylons/pyramid/pull/3465 and
+  https://github.com/Pylons/pyramid/pull/3598
 
 - Changed the default ``serializer`` on
   ``pyramid.session.SignedCookieSessionFactory`` to use

docs/narr/viewconfig.rst

@@ -496,7 +496,11 @@ configured view.
 
 ``is_authenticated``
 
-  XXX doc doc
+  This value, if specified, must be either ``True`` or ``False``.  If it is
+  specified and is ``True``, the request must be for an authenticated user,
+  as determined by the :term:`security policy` in use.  If it is specified and
+  ``False``, the associated view callable will be invoked only if the request
+  does not have an authenticated user.
 
   .. versionadded:: 2.0
 
@@ -511,7 +515,7 @@ configured view.
 
   .. versionadded:: 1.4a4
 
-  .. deprecated:: TODO add
+  .. deprecated:: 2.0
 
 ``custom_predicates``
   If ``custom_predicates`` is specified, it must be a sequence of references to

src/pyramid/config/routes.py

@@ -270,7 +270,12 @@ def add_route(
 
         is_authenticated
 
-          XXX doc doc
+          This value, if specified, should be either ``True`` or ``False``.
+          If it is specified and is ``True``, the route will only match if
+          the request has an authenticated user, as determined by the
+          :term:`security policy` in use.  If it is specified and ``False``,
+          the route will only match if the request does not have an
+          authenticated user.
 
           .. versionadded:: 2.0
 

src/pyramid/config/views.py

@@ -714,7 +714,11 @@ def wrapper(context, request):
 
         is_authenticated
 
-          XXX doc doc
+          This value, if specified, should be either ``True`` or ``False``.
+          If it is specified and is ``True``, the request must be for an
+          authenticated user, as determined by the :term:`security policy` in
+          use.  If it is specified and ``False``, the associated view callable
+          will match only if the request does not have an authenticated user.
 
           ..versionadded:: 2.0
 

src/pyramid/interfaces.py

@@ -114,11 +114,13 @@ def app_iter_range(start, stop):
         serves up only the given start:stop range. """
 
     authenticated_identity = Attribute(
-        """XXX Doc doc"""
+        """An object representing the authenticated user, as determined by
+        the security policy in use, or ``None`` for unauthenticated requests.
+        The object's class and meaning is defined by the security policy."""
     )
 
     authenticated_userid = Attribute(
-        """XXX Doc doc"""
+        """A string to identify the authenticated user or ``None``."""
     )
 
     body = Attribute(
@@ -242,7 +244,8 @@ def encode_content(encoding='gzip', lazy=False):
     headers = Attribute(""" The headers in a dictionary-like object """)
 
     is_authenticated = Attribute(
-        """XXX doc doc"""
+        """A boolean indicating whether the request has an authenticated
+        user, as determined by the security policy in use."""
     )
 
     last_modified = Attribute(

src/pyramid/security.py

@@ -246,7 +246,7 @@ def authenticated_userid(self):
 
     @property
     def is_authenticated(self):
-        """Return True if a user is authenticated for this request."""
+        """Return ``True`` if a user is authenticated for this request."""
         return self.authenticated_identity is not None
 
     def has_permission(self, permission, context=None):

tests/test_config/test_predicates.py

@@ -454,13 +454,28 @@ def test_header_multiple_mixed_fails(self):
         self.assertFalse(predicates[0](Dummy(), request))
 
     def test_is_authenticated_true_matches(self):
-        ...
+        _, predicates, _ = self._callFUT(is_authenticated=True)
+        request = DummyRequest()
+        request.is_authenticated = True
+        self.assertTrue(predicates[0](Dummy(), request))
+
     def test_is_authenticated_true_fails(self):
-        ...
+        _, predicates, _ = self._callFUT(is_authenticated=True)
+        request = DummyRequest()
+        request.is_authenticated = False
+        self.assertFalse(predicates[0](Dummy(), request))
+
     def test_is_authenticated_false_matches(self):
-        ...
+        _, predicates, _ = self._callFUT(is_authenticated=False)
+        request = DummyRequest()
+        request.is_authenticated = False
+        self.assertTrue(predicates[0](Dummy(), request))
+
     def test_is_authenticated_false_fails(self):
-        ...
+        _, predicates, _ = self._callFUT(is_authenticated=False)
+        request = DummyRequest()
+        request.is_authenticated = True
+        self.assertFalse(predicates[0](Dummy(), request))
 
     def test_unknown_predicate(self):
         from pyramid.exceptions import ConfigurationError

tests/test_config/test_routes.py

@@ -184,6 +184,18 @@ def test_add_route_with_request_param(self):
         request.params = {}
         self.assertEqual(predicate(None, request), False)
 
+    def test_add_route_with_is_authenticated(self):
+        config = self._makeOne(autocommit=True)
+        config.add_route('name', 'path', is_authenticated=True)
+        route = self._assertRoute(config, 'name', 'path', 1)
+        predicate = route.predicates[0]
+        request = self._makeRequest(config)
+        request.is_authenticated = True
+        self.assertEqual(predicate(None, request), True)
+        request = self._makeRequest(config)
+        request.is_authenticated = False
+        self.assertEqual(predicate(None, request), False)
+
     def test_add_route_with_custom_predicates(self):
         import warnings
 

tests/test_config/test_views.py

@@ -1742,6 +1742,46 @@ def test_add_view_with_xhr_false(self):
         request.is_xhr = False
         self._assertNotFound(wrapper, None, request)
 
+    def test_add_view_with_is_authenticated_true_matches(self):
+        from pyramid.renderers import null_renderer as nr
+
+        view = lambda *arg: 'OK'
+        config = self._makeOne(autocommit=True)
+        config.add_view(view=view, is_authenticated=True, renderer=nr)
+        wrapper = self._getViewCallable(config)
+        request = self._makeRequest(config)
+        request.is_authenticated = True
+        self.assertEqual(wrapper(None, request), 'OK')
+
+    def test_add_view_with_is_authenticated_true_no_match(self):
+        view = lambda *arg: 'OK'
+        config = self._makeOne(autocommit=True)
+        config.add_view(view=view, is_authenticated=True)
+        wrapper = self._getViewCallable(config)
+        request = self._makeRequest(config)
+        request.is_authenticated = False
+        self._assertNotFound(wrapper, None, request)
+
+    def test_add_view_with_is_authenticated_false_matches(self):
+        from pyramid.renderers import null_renderer as nr
+
+        view = lambda *arg: 'OK'
+        config = self._makeOne(autocommit=True)
+        config.add_view(view=view, is_authenticated=False, renderer=nr)
+        wrapper = self._getViewCallable(config)
+        request = self._makeRequest(config)
+        request.is_authenticated = False
+        self.assertEqual(wrapper(None, request), 'OK')
+
+    def test_add_view_with_is_authenticated_false_no_match(self):
+        view = lambda *arg: 'OK'
+        config = self._makeOne(autocommit=True)
+        config.add_view(view=view, is_authenticated=False)
+        wrapper = self._getViewCallable(config)
+        request = self._makeRequest(config)
+        request.is_authenticated = True
+        self._assertNotFound(wrapper, None, request)
+
     def test_add_view_with_header_badregex(self):
         view = lambda *arg: 'OK'
         config = self._makeOne()

tests/test_security.py

@@ -393,6 +393,29 @@ def test_security_policy_trumps_authentication_policy(self):
         self.assertEqual(request.unauthenticated_userid, 'wat')
 
 
+class TestIsAuthenticated(unittest.TestCase):
+    def setUp(self):
+        testing.setUp()
+
+    def tearDown(self):
+        testing.tearDown()
+
+    def test_no_security_policy(self):
+        request = _makeRequest()
+        self.assertIs(request.is_authenticated, False)
+
+    def test_with_security_policy(self):
+        request = _makeRequest()
+        _registerSecurityPolicy(request.registry, '123')
+        self.assertIs(request.is_authenticated, True)
+
+    def test_with_legacy_security_policy(self):
+        request = _makeRequest()
+        _registerAuthenticationPolicy(request.registry, 'yo')
+        _registerLegacySecurityPolicy(request.registry)
+        self.assertEqual(request.authenticated_userid, 'yo')
+
+
 class TestEffectivePrincipals(unittest.TestCase):
     def setUp(self):
         testing.setUp()