Security APIs on pyramid.request.Request

The pyramid.security Authorization API function has_permission is made available on the request.
The pyramid.security Authentication API functions are now available as
properties (unauthenticated_userid, authenticated_userid, effective_principals)
and methods (remember_userid, forget_userid) on pyramid.request.Request.

Backwards compatibility:
    For each of the APIs moved to request method or property,
    the original API in the pyramid.security module proxies to the request.

Reworked tests to check module level b/c wrappers call through to mixins for each API.
Tests that check no reg on request now do the right thing.
Use a response callback to set the request headers for forget_userid and remember_userid.

Update docs.

Attempt to improve a documentation section referencing the pyramid.security.has_permission
function in docs/narr/resources.rst

Ensures backwards compatiblity for `pyramid.security.forget`
and `pyramid.security.remember`.

CHANGES.txt

@@ -4,6 +4,14 @@ Unreleased
 Features
 --------
 
+- The :mod:``pyramid.security`` authentication API methods should now be 
+  accessed via the request. The ``pyramid.security`` authoriztion API function 
+  :meth:`has_permission` should now be accessed via the request.
+  The methods :meth:``pyramid.request.Request.forget_userid``, 
+  meth:``pyramid.request.Request.remember_userid`` now automatically 
+  set the headers on the response, as returned by the corrosponding 
+  method of the current request's :term:``authentication policy``.
+
 - Pyramid's console scripts (``pserve``, ``pviews``, etc) can now be run
   directly, allowing custom arguments to be sent to the python interpreter
   at runtime. For example::

CONTRIBUTORS.txt

@@ -224,3 +224,5 @@ Contributors
 - Doug Hellmann, 2013/09/06
 
 - Karl O. Pinc, 2013/09/27
+
+- Matthew Russell, 2013/10/14

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.
 

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)

docs/narr/testing.rst

@@ -229,7 +229,7 @@ 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
+: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

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

docs/tutorials/wiki/authorization.rst

@@ -207,8 +207,8 @@ need to be added.)
 
 :meth:`~pyramid.view.forbidden_view_config` will be used
 to customize the default 403 Forbidden page.
-:meth:`~pyramid.security.remember` and
-:meth:`~pyramid.security.forget` help to create and
+:meth:`~pyramid.request.Request.remember_userid` and
+:meth:`~pyramid.request.Request.forget_userid` help to create and
 expire an auth ticket cookie.
 
 Now add the ``login`` and ``logout`` views:

docs/tutorials/wiki2/authorization.rst

@@ -230,8 +230,8 @@ head of ``tutorial/tutorial/views.py``:
 
 :meth:`~pyramid.view.forbidden_view_config` will be used
 to customize the default 403 Forbidden page.
-:meth:`~pyramid.security.remember` and
-:meth:`~pyramid.security.forget` help to create and
+:meth:`~pyramid.request.Request.remember_userid` and
+:meth:`~pyramid.request.Request.forget_userid` help to create and
 expire an auth ticket cookie.
 
 Now add the ``login`` and ``logout`` views:

pyramid/config/routes.py

@@ -237,7 +237,7 @@ def add_route(self,
 
           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
+          :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:

pyramid/config/testing.py

@@ -47,14 +47,14 @@ def testing_securitypolicy(self, userid=None, groupids=(),
         ``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
-        :func:`pyramid.security.authenticated_userid` or
-        :func:`pyramid.security.effective_principals` APIs are
+        :meth:`pyramid.request.Request.authenticated_userid` or
+        :meth:`pyramid.request.Request.effective_principals` APIs are
         used.
 
         This function is most useful when testing code that uses
-        the APIs named :func:`pyramid.security.has_permission`,
-        :func:`pyramid.security.authenticated_userid`,
-        :func:`pyramid.security.effective_principals`, and
+        the APIs named :meth:`pyramid.request.Request.has_permission`,
+        :meth:`pyramid.request.Request.authenticated_userid`,
+        :meth:`pyramid.request.Request.effective_principals`, and
         :func:`pyramid.security.principals_allowed_by_permission`.
 
         .. versionadded:: 1.4

pyramid/config/views.py

@@ -1017,7 +1017,7 @@ def myview(request):
 
           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
+          :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:

pyramid/request.py

@@ -21,6 +21,7 @@
 from pyramid.decorator import reify
 from pyramid.i18n import LocalizerRequestMixin
 from pyramid.response import Response
+from pyramid.security import AuthenticationAPIMixin, AuthorizationAPIMixin
 from pyramid.url import URLMethodsMixin
 from pyramid.util import InstancePropertyMixin
 
@@ -136,8 +137,13 @@ def _process_finished_callbacks(self):
             callback(self)
 
 @implementer(IRequest)
-class Request(BaseRequest, URLMethodsMixin, CallbackMethodsMixin,
-              InstancePropertyMixin, LocalizerRequestMixin):
+class Request(BaseRequest,
+              URLMethodsMixin,
+              CallbackMethodsMixin,
+              InstancePropertyMixin,
+              LocalizerRequestMixin,
+              AuthenticationAPIMixin,
+              AuthorizationAPIMixin):
     """
     A subclass of the :term:`WebOb` Request class.  An instance of
     this class is created by the :term:`router` and is provided to a