Merge pull request #3550 from mmerickel/moar-security-policy

security policy docs and legacy policy improvements

5 files changed, 34 insertions, 22 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index 3ef350888..3ce224d91 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -297,21 +297,22 @@ Methods Which Provide Conflict Detection
 
 These are the methods of the configurator which provide conflict detection:
 
-:meth:`~pyramid.config.Configurator.add_view`,
-:meth:`~pyramid.config.Configurator.add_route`,
-:meth:`~pyramid.config.Configurator.add_renderer`,
-:meth:`~pyramid.config.Configurator.add_request_method`,
-:meth:`~pyramid.config.Configurator.set_request_factory`,
-:meth:`~pyramid.config.Configurator.set_session_factory`,
-:meth:`~pyramid.config.Configurator.set_root_factory`,
-:meth:`~pyramid.config.Configurator.set_view_mapper`,
-:meth:`~pyramid.config.Configurator.set_authentication_policy`,
-:meth:`~pyramid.config.Configurator.set_authorization_policy`,
-:meth:`~pyramid.config.Configurator.set_locale_negotiator`,
-:meth:`~pyramid.config.Configurator.set_default_permission`,
-:meth:`~pyramid.config.Configurator.add_traverser`,
-:meth:`~pyramid.config.Configurator.add_resource_url_adapter`,
-and :meth:`~pyramid.config.Configurator.add_response_adapter`.
+- :meth:`~pyramid.config.Configurator.add_renderer`
+- :meth:`~pyramid.config.Configurator.add_request_method`
+- :meth:`~pyramid.config.Configurator.add_resource_url_adapter`
+- :meth:`~pyramid.config.Configurator.add_response_adapter`
+- :meth:`~pyramid.config.Configurator.add_route`
+- :meth:`~pyramid.config.Configurator.add_traverser`
+- :meth:`~pyramid.config.Configurator.add_view`
+- :meth:`~pyramid.config.Configurator.set_authentication_policy`
+- :meth:`~pyramid.config.Configurator.set_authorization_policy`
+- :meth:`~pyramid.config.Configurator.set_default_permission`
+- :meth:`~pyramid.config.Configurator.set_locale_negotiator`
+- :meth:`~pyramid.config.Configurator.set_request_factory`
+- :meth:`~pyramid.config.Configurator.set_root_factory`
+- :meth:`~pyramid.config.Configurator.set_security_policy`
+- :meth:`~pyramid.config.Configurator.set_session_factory`
+- :meth:`~pyramid.config.Configurator.set_view_mapper`
 
 :meth:`~pyramid.config.Configurator.add_static_view` also indirectly provides
 conflict detection, because it's implemented in terms of the conflict-aware
diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst
index 4c6c8b70b..5a99fc1c6 100644
--- a/docs/narr/extconfig.rst
+++ b/docs/narr/extconfig.rst
@@ -271,6 +271,7 @@ Pre-defined Phases
 
 - :meth:`pyramid.config.Configurator.add_route`
 - :meth:`pyramid.config.Configurator.set_authentication_policy`
+- :meth:`pyramid.config.Configurator.set_security_policy`
 
 :const:`pyramid.config.PHASE3_CONFIG`
 
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index 50f4ac736..40002347c 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -302,6 +302,16 @@ introspectables in categories not described here.
      The :class:`pyramid.interfaces.IRoute` object that is used to perform
      matching and generation for this route.
 
+``security policy``
+
+  There will be one and only one introspectable in the ``security policy`` category.
+  It represents a call to the :meth:`pyramid.config.Configurator.set_security_policy` method (or its Configurator constructor equivalent).
+  It will have the following data:
+
+  ``policy``
+
+    The policy object (the resolved ``policy`` argument to ``set_security_policy``).
+
 ``authentication policy``
 
   There will be one and only one introspectable in the ``authentication
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index 883bb7c7b..2182082a8 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -278,7 +278,7 @@ In the above example, we create a ``MyTest`` test case that inherits from
 be found when ``pytest`` is run.  It has two test methods.
 
 The first test method, ``test_view_fn_forbidden`` tests the ``view_fn`` when
-the authentication policy forbids the current user the ``edit`` permission. Its
+the security policy forbids the current user the ``edit`` permission. Its
 third line registers a "dummy" "non-permissive" authorization policy using the
 :meth:`~pyramid.config.Configurator.testing_securitypolicy` method, which is a
 special helper method for unit testing.
@@ -288,13 +288,13 @@ WebOb request object API.  A :class:`pyramid.testing.DummyRequest` is a request
 object that requires less setup than a "real" :app:`Pyramid` request.  We call
 the function being tested with the manufactured request.  When the function is
 called, :meth:`pyramid.request.Request.has_permission` will call the "dummy"
-authentication policy we've registered through
+security policy we've registered through
 :meth:`~pyramid.config.Configurator.testing_securitypolicy`, which denies
 access.  We check that the view function raises a
 :exc:`~pyramid.httpexceptions.HTTPForbidden` error.
 
 The second test method, named ``test_view_fn_allowed``, tests the alternate
-case, where the authentication policy allows access.  Notice that we pass
+case, where the security policy allows access.  Notice that we pass
 different values to :meth:`~pyramid.config.Configurator.testing_securitypolicy`
 to obtain this result.  We assert at the end of this that the view function
 returns a value.
diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst
index 7437a3a76..8aa5b313d 100644
--- a/docs/narr/threadlocals.rst
+++ b/docs/narr/threadlocals.rst
@@ -32,11 +32,11 @@ various :app:`Pyramid` API functions.  For example, the implementation of the
 :mod:`pyramid.security` function named
 :func:`~pyramid.security.authenticated_userid` (deprecated as of 1.5) retrieves
 the thread local :term:`application registry` as a matter of course to find an
-:term:`authentication policy`.  It uses the
+:term:`security policy`.  It uses the
 :func:`pyramid.threadlocal.get_current_registry` function to retrieve the
-application registry, from which it looks up the authentication policy; it then
-uses the authentication policy to retrieve the authenticated user id.  This is
-how :app:`Pyramid` allows arbitrary authentication policies to be "plugged in".
+application registry, from which it looks up the security policy; it then
+uses the security policy to retrieve the authenticated user id.  This is
+how :app:`Pyramid` allows arbitrary security policies to be "plugged in".
 
 When they need to do so, :app:`Pyramid` internals use two API functions to
 retrieve the :term:`request` and :term:`application registry`: