diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst index 199847d9f..009416f04 100644 --- a/docs/gl_objects/groups.rst +++ b/docs/gl_objects/groups.rst @@ -221,7 +221,9 @@ Reference + :class:`gitlab.v4.objects.GroupMember` + :class:`gitlab.v4.objects.GroupMemberManager` + + :class:`gitlab.v4.objects.GroupMemberAllManager` + :attr:`gitlab.v4.objects.Group.members` + + :attr:`gitlab.v4.objects.Group.members_all` * GitLab API: https://docs.gitlab.com/ce/api/groups.html @@ -229,19 +231,25 @@ Reference Examples -------- -List group members:: +List only direct group members:: members = group.members.list() List the group members recursively (including inherited members through ancestor groups):: - members = group.members.all(all=True) + members = group.members.all(all=True) # Deprecated + # or + members = group.members_all.list(all=True) -Get a group member:: +Get only direct group member:: members = group.members.get(member_id) +Get a member of a group, including members inherited through ancestor groups:: + + members = group.members_all.get(member_id) + Add a member to the group:: member = group.members.create({'user_id': user_id, diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst index 61383e451..4b28b6346 100644 --- a/docs/gl_objects/projects.rst +++ b/docs/gl_objects/projects.rst @@ -502,30 +502,39 @@ Reference + :class:`gitlab.v4.objects.ProjectMember` + :class:`gitlab.v4.objects.ProjectMemberManager` + + :class:`gitlab.v4.objects.ProjectMemberAllManager` + :attr:`gitlab.v4.objects.Project.members` + + :attr:`gitlab.v4.objects.Project.members_all` * GitLab API: https://docs.gitlab.com/ce/api/members.html Examples -------- -List the project members:: +List only direct project members:: members = project.members.list() List the project members recursively (including inherited members through ancestor groups):: - members = project.members.all(all=True) + members = project.members.all(all=True) # Deprecated + # or + members = project.members_all.list(all=True) Search project members matching a query string:: members = project.members.list(query='bar') -Get a single project member:: +Get only direct project member:: member = project.members.get(user_id) +Get a member of a project, including members inherited through ancestor groups:: + + members = project.members_all.get(member_id) + + Add a project member:: member = project.members.create({'user_id': user.id, 'access_level': diff --git a/gitlab/mixins.py b/gitlab/mixins.py index 9c00c324d..6bf6ea3bd 100644 --- a/gitlab/mixins.py +++ b/gitlab/mixins.py @@ -22,6 +22,8 @@ from gitlab import types as g_types from gitlab import utils +import warnings + class GetMixin(object): @exc.on_http_error(exc.GitlabGetError) @@ -662,3 +664,39 @@ def render(self, link_url, image_url, **kwargs): path = "%s/render" % self.path data = {"link_url": link_url, "image_url": image_url} return self.gitlab.http_get(path, data, **kwargs) + + +class MemberAllMixin(object): + """This mixin is deprecated.""" + + @cli.register_custom_action(("GroupMemberManager", "ProjectMemberManager")) + @exc.on_http_error(exc.GitlabListError) + def all(self, **kwargs): + """List all the members, included inherited ones. + + This Method is deprecated. + + Args: + all (bool): If True, return all the items, without pagination + per_page (int): Number of items to retrieve per request + page (int): ID of the page to return (starts with page 1) + as_list (bool): If set to False and no pagination option is + defined, return a generator instead of a list + **kwargs: Extra options to send to the server (e.g. sudo) + + Raises: + GitlabAuthenticationError: If authentication is not correct + GitlabListError: If the list could not be retrieved + + Returns: + RESTObjectList: The list of members + """ + + warnings.warn( + "The all() method for this object is deprecated " + "and will be removed in a future version.", + DeprecationWarning, + ) + path = "%s/all" % self.path + obj = self.gitlab.http_list(path, **kwargs) + return [self._obj_cls(self, item) for item in obj] diff --git a/gitlab/v4/objects/__init__.py b/gitlab/v4/objects/__init__.py index 016caece9..f6094b6be 100644 --- a/gitlab/v4/objects/__init__.py +++ b/gitlab/v4/objects/__init__.py @@ -1163,37 +1163,18 @@ class GroupMember(SaveMixin, ObjectDeleteMixin, RESTObject): _short_print_attr = "username" -class GroupMemberManager(CRUDMixin, RESTManager): +class GroupMemberManager(MemberAllMixin, CRUDMixin, RESTManager): _path = "/groups/%(group_id)s/members" _obj_cls = GroupMember _from_parent_attrs = {"group_id": "id"} _create_attrs = (("access_level", "user_id"), ("expires_at",)) _update_attrs = (("access_level",), ("expires_at",)) - @cli.register_custom_action("GroupMemberManager") - @exc.on_http_error(exc.GitlabListError) - def all(self, **kwargs): - """List all the members, included inherited ones. - - Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is - defined, return a generator instead of a list - **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabListError: If the list could not be retrieved - - Returns: - RESTObjectList: The list of members - """ - - path = "%s/all" % self.path - obj = self.gitlab.http_list(path, **kwargs) - return [self._obj_cls(self, item) for item in obj] +class GroupMemberAllManager(RetrieveMixin, RESTManager): + _path = "/groups/%(group_id)s/members/all" + _obj_cls = GroupMember + _from_parent_attrs = {"group_id": "id"} class GroupMergeRequest(RESTObject): @@ -1394,6 +1375,7 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject): ("issues", "GroupIssueManager"), ("labels", "GroupLabelManager"), ("members", "GroupMemberManager"), + ("members_all", "GroupMemberAllManager"), ("mergerequests", "GroupMergeRequestManager"), ("milestones", "GroupMilestoneManager"), ("notificationsettings", "GroupNotificationSettingsManager"), @@ -2831,37 +2813,18 @@ class ProjectMember(SaveMixin, ObjectDeleteMixin, RESTObject): _short_print_attr = "username" -class ProjectMemberManager(CRUDMixin, RESTManager): +class ProjectMemberManager(MemberAllMixin, CRUDMixin, RESTManager): _path = "/projects/%(project_id)s/members" _obj_cls = ProjectMember _from_parent_attrs = {"project_id": "id"} _create_attrs = (("access_level", "user_id"), ("expires_at",)) _update_attrs = (("access_level",), ("expires_at",)) - @cli.register_custom_action("ProjectMemberManager") - @exc.on_http_error(exc.GitlabListError) - def all(self, **kwargs): - """List all the members, included inherited ones. - - Args: - all (bool): If True, return all the items, without pagination - per_page (int): Number of items to retrieve per request - page (int): ID of the page to return (starts with page 1) - as_list (bool): If set to False and no pagination option is - defined, return a generator instead of a list - **kwargs: Extra options to send to the server (e.g. sudo) - Raises: - GitlabAuthenticationError: If authentication is not correct - GitlabListError: If the list could not be retrieved - - Returns: - RESTObjectList: The list of members - """ - - path = "%s/all" % self.path - obj = self.gitlab.http_list(path, **kwargs) - return [self._obj_cls(self, item) for item in obj] +class ProjectMemberAllManager(RetrieveMixin, RESTManager): + _path = "/projects/%(project_id)s/members/all" + _obj_cls = ProjectMember + _from_parent_attrs = {"project_id": "id"} class ProjectNote(RESTObject): @@ -4595,6 +4558,7 @@ class Project(SaveMixin, ObjectDeleteMixin, RESTObject): ("issues", "ProjectIssueManager"), ("labels", "ProjectLabelManager"), ("members", "ProjectMemberManager"), + ("members_all", "ProjectMemberAllManager"), ("mergerequests", "ProjectMergeRequestManager"), ("milestones", "ProjectMilestoneManager"), ("notes", "ProjectNoteManager"), diff --git a/tools/python_test_v4.py b/tools/python_test_v4.py index 7ff97b67f..11371f95c 100644 --- a/tools/python_test_v4.py +++ b/tools/python_test_v4.py @@ -312,7 +312,8 @@ group1.members.delete(user1.id) assert len(group1.members.list()) == 2 -assert len(group1.members.all()) +assert len(group1.members.all()) # Deprecated +assert len(group1.members_all.list()) member = group1.members.get(user2.id) member.access_level = gitlab.const.OWNER_ACCESS member.save()