Permalink
Browse files

Bring change log, API docs, and deprecations in line with normal poli…

…cies/processes
  • Loading branch information...
mcdonc committed Oct 28, 2013
1 parent 0f424ae commit 0184b527725cfb634e4d57a1b033450fa8b24502
View
@@ -4,13 +4,34 @@ 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``.
+- Authentication and authorization APIs have been added as as methods of the
+ request: ``request.has_permission``, ``request.forget_userid``, and
+ ``request.remember_userid``.
+
+ ``request.has_permission`` is a method-based alternative to the
+ ``pyramid.security.has_permission`` API and works exactly the same. The
+ older API is now deprecated.
+
+ ``request.forget_userid`` and ``request.remember_userid`` are method-based
+ alternatives to ``pyramid.security.forget`` and
+ ``pyramid.security.remember``. These do not work exacly the same as their
+ function counterparts, however. These methods automatically set the headers
+ returned by the authentication policy on the response, whereas the older
+ function-based APIs returned a sequence of headers and required the caller to
+ set those headers. The older function-based API still works but is now
+ deprecated.
+
+- Property API attributes have been added to the request for easier access to
+ authentication data: ``request.authenticated_userid``,
+ ``request.unauthenticated_userid``, and ``request.effective_principals``.
+
+ These are analogues, respectively, of
+ ``pyramid.security.authenticated_userid``,
+ ``pyramid.security.unauthenticated_userid``, and
+ ``pyramid.security.effective_principals``. They operate exactly the same,
+ except they are attributes of the request instead of functions accepting a
+ request. They are properties, so they cannot be assigned to. The older
+ function-based APIs are now deprecated.
- Pyramid's console scripts (``pserve``, ``pviews``, etc) can now be run
directly, allowing custom arguments to be sent to the python interpreter
@@ -105,6 +126,27 @@ Deprecations
the SignedCookieSessionFactory are not. See
https://github.com/Pylons/pyramid/pull/1142
+- The ``pyramid.security.has_permission`` API is now deprecated. Instead, use
+ the newly-added ``has_permission`` method of the request object.
+
+- The ``pyramid.security.forget`` API is now deprecated. Instead, use
+ the newly-added ``forget_userid`` method of the request object.
+
+- The ``pyramid.security.remember`` API is now deprecated. Instead, use
+ the newly-added ``remember_userid`` method of the request object.
+
+- The ``pyramid.security.effective_principals`` API is now deprecated.
+ Instead, use the newly-added ``effective_principals`` attribute of the
+ request object.
+
+- The ``pyramid.security.authenticated_userid`` API is now deprecated.
+ Instead, use the newly-added ``authenticated_userid`` attribute of the
+ request object.
+
+- The ``pyramid.security.unauthenticated_userid`` API is now deprecated.
+ Instead, use the newly-added ``unauthenticated_userid`` attribute of the
+ request object.
+
1.5a2 (2013-09-22)
==================
View
@@ -11,7 +11,10 @@
:exclude-members: add_response_callback, add_finished_callback,
route_url, route_path, current_route_url,
current_route_path, static_url, static_path,
- model_url, resource_url, set_property
+ model_url, resource_url, set_property,
+ effective_principals, authenticated_userid,
+ unauthenticated_userid, has_permission, forget_userid,
+ remember_userid
.. attribute:: context
@@ -161,6 +164,42 @@
request, the value of this attribute will be ``None``. See
:ref:`matched_route`.
+ .. attribute:: authenticated_userid
+
+ .. versionadded:: 1.5
+
+ A property which returns the userid of the currently authenticated user
+ or ``None`` if there is no :term:`authentication policy` in effect or
+ there is no currently authenticated user. This differs from
+ :meth:`~pyramid.request.Request.unauthenticated_userid`, because the
+ effective authentication policy will have ensured that a record
+ associated with the userid exists in persistent storage; if it has
+ not, this value will be ``None``.
+
+ .. attribute:: unauthenticated_userid
+
+ .. versionadded:: 1.5
+
+ A property which returns a value which represents the *claimed* (not
+ verified) user id of the credentials present in the request. ``None`` if
+ there is no :term:`authentication policy` in effect or there is no user
+ data associated with the current request. This differs from
+ :meth:`~pyramid.request.Request.authenticated_userid`, because the
+ effective authentication policy will not ensure that a record associated
+ with the userid exists in persistent storage. Even if the userid
+ does not exist in persistent storage, this value will be the value
+ of the userid *claimed* by the request data.
+
+ .. attribute:: effective_principals
+
+ .. versionadded:: 1.5
+
+ A property which returns the list of 'effective' :term:`principal`
+ identifiers for this request. This will include the userid of the
+ currently authenticated user if a user is currently authenticated. If no
+ :term:`authentication policy` is in effect, this will return a sequence
+ containing only the :attr:`pyramid.security.Everyone` principal.
+
.. method:: invoke_subrequest(request, use_tweens=False)
.. versionadded:: 1.4a1
@@ -215,6 +254,12 @@
request provided by e.g. the ``pshell`` environment. For more
information, see :ref:`subrequest_chapter`.
+ .. automethod:: remember_userid
+
+ .. automethod:: forget_userid
+
+ .. automethod:: has_permission
+
.. automethod:: add_response_callback
.. automethod:: add_finished_callback
View
@@ -237,10 +237,10 @@ def add_route(self,
If specified, this value should be a :term:`principal` identifier or
a sequence of principal identifiers. If the
- :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:
+ :attr:`pyramid.request.Request.effective_principals` property
+ 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
``effective_principals=('fred', 'group:admins')``.
@@ -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
- :meth:`pyramid.request.Request.authenticated_userid` or
- :meth:`pyramid.request.Request.effective_principals` APIs are
+ :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`,
- :meth:`pyramid.request.Request.authenticated_userid`,
- :meth:`pyramid.request.Request.effective_principals`, and
+ :attr:`pyramid.request.Request.authenticated_userid`,
+ :attr:`pyramid.request.Request.effective_principals`, and
:func:`pyramid.security.principals_allowed_by_permission`.
.. versionadded:: 1.4
View
@@ -1017,10 +1017,10 @@ def myview(request):
If specified, this value should be a :term:`principal` identifier or
a sequence of principal identifiers. If the
- :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:
+ :attr:`pyramid.request.Request.effective_principals` property
+ 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
``effective_principals=('fred', 'group:admins')``.
View
@@ -21,7 +21,10 @@
from pyramid.decorator import reify
from pyramid.i18n import LocalizerRequestMixin
from pyramid.response import Response
-from pyramid.security import AuthenticationAPIMixin, AuthorizationAPIMixin
+from pyramid.security import (
+ AuthenticationAPIMixin,
+ AuthorizationAPIMixin,
+ )
from pyramid.url import URLMethodsMixin
from pyramid.util import InstancePropertyMixin
@@ -137,13 +140,15 @@ def _process_finished_callbacks(self):
callback(self)
@implementer(IRequest)
-class Request(BaseRequest,
- URLMethodsMixin,
- CallbackMethodsMixin,
- InstancePropertyMixin,
- LocalizerRequestMixin,
- AuthenticationAPIMixin,
- AuthorizationAPIMixin):
+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
Oops, something went wrong.

0 comments on commit 0184b52

Please sign in to comment.