openstack/python-keystoneclient
Code Issues Proposed changes

Improve docs for v3 users

Browse Source 
In preparation to add functional tests for v3 users, this change
proposes to detail the method docs, because the tests need to be
based on them.

Change-Id: I8f725ca8071e592fdf932bf83f72eaebf588bb6b
This commit is contained in:
Samuel de Medeiros Queiroz
2016-04-13 11:16:02 -03:00
committed by Steve Martinelli
parent 31a9059460
commit b170fa4564
1 changed files with 121 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
keystoneclient/v3/users.py
View File

@@ -55,13 +55,33 @@ class UserManager(base.CrudManager):
default_project=None, **kwargs):
"""Create a user.
:param str name: the name of the user.
:param domain: the domain of the user.
:type domain: str or :class:`keystoneclient.v3.domains.Domain`
:param project: the default project of the user.
(deprecated, see warning below)
:type project: str or :class:`keystoneclient.v3.projects.Project`
:param str password: the password for the user.
:param str email: the email address of the user.
:param str description: a description of the user.
:param bool enabled: whether the user is enabled.
:param default_project: the default project of the user.
:type default_project: str or
:class:`keystoneclient.v3.projects.Project`
:param kwargs: any other attribute provided will be passed to the
server.
:returns: the created user returned from server.
:rtype: :class:`keystoneclient.v3.users.User`
.. warning::
The project argument is deprecated as of the 1.7.0 release in favor
of default_project and may be removed in the 2.0.0 release.
The project argument is deprecated as of the 1.7.0 release in favor
of default_project and may be removed in the 2.0.0 release.
If both default_project and project is provided, the default_project
will be used.
If both default_project and project is provided, the default_project
will be used.
"""
default_project_id = base.getid(default_project) or base.getid(project)
user_data = base.filter_none(name=name,
@@ -83,19 +103,30 @@ class UserManager(base.CrudManager):
**kwargs):
"""List users.
If project, domain or group are provided, then filter
users with those attributes.
:param project: the default project of the users to be filtered on.
(deprecated, see warning below)
:type project: str or :class:`keystoneclient.v3.projects.Project`
:param domain: the domain of the users to be filtered on.
:type domain: str or :class:`keystoneclient.v3.domains.Domain`
:param group: the group in which the users are member of.
:type group: str or :class:`keystoneclient.v3.groups.Group`
:param default_project: the default project of the users to be filtered
on.
:type default_project: str or
:class:`keystoneclient.v3.projects.Project`
:param kwargs: any other attribute provided will filter users on.
If ``**kwargs`` are provided, then filter users with
attributes matching ``**kwargs``.
:returns: a list of users.
:rtype: list of :class:`keystoneclient.v3.users.User`.
.. warning::
The project argument is deprecated as of the 1.7.0 release in favor
of default_project and may be removed in the 2.0.0 release.
If both default_project and project is provided, the default_project
will be used.
If both default_project and project is provided, the default_project
will be used.
"""
default_project_id = base.getid(default_project) or base.getid(project)
if group:
@@ -110,6 +141,15 @@ class UserManager(base.CrudManager):
**kwargs)
def get(self, user):
"""Retrieve a user.
:param user: the user to be retrieved from the server.
:type user: str or :class:`keystoneclient.v3.users.User`
:returns: the specified user returned from server.
:rtype: :class:`keystoneclient.v3.users.User`
"""
return super(UserManager, self).get(
user_id=base.getid(user))
@@ -121,13 +161,34 @@ class UserManager(base.CrudManager):
default_project=None, **kwargs):
"""Update a user.
:param user: the user to be updated on the server.
:type user: str or :class:`keystoneclient.v3.users.User`
:param str name: the new name of the user.
:param domain: the new domain of the user.
:type domain: str or :class:`keystoneclient.v3.domains.Domain`
:param project: the new default project of the user.
(deprecated, see warning below)
:type project: str or :class:`keystoneclient.v3.projects.Project`
:param str password: the new password of the user.
:param str email: the new email of the user.
:param str description: the newdescription of the user.
:param bool enabled: whether the user is enabled.
:param default_project: the new default project of the user.
:type default_project: str or
:class:`keystoneclient.v3.projects.Project`
:param kwargs: any other attribute provided will be passed to server.
:returns: the updated user returned from server.
:rtype: :class:`keystoneclient.v3.users.User`
.. warning::
The project argument is deprecated as of the 1.7.0 release in favor
of default_project and may be removed in the 2.0.0 release.
The project argument is deprecated as of the 1.7.0 release in favor
of default_project and may be removed in the 2.0.0 release.
If both default_project and project is provided, the default_project
will be used.
If both default_project and project is provided, the default_project
will be used.
"""
default_project_id = base.getid(default_project) or base.getid(project)
user_data = base.filter_none(name=name,
@@ -146,7 +207,14 @@ class UserManager(base.CrudManager):
log=False)
def update_password(self, old_password, new_password):
"""Update the password for the user the token belongs to."""
"""Update the password for the user the token belongs to.
:param str old_password: the user's old password
:param str new_password: the user's new password
:returns: 204 No Content.
"""
if not (old_password and new_password):
msg = _('Specify both the current password and a new password')
raise exceptions.ValidationError(msg)
@@ -163,6 +231,16 @@ class UserManager(base.CrudManager):
return self._update(base_url, params, method='POST', log=False)
def add_to_group(self, user, group):
"""Add the specified user as a member of the specified group.
:param user: the user to be added to the group.
:type user: str or :class:`keystoneclient.v3.users.User`
:param group: the group to put the user in.
:type group: str or :class:`keystoneclient.v3.groups.Group`
:returns: 204 No Content.
"""
self._require_user_and_group(user, group)
base_url = '/groups/%s' % base.getid(group)
@@ -171,6 +249,16 @@ class UserManager(base.CrudManager):
user_id=base.getid(user))
def check_in_group(self, user, group):
"""Check if the specified user is a member of the specified group.
:param user: the user to be verified in the group.
:type user: str or :class:`keystoneclient.v3.users.User`
:param group: the group to check the user in.
:type group: str or :class:`keystoneclient.v3.groups.Group`
:returns: 204 No Content.
"""
self._require_user_and_group(user, group)
base_url = '/groups/%s' % base.getid(group)
@@ -179,6 +267,16 @@ class UserManager(base.CrudManager):
user_id=base.getid(user))
def remove_from_group(self, user, group):
"""Remove the specified user from the specified group.
:param user: the user to be removed from the group.
:type user: str or :class:`keystoneclient.v3.users.User`
:param group: the group to remove the user from.
:type group: str or :class:`keystoneclient.v3.groups.Group`
:returns: 204 No Content.
"""
self._require_user_and_group(user, group)
base_url = '/groups/%s' % base.getid(group)
@@ -187,5 +285,13 @@ class UserManager(base.CrudManager):
user_id=base.getid(user))
def delete(self, user):
"""Delete a user.
:param user: the user to be deleted on the server.
:type user: str or :class:`keystoneclient.v3.users.User`
:returns: 204 No Content.
"""
return super(UserManager, self).delete(
user_id=base.getid(user))