Skip to content

feat: add feature to get inherited member for project/group #1187

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed

feat: add feature to get inherited member for project/group #1187

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1b62c2e
feat: add feature to get inherited member for project/group
Sep 12, 2020
50f4b9c
test: update test which lists all members including inherited
Sep 12, 2020
565151a
chore: revert "test: update test which lists all members including in…
Sep 14, 2020
55cdad8
feat: add feature to get inherited member for project/group
Sep 14, 2020
323c279
test: add one more test which lists all members including inherited
Sep 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions docs/gl_objects/groups.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,27 +221,35 @@ 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


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,
Expand Down
15 changes: 12 additions & 3 deletions docs/gl_objects/projects.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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':
Expand Down
38 changes: 38 additions & 0 deletions gitlab/mixins.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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]
60 changes: 12 additions & 48 deletions gitlab/v4/objects/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -1394,6 +1375,7 @@ class Group(SaveMixin, ObjectDeleteMixin, RESTObject):
("issues", "GroupIssueManager"),
("labels", "GroupLabelManager"),
("members", "GroupMemberManager"),
("members_all", "GroupMemberAllManager"),
("mergerequests", "GroupMergeRequestManager"),
("milestones", "GroupMilestoneManager"),
("notificationsettings", "GroupNotificationSettingsManager"),
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -4595,6 +4558,7 @@ class Project(SaveMixin, ObjectDeleteMixin, RESTObject):
("issues", "ProjectIssueManager"),
("labels", "ProjectLabelManager"),
("members", "ProjectMemberManager"),
("members_all", "ProjectMemberAllManager"),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For me the dilemma here is: members_all/ProjectMemberAllManager or all_members/ProjectAllMemberManager 😁 WDYT @max-wittig? all_members (or allmembers) sounds more natural to me. On the other hand members_all does follow the URL segments.

Just asking because this pattern can be a precedent for improving other /all endpoints (e.g. #593) so it might have further reach.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I spent a few minutes scanning the GitLab API and looks GitLab doesn't tend to make its addresses natural. Anyway, I am not a python Pro, final conclusion is up to you.

("mergerequests", "ProjectMergeRequestManager"),
("milestones", "ProjectMilestoneManager"),
("notes", "ProjectNoteManager"),
Expand Down
3 changes: 2 additions & 1 deletion tools/python_test_v4.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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())
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
assert len(group1.members_all.list())
assert len(group1.members.all()) # Deprecated
assert len(group1.members_all.list())

As you can see in the test you've had to change in 50f4b9c, this would break the existing behavior for anyone who has relied on .all() so far. I think it might be better to preserve the old behavior with a DeprecationWarning and remove it later with a major release.

Maybe that can be done (temporarily) with a ListAllMixin that contains the method, to avoid copy/pasting. Just need to make sure to register_custom_action for both Project and Group members.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I rolled back the test case group1.members.all() and added MemberAllMixin with register_custom_action and DeprecationWarning , ListAllMixin sounds very general, we won't use ListAllMixin somewhere I guess.

member = group1.members.get(user2.id)
member.access_level = gitlab.const.OWNER_ACCESS
member.save()
Expand Down