Merge branch 'feature.security-apis-on-request'

5 files changed, 35 insertions, 36 deletions

diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index b1bb611e5..34d75f2cc 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -201,7 +201,7 @@ location-aware resources.  These APIs include (but are not limited to)
 :func:`~pyramid.traversal.resource_path`,
 :func:`~pyramid.traversal.resource_path_tuple`, or
 :func:`~pyramid.traversal.traverse`, :func:`~pyramid.traversal.virtual_root`,
-and (usually) :func:`~pyramid.security.has_permission` and
+and (usually) :meth:`~pyramid.request.Request.has_permission` and
 :func:`~pyramid.security.principals_allowed_by_permission`.
 
 In general, since so much :app:`Pyramid` infrastructure depends on
@@ -695,10 +695,10 @@ The APIs provided by :ref:`location_module` are used against resources.
 These can be used to walk down a resource tree, or conveniently locate one
 resource "inside" another.
 
-Some APIs in :ref:`security_module` accept a resource object as a parameter.
-For example, the :func:`~pyramid.security.has_permission` API accepts a
+Some APIs on the :class:`pyramid.request.Request` accept a resource object as a parameter.
+For example, the :meth:`~pyramid.request.Request.has_permission` API accepts a
 resource object as one of its arguments; the ACL is obtained from this
-resource or one of its ancestors.  Other APIs in the :mod:`pyramid.security`
-module also accept :term:`context` as an argument, and a context is always a
-resource.
+resource or one of its ancestors.  Other security related APIs on the 
+:class:`pyramid.request.Request` class also accept :term:`context` as an argument, 
+and a context is always a resource.
 
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index e85ed823a..9e6fb6c82 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -550,7 +550,7 @@ also contain security debugging information in its body.
 Debugging Imperative Authorization Failures
 -------------------------------------------
 
-The :func:`pyramid.security.has_permission` API is used to check
+The :meth:`pyramid.request.Request.has_permission` API is used to check
 security within view functions imperatively.  It returns instances of
 objects that are effectively booleans.  But these objects are not raw
 ``True`` or ``False`` objects, and have information attached to them
@@ -563,7 +563,7 @@ one of :data:`pyramid.security.ACLAllowed`,
 ``msg`` attribute, which is a string indicating why the permission was
 denied or allowed.  Introspecting this information in the debugger or
 via print statements when a call to
-:func:`~pyramid.security.has_permission` fails is often useful.
+:meth:`~pyramid.request.Request.has_permission` fails is often useful.
 
 .. index::
    single: authentication policy (creating)
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index 88d6904c7..5a5bf8fad 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -214,11 +214,10 @@ function.
 .. code-block:: python
    :linenos:
 
-   from pyramid.security import has_permission
    from pyramid.httpexceptions import HTTPForbidden
 
    def view_fn(request):
-       if not has_permission('edit', request.context, request):
+       if request.has_permission('edit'):
            raise HTTPForbidden
        return {'greeting':'hello'}
 
@@ -229,15 +228,16 @@ function.
    otherwise it would fail when run normally.
 
 Without doing anything special during a unit test, the call to
-:func:`~pyramid.security.has_permission` in this view function will always
-return a ``True`` value.  When a :app:`Pyramid` application starts normally,
-it will populate a :term:`application registry` using :term:`configuration
-declaration` calls made against a :term:`Configurator`.  But if this
-application registry is not created and populated (e.g. by initializing the
-configurator with an authorization policy), like when you invoke application
-code via a unit test, :app:`Pyramid` API functions will tend to either fail
-or return default results.  So how do you test the branch of the code in this
-view function that raises :exc:`~pyramid.httpexceptions.HTTPForbidden`?
+:meth:`~pyramid.request.Request.has_permission` in this view function will
+always return a ``True`` value.  When a :app:`Pyramid` application starts
+normally, it will populate a :term:`application registry` using
+:term:`configuration declaration` calls made against a :term:`Configurator`.
+But if this application registry is not created and populated (e.g. by
+initializing the configurator with an authorization policy), like when you
+invoke application code via a unit test, :app:`Pyramid` API functions will tend
+to either fail or return default results.  So how do you test the branch of the
+code in this view function that raises
+:exc:`~pyramid.httpexceptions.HTTPForbidden`?
 
 The testing API provided by :app:`Pyramid` allows you to simulate various
 application registry registrations for use under a unit testing framework
@@ -287,12 +287,12 @@ 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.
 
-We then create a :class:`pyramid.testing.DummyRequest` object which simulates
-a 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, :func:`pyramid.security.has_permission` will call the
-"dummy" authentication policy we've registered through
+We then create a :class:`pyramid.testing.DummyRequest` object which simulates a
+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
 :meth:`~pyramid.config.Configurator.testing_securitypolicy`, which denies
 access.  We check that the view function raises a
 :exc:`~pyramid.httpexceptions.HTTPForbidden` error.
diff --git a/docs/narr/threadlocals.rst b/docs/narr/threadlocals.rst
index a90ee4905..afe56de3e 100644
--- a/docs/narr/threadlocals.rst
+++ b/docs/narr/threadlocals.rst
@@ -29,17 +29,16 @@ of a thread local or a global is usually just a way to avoid passing
 some value around between functions, which is itself usually a very
 bad idea, at least if code readability counts as an important concern.
 
-For historical reasons, however, thread local variables are indeed
-consulted by various :app:`Pyramid` API functions.  For example,
-the implementation of the :mod:`pyramid.security` function named
-:func:`~pyramid.security.authenticated_userid` retrieves the thread
-local :term:`application registry` as a matter of course to find an
+For historical reasons, however, thread local variables are indeed consulted by
+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
-: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".
+: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".
 
 When they need to do so, :app:`Pyramid` internals use two API
 functions to retrieve the :term:`request` and :term:`application
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 7c76116f7..e5a2c1ade 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -435,7 +435,7 @@ configured view.
 
   If specified, this value should be a :term:`principal` identifier or a
   sequence of principal identifiers.  If the
-  :func:`pyramid.security.effective_principals` method indicates that every
+  :meth:`pyramid.request.Request.effective_principals` method indicates that every
   principal named in the argument list is present in the current request, this
   predicate will return True; otherwise it will return False.  For example:
   ``effective_principals=pyramid.security.Authenticated`` or