Merge "Improve docs for v3 users"

keystoneclient/v3/users.py

@@ -57,6 +57,25 @@ 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
@@ -64,6 +83,7 @@ class UserManager(base.CrudManager):
 
           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,
@@ -85,11 +105,21 @@ class UserManager(base.CrudManager):
              **kwargs):
         """List users.
 
-        If project, domain or group are provided, then filter
+        :param project: the default project of the users to be filtered on.
-        users with those attributes.
+                        (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
+        :returns: a list of users.
-        attributes matching ``**kwargs``.
+        :rtype: list of :class:`keystoneclient.v3.users.User`.
 
         .. warning::
 
@@ -98,6 +128,7 @@ class UserManager(base.CrudManager):
 
           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:
@@ -112,6 +143,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))
 
@@ -123,6 +163,26 @@ 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
@@ -130,6 +190,7 @@ class UserManager(base.CrudManager):
 
           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,
@@ -148,7 +209,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)
@@ -165,6 +233,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)
@@ -173,6 +251,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)
@@ -181,6 +269,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)
@@ -189,5 +287,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))