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, 19 insertions, 7 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index 3ef350888..1d094f219 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -307,6 +307,7 @@ These are the methods of the configurator which provide conflict detection:
 :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_security_policy`,
 :meth:`~pyramid.config.Configurator.set_locale_negotiator`,
 :meth:`~pyramid.config.Configurator.set_default_permission`,
 :meth:`~pyramid.config.Configurator.add_traverser`,
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`: