Merge pull request #3620 from luhn/identity-rename

Rename `ISecurityPolicy.authenticated_identity` to `identity`

docs/api/request.rst

@@ -175,8 +175,8 @@
  .. deprecated:: 2.0
 
  ``unauthenticated_userid`` has been deprecated in version 2.0. Use
- :attr:`authenticated_userid` or :attr:`authenticated_identity`
- instead. See :ref:`upgrading_auth` for more information.
+ :attr:`authenticated_userid` or :attr:`identity` instead. See
+ :ref:`upgrading_auth` for more information.
 
  A property which returns a value which represents the *claimed* (not
  verified) :term:`userid` of the credentials present in the

docs/narr/security.rst

@@ -69,7 +69,7 @@ A simple security policy might look like the following:
  from pyramid.security import Allowed, Denied
 
  class SessionSecurityPolicy:
- def authenticated_identity(self, request):
+ def identity(self, request):
  """ Return app-specific user object. """
  userid = request.session.get('userid')
  if userid is None:
@@ -78,14 +78,14 @@ A simple security policy might look like the following:
 
  def authenticated_userid(self, request):
  """ Return a string ID for the user. """
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is None:
  return None
  return string(identity.id)
 
  def permits(self, request, context, permission):
  """ Allow access to everything if signed in. """
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is not None:
  return Allowed('User is signed in.')
  else:
@@ -144,7 +144,7 @@ For example, our above security policy can leverage these helpers like so:
  def __init__(self):
  self.helper = SessionAuthenticationHelper()
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  """ Return app-specific user object. """
  userid = self.helper.authenticated_userid(request)
  if userid is None:
@@ -153,14 +153,14 @@ For example, our above security policy can leverage these helpers like so:
 
  def authenticated_userid(self, request):
  """ Return a string ID for the user. """
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is None:
  return None
  return str(identity.id)
 
  def permits(self, request, context, permission):
  """ Allow access to everything if signed in. """
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is not None:
  return Allowed('User is signed in.')
  else:
@@ -249,7 +249,7 @@ might look like so:
 
  class SecurityPolicy:
  def permits(self, request, context, permission):
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
 
  if identity is None:
  return Denied('User is not signed in.')

docs/quick_tutorial/authentication/tutorial/security.py

@@ -19,13 +19,13 @@ class SecurityPolicy:
  def __init__(self, secret):
  self.authtkt = AuthTktCookieHelper(secret=secret)
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  identity = self.authtkt.identify(request)
  if identity is not None and identity['userid'] in USERS:
  return identity
 
  def authenticated_userid(self, request):
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is not None:
  return identity['userid']
 

docs/quick_tutorial/authorization/tutorial/security.py

@@ -26,13 +26,13 @@ def __init__(self, secret):
  self.authtkt = AuthTktCookieHelper(secret=secret)
  self.acl = ACLHelper()
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  identity = self.authtkt.identify(request)
  if identity is not None and identity['userid'] in USERS:
  return identity
 
  def authenticated_userid(self, request):
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is not None:
  return identity['userid']
 

docs/tutorials/wiki/authorization.rst

@@ -88,7 +88,7 @@ The security policy controls several aspects of authentication and authorization
 Identifying logged-in users
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``MySecurityPolicy.authenticated_identity`` method inspects the ``request`` and determines if it came from an authenticated user.
+The ``MySecurityPolicy.identity`` method inspects the ``request`` and determines if it came from an authenticated user.
 It does this by utilizing the :class:`pyramid.authentication.AuthTktCookieHelper` class which stores the :term:`identity` in a cryptographically-signed cookie.
 If a ``request`` does contain an identity, then we perform a final check to determine if the user is valid in our current ``USERS`` store.
 

docs/tutorials/wiki/src/authorization/tutorial/security.py

@@ -28,13 +28,13 @@ def __init__(self, secret):
  self.authtkt = AuthTktCookieHelper(secret)
  self.acl = ACLHelper()
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  identity = self.authtkt.identify(request)
  if identity is not None and identity['userid'] in USERS:
  return identity
 
  def authenticated_userid(self, request):
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is not None:
  return identity['userid']
 
@@ -50,7 +50,7 @@ def permits(self, request, context, permission):
 
  def effective_principals(self, request):
  principals = [Everyone]
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is not None:
  principals.append(Authenticated)
  principals.append('u:' + identity['userid'])

docs/tutorials/wiki/src/tests/tutorial/security.py

@@ -28,13 +28,13 @@ def __init__(self, secret):
  self.authtkt = AuthTktCookieHelper(secret)
  self.acl = ACLHelper()
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  identity = self.authtkt.identify(request)
  if identity is not None and identity['userid'] in USERS:
  return identity
 
  def authenticated_userid(self, request):
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is not None:
  return identity['userid']
 
@@ -50,7 +50,7 @@ def permits(self, request, context, permission):
 
  def effective_principals(self, request):
  principals = [Everyone]
- identity = self.authenticated_identity(request)
+ identity = self.identity(request)
  if identity is not None:
  principals.append(Authenticated)
  principals.append('u:' + identity['userid'])

docs/tutorials/wiki2/authentication.rst

@@ -64,7 +64,7 @@ Identifying the current user is done in a few steps:
 
 #. The result is stored in the ``identity_cache`` which ensures that subsequent invocations return the same identity object for the request.
 
-Finally, :attr:`pyramid.request.Request.authenticated_identity` contains either ``None`` or a ``tutorial.models.User`` instance and that value is aliased to ``request.user`` for convenience in our application.
+Finally, :attr:`pyramid.request.Request.identity` contains either ``None`` or a ``tutorial.models.User`` instance and that value is aliased to ``request.user`` for convenience in our application.
 
 Note the usage of the ``identity_cache`` is optional, but it has several advantages in most scenarios:
 

docs/tutorials/wiki2/src/authentication/tutorial/security.py

@@ -19,11 +19,11 @@ def load_identity(self, request):
  user = request.dbsession.query(models.User).get(userid)
  return user
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  return self.identity_cache.get_or_create(request)
 
  def authenticated_userid(self, request):
- user = self.authenticated_identity(request)
+ user = self.identity(request)
  if user is not None:
  return user.id
 
@@ -41,4 +41,4 @@ def includeme(config):
 
  config.set_security_policy(MySecurityPolicy(settings['auth.secret']))
  config.add_request_method(
- lambda request: request.authenticated_identity, 'user', property=True)
+ lambda request: request.identity, 'user', property=True)

docs/tutorials/wiki2/src/authorization/tutorial/security.py

@@ -25,11 +25,11 @@ def load_identity(self, request):
  user = request.dbsession.query(models.User).get(userid)
  return user
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  return self.identity_cache.get_or_create(request)
 
  def authenticated_userid(self, request):
- user = self.authenticated_identity(request)
+ user = self.identity(request)
  if user is not None:
  return user.id
 
@@ -45,7 +45,7 @@ def permits(self, request, context, permission):
 
  def effective_principals(self, request):
  principals = [Everyone]
- user = self.authenticated_identity(request)
+ user = self.identity(request)
  if user is not None:
  principals.append(Authenticated)
  principals.append('u:' + str(user.id))
@@ -60,4 +60,4 @@ def includeme(config):
 
  config.set_security_policy(MySecurityPolicy(settings['auth.secret']))
  config.add_request_method(
- lambda request: request.authenticated_identity, 'user', property=True)
+ lambda request: request.identity, 'user', property=True)

docs/tutorials/wiki2/src/tests/tutorial/security.py

@@ -25,11 +25,11 @@ def load_identity(self, request):
  user = request.dbsession.query(models.User).get(userid)
  return user
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  return self.identity_cache.get_or_create(request)
 
  def authenticated_userid(self, request):
- user = self.authenticated_identity(request)
+ user = self.identity(request)
  if user is not None:
  return user.id
 
@@ -45,7 +45,7 @@ def permits(self, request, context, permission):
 
  def effective_principals(self, request):
  principals = [Everyone]
- user = self.authenticated_identity(request)
+ user = self.identity(request)
  if user is not None:
  principals.append(Authenticated)
  principals.append('u:' + str(user.id))
@@ -60,4 +60,4 @@ def includeme(config):
 
  config.set_security_policy(MySecurityPolicy(settings['auth.secret']))
  config.add_request_method(
- lambda request: request.authenticated_identity, 'user', property=True)
+ lambda request: request.identity, 'user', property=True)

docs/whatsnew-2.0.rst

@@ -47,7 +47,7 @@ signature.
 
 The new security policy adds the concept of an :term:`identity`, which is an
 object representing the user associated with the current request. The identity
-can be accessed via :attr:`pyramid.request.Request.authenticated_identity`.
+can be accessed via :attr:`pyramid.request.Request.identity`.
 The object can be of any shape, such as a simple ID string or an ORM object.
 
 The concept of :term:`principals <principal>` has been removed; the
@@ -89,10 +89,8 @@ For further documentation on implementing security policies, see
 Behavior of the Legacy System
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Legacy authentication and authorization policies will continue to function as
-normal, as well as all related :class:`pyramid.request.Request` properties.
-The new :attr:`pyramid.request.Request.authenticated_identity` property will
-output the same result as :attr:`pyramid.request.Request.authenticated_userid`.
+Legacy authentication and authorization policies will continue to function as normal, as well as all related :class:`pyramid.request.Request` properties.
+The new :attr:`pyramid.request.Request.identity` property will output the same result as :attr:`pyramid.request.Request.authenticated_userid`.
 
 If using a security policy, :attr:`pyramid.request.Request.unauthenticated_userid` will return the same value as :attr:`pyramid.request.Request.authenticated_userid`.
 :attr:`pyramid.request.Request.effective_principals` will always return a one-element list containing the :data:`pyramid.authorization.Everyone` principal, as there is no equivalent in the new security policy.

src/pyramid/config/testing.py

@@ -32,10 +32,9 @@ def testing_securitypolicy(
  :attr:`pyramid.request.Request.authenticated_userid` will have this
  value as well.
  :type userid: str
- :param identity: If provided, the policy's ``authenticated_identity``
- method will return this value. As a result,
- :attr:`pyramid.request.Request.authenticated_identity`` will have
- this value.
+ :param identity: If provided, the policy's ``identity`` method will
+ return this value. As a result,
+ :attr:`pyramid.request.Request.identity`` will have this value.
  :type identity: object
  :param permissive: If true, the policy will allow access to any user
  for any permission. If false, the policy will deny all access.

src/pyramid/interfaces.py

@@ -113,10 +113,10 @@ def app_iter_range(start, stop):
  """Return a new app_iter built from the response app_iter that
  serves up only the given start:stop range."""
 
- authenticated_identity = Attribute(
- """An object representing the authenticated user, as determined by
- the security policy in use, or ``None`` for unauthenticated requests.
- The object's class and meaning is defined by the security policy."""
+ identity = Attribute(
+ """An object containing authentication information related to the
+ current request. The object's type and meaning is defined by the
+ configured security policy."""
  )
 
  authenticated_userid = Attribute(
@@ -498,7 +498,7 @@ def __call__(self, **kw):
 
 
 class ISecurityPolicy(Interface):
- def authenticated_identity(request):
+ def identity(request):
  """Return the :term:`identity` of the current user. The object can be
  of any shape, such as a simple ID string or an ORM object.
  """

src/pyramid/request.py

@@ -377,7 +377,7 @@ def load_identity(self, request):
  result = ... # do some expensive computations
  return result
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  return self.identity_cache.get_or_create(request)
 
  The cache maintains a weakref to each request and will release the cached

src/pyramid/security.py

@@ -215,7 +215,7 @@ class SecurityAPIMixin:
  """ Mixin for Request class providing auth-related properties. """
 
  @property
- def authenticated_identity(self):
+ def identity(self):
  """
  Return an opaque object identifying the current user or ``None`` if no
  user is authenticated or there is no :term:`security policy` in effect.
@@ -224,7 +224,7 @@ def authenticated_identity(self):
  policy = _get_security_policy(self)
  if policy is None:
  return None
- return policy.authenticated_identity(self)
+ return policy.identity(self)
 
  @property
  def authenticated_userid(self):
@@ -247,7 +247,7 @@ def authenticated_userid(self):
  @property
  def is_authenticated(self):
  """Return ``True`` if a user is authenticated for this request."""
- return self.authenticated_identity is not None
+ return self.authenticated_userid is not None
 
  def has_permission(self, permission, context=None):
  """Given a permission and an optional context, returns an instance of
@@ -287,8 +287,8 @@ def unauthenticated_userid(self):
 
  ``unauthenticated_userid`` does not have an equivalent in the new
  security system. Use :attr:`.authenticated_userid` or
- :attr:`.authenticated_identity` instead.
- See :ref:`upgrading_auth` for more information.
+ :attr:`.identity` instead. See :ref:`upgrading_auth` for more
+ information.
 
  Return an object which represents the *claimed* (not verified) user
  id of the credentials present in the request. ``None`` if there is no
@@ -362,7 +362,7 @@ def _get_authn_policy(self, request):
  def _get_authz_policy(self, request):
  return request.registry.getUtility(IAuthorizationPolicy)
 
- def authenticated_identity(self, request):
+ def identity(self, request):
  return self.authenticated_userid(request)
 
  def authenticated_userid(self, request):

src/pyramid/testing.py

@@ -42,7 +42,7 @@ def __init__(
  forget_result=None,
  ):
  self.userid = userid
- self.identity = identity
+ self._identity = identity
  self.permissive = permissive
  if remember_result is None:
  remember_result = []
@@ -51,8 +51,8 @@ def __init__(
  self.remember_result = remember_result
  self.forget_result = forget_result
 
- def authenticated_identity(self, request):
- return self.identity
+ def identity(self, request):
+ return self._identity
 
  def authenticated_userid(self, request):
  return self.userid

tests/pkgs/securityapp/__init__.py

@@ -3,7 +3,7 @@
 
 
 class SecurityPolicy:
- def authenticated_identity(self, request):
+ def identity(self, request):
  raise NotImplementedError() # pragma: no cover
 
  def authenticated_userid(self, request):