From 279fbb2524586d8a0ed1d5fa28ca1aced79eb126 Mon Sep 17 00:00:00 2001
From: Theron Luhn <theron@luhn.com>
Date: Sat, 14 Dec 2019 17:49:44 -0600
Subject: Update docs from Configurator.testing_securitypolicy.

---
 src/pyramid/config/testing.py | 69 +++++++++++++++++++++----------------------
 src/pyramid/testing.py        |  2 +-
 2 files changed, 34 insertions(+), 37 deletions(-)

(limited to 'src')

diff --git a/src/pyramid/config/testing.py b/src/pyramid/config/testing.py
index 83a8db552..2cde8fc59 100644
--- a/src/pyramid/config/testing.py
+++ b/src/pyramid/config/testing.py
@@ -19,41 +19,38 @@ class TestingConfiguratorMixin(object):
         remember_result=None,
         forget_result=None,
     ):
-        """Unit/integration testing helper: Registers a pair of faux
-        :app:`Pyramid` security policies: a :term:`authentication
-        policy` and a :term:`authorization policy`.
-
-        The behavior of the registered :term:`authorization policy`
-        depends on the ``permissive`` argument.  If ``permissive`` is
-        true, a permissive :term:`authorization policy` is registered;
-        this policy allows all access.  If ``permissive`` is false, a
-        nonpermissive :term:`authorization policy` is registered; this
-        policy denies all access.
-
-        ``remember_result``, if provided, should be the result returned by
-        the ``remember`` method of the faux authentication policy.  If it is
-        not provided (or it is provided, and is ``None``), the default value
-        ``[]`` (the empty list) will be returned by ``remember``.
-
-        ``forget_result``, if provided, should be the result returned by
-        the ``forget`` method of the faux authentication policy.  If it is
-        not provided (or it is provided, and is ``None``), the default value
-        ``[]`` (the empty list) will be returned by ``forget``.
-
-        XXX rewrite
-        The behavior of the registered :term:`authentication policy`
-        depends on the values provided for the ``userid`` and
-        ``groupids`` argument.  The authentication policy will return
-        the userid identifier implied by the ``userid`` argument and
-        the group ids implied by the ``groupids`` argument when the
-        :attr:`pyramid.request.Request.authenticated_userid` or
-        :attr:`pyramid.request.Request.effective_principals` APIs are
-        used.
-
-        This function is most useful when testing code that uses
-        the APIs named :meth:`pyramid.request.Request.has_permission`,
-        :attr:`pyramid.request.Request.authenticated_userid`,
-        :func:`pyramid.security.principals_allowed_by_permission`.
+        """Unit/integration testing helper.  Registers a faux :term:`security
+        policy`.
+
+        This function is most useful when testing code that uses the security
+        APIs, such as :meth:`pyramid.request.Request.identity`,
+        :attr:`pyramid.request.Request.authenticated_userid`, or
+        :meth:`pyramid.request.Request.has_permission`,
+
+        The behavior of the registered :term:`security policy` depends on the
+        arguments passed to this method.
+
+        :param userid:  If provided, the policy's ``authenticated_userid``
+            method will return this value.  As a result,
+            :attr:`pyramid.request.Request.authenticated_userid` will have this
+            value as well.
+        :type userid:  str
+        :param identity:  If provided, the policy's ``identify`` method will
+            return this value.  As a result,
+            :attr:`pyramid.request.Request.authenticated_identity`` will have
+            this value.
+        :type identity:  object
+        :param permissive:  If true, the policy will allow access to any user
+            for any permission.  If false, the policy will deny all access.
+        :type permissive:  bool
+        :param remember_result:  If provided, the policy's ``remember`` method
+            will return this value.  Otherwise, ``remember`` will return an
+            empty list.
+        :type remember_result:  list
+        :param forget_result:  If provided, the policy's ``forget`` method will
+            return this value.  Otherwise, ``forget`` will return an empty
+            list.
+        :type forget_result:  list
 
         .. versionadded:: 1.4
            The ``remember_result`` argument.
@@ -62,7 +59,7 @@ class TestingConfiguratorMixin(object):
            The ``forget_result`` argument.
 
         .. versionchanged:: 2.0
-           Removed ``groupids`` argument and doc about effective principals.
+           Removed ``groupids`` argument and add `identity` argument.
         """
         from pyramid.testing import DummySecurityPolicy
 
diff --git a/src/pyramid/testing.py b/src/pyramid/testing.py
index 316e0bd15..a1870874e 100644
--- a/src/pyramid/testing.py
+++ b/src/pyramid/testing.py
@@ -38,7 +38,7 @@ class DummyRootFactory(object):
 
 
 class DummySecurityPolicy(object):
-    """ A standin for a security policy"""
+    """ A standin for a :term:`security policy`."""
 
     def __init__(
         self,
-- 
cgit v1.2.3