diff --git a/docs/gl_objects/access_requests.rst b/docs/gl_objects/access_requests.rst index e384534fe..f68b70b73 100644 --- a/docs/gl_objects/access_requests.rst +++ b/docs/gl_objects/access_requests.rst @@ -7,11 +7,11 @@ Users can request access to groups and projects. When access is granted the user should be given a numerical access level. The following constants are provided to represent the access levels: -* ``gitlab.const.GUEST_ACCESS``: ``10`` -* ``gitlab.const.REPORTER_ACCESS``: ``20`` -* ``gitlab.const.DEVELOPER_ACCESS``: ``30`` -* ``gitlab.const.MAINTAINER_ACCESS``: ``40`` -* ``gitlab.const.OWNER_ACCESS``: ``50`` +* ``gitlab.const.AccessLevel.GUEST``: ``10`` +* ``gitlab.const.AccessLevel.REPORTER``: ``20`` +* ``gitlab.const.AccessLevel.DEVELOPER``: ``30`` +* ``gitlab.const.AccessLevel.MAINTAINER``: ``40`` +* ``gitlab.const.AccessLevel.OWNER``: ``50`` References ---------- @@ -43,7 +43,7 @@ Create an access request:: Approve an access request:: ar.approve() # defaults to DEVELOPER level - ar.approve(access_level=gitlab.const.MAINTAINER_ACCESS) # explicitly set access level + ar.approve(access_level=gitlab.const.AccessLevel.MAINTAINER.value) # explicitly set access level Deny (delete) an access request:: diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst index 435835f09..807769d3f 100644 --- a/docs/gl_objects/groups.rst +++ b/docs/gl_objects/groups.rst @@ -80,7 +80,7 @@ Remove a group:: Share/unshare the group with a group:: - group.share(group2.id, gitlab.const.DEVELOPER_ACCESS) + group.share(group2.id, gitlab.const.AccessLevel.DEVELOPER.value) group.unshare(group2.id) Import / Export @@ -237,11 +237,11 @@ Group members The following constants define the supported access levels: -* ``gitlab.const.GUEST_ACCESS = 10`` -* ``gitlab.const.REPORTER_ACCESS = 20`` -* ``gitlab.const.DEVELOPER_ACCESS = 30`` -* ``gitlab.const.MAINTAINER_ACCESS = 40`` -* ``gitlab.const.OWNER_ACCESS = 50`` +* ``gitlab.const.AccessLevel.GUEST = 10`` +* ``gitlab.const.AccessLevel.REPORTER = 20`` +* ``gitlab.const.AccessLevel.DEVELOPER = 30`` +* ``gitlab.const.AccessLevel.MAINTAINER = 40`` +* ``gitlab.const.AccessLevel.OWNER = 50`` Reference --------- @@ -284,11 +284,11 @@ Get a member of a group, including members inherited through ancestor groups:: Add a member to the group:: member = group.members.create({'user_id': user_id, - 'access_level': gitlab.const.GUEST_ACCESS}) + 'access_level': gitlab.const.AccessLevel.GUEST.value}) Update a member (change the access level):: - member.access_level = gitlab.const.DEVELOPER_ACCESS + member.access_level = gitlab.const.AccessLevel.DEVELOPER.value member.save() Remove a member from the group:: @@ -316,7 +316,7 @@ LDAP group links Add an LDAP group link to an existing GitLab group:: - group.add_ldap_group_link(ldap_group_cn, gitlab.const.DEVELOPER_ACCESS, 'ldapmain') + group.add_ldap_group_link(ldap_group_cn, gitlab.const.AccessLevel.DEVELOPER.value, 'ldapmain') Remove a link:: diff --git a/docs/gl_objects/notifications.rst b/docs/gl_objects/notifications.rst index 8d8d9c060..8d1667fde 100644 --- a/docs/gl_objects/notifications.rst +++ b/docs/gl_objects/notifications.rst @@ -5,12 +5,12 @@ Notification settings You can define notification settings globally, for groups and for projects. Valid levels are defined as constants: -* ``gitlab.const.NOTIFICATION_LEVEL_DISABLED`` -* ``gitlab.const.NOTIFICATION_LEVEL_PARTICIPATING`` -* ``gitlab.const.NOTIFICATION_LEVEL_WATCH`` -* ``gitlab.const.NOTIFICATION_LEVEL_GLOBAL`` -* ``gitlab.const.NOTIFICATION_LEVEL_MENTION`` -* ``gitlab.const.NOTIFICATION_LEVEL_CUSTOM`` +* ``gitlab.const.NotificationLevel.DISABLED`` +* ``gitlab.const.NotificationLevel.PARTICIPATING`` +* ``gitlab.const.NotificationLevel.WATCH`` +* ``gitlab.const.NotificationLevel.GLOBAL`` +* ``gitlab.const.NotificationLevel.MENTION`` +* ``gitlab.const.NotificationLevel.CUSTOM`` You get access to fine-grained settings if you use the ``NOTIFICATION_LEVEL_CUSTOM`` level. @@ -47,10 +47,10 @@ Get the notifications settings:: Update the notifications settings:: # use a predefined level - settings.level = gitlab.const.NOTIFICATION_LEVEL_WATCH + settings.level = gitlab.const.NotificationLevel.WATCH.value # create a custom setup - settings.level = gitlab.const.NOTIFICATION_LEVEL_CUSTOM + settings.level = gitlab.const.NotificationLevel.CUSTOM.value settings.save() # will create additional attributes, but not mandatory settings.new_merge_request = True diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst index 827ffbd4b..fcf55e620 100644 --- a/docs/gl_objects/projects.rst +++ b/docs/gl_objects/projects.rst @@ -446,9 +446,9 @@ Project snippets The snippet visibility can be defined using the following constants: -* ``gitlab.const.VISIBILITY_PRIVATE`` -* ``gitlab.const.VISIBILITY_INTERNAL`` -* ``gitlab.const.VISIBILITY_PUBLIC`` +* ``gitlab.const.Visibility.PRIVATE`` +* ``gitlab.const.Visibility.INTERNAL`` +* ``gitlab.const.Visibility.PUBLIC`` Reference --------- @@ -487,7 +487,7 @@ Create a snippet:: 'file_name': 'foo.py', 'code': 'import gitlab', 'visibility_level': - gitlab.const.VISIBILITY_PRIVATE}) + gitlab.const.Visibility.PRIVATE.value}) Update a snippet:: @@ -553,11 +553,11 @@ Get a member of a project, including members inherited through ancestor groups:: Add a project member:: member = project.members.create({'user_id': user.id, 'access_level': - gitlab.const.DEVELOPER_ACCESS}) + gitlab.const.AccessLevel.DEVELOPER.value}) Modify a project member (change the access level):: - member.access_level = gitlab.const.MAINTAINER_ACCESS + member.access_level = gitlab.const.AccessLevel.MAINTAINER.value member.save() Remove a member from the project team:: @@ -568,7 +568,7 @@ Remove a member from the project team:: Share/unshare the project with a group:: - project.share(group.id, gitlab.const.DEVELOPER_ACCESS) + project.share(group.id, gitlab.const.AccessLevel.DEVELOPER.value) project.unshare(group.id) Project hooks diff --git a/docs/gl_objects/protected_branches.rst b/docs/gl_objects/protected_branches.rst index 74cc3f6e6..fd2034781 100644 --- a/docs/gl_objects/protected_branches.rst +++ b/docs/gl_objects/protected_branches.rst @@ -31,8 +31,8 @@ Create a protected branch:: p_branch = project.protectedbranches.create({ 'name': '*-stable', - 'merge_access_level': gitlab.const.DEVELOPER_ACCESS, - 'push_access_level': gitlab.const.MAINTAINER_ACCESS + 'merge_access_level': gitlab.const.AccessLevel.DEVELOPER.value, + 'push_access_level': gitlab.const.AccessLevel.MAINTAINER.value }) Create a protected branch with more granular access control:: @@ -41,7 +41,7 @@ Create a protected branch with more granular access control:: 'name': '*-stable', 'allowed_to_push': [{"user_id": 99}, {"user_id": 98}], 'allowed_to_merge': [{"group_id": 653}], - 'allowed_to_unprotect': [{"access_level": gitlab.const.MAINTAINER_ACCESS}] + 'allowed_to_unprotect': [{"access_level": gitlab.const.AccessLevel.MAINTAINER.value}] }) Delete a protected branch:: diff --git a/docs/gl_objects/search.rst b/docs/gl_objects/search.rst index 44773099d..f443d8978 100644 --- a/docs/gl_objects/search.rst +++ b/docs/gl_objects/search.rst @@ -9,24 +9,24 @@ string. The following constants are provided to represent the possible scopes: * Shared scopes (global, group and project): - + ``gitlab.const.SEARCH_SCOPE_PROJECTS``: ``projects`` - + ``gitlab.const.SEARCH_SCOPE_ISSUES``: ``issues`` - + ``gitlab.const.SEARCH_SCOPE_MERGE_REQUESTS``: ``merge_requests`` - + ``gitlab.const.SEARCH_SCOPE_MILESTONES``: ``milestones`` - + ``gitlab.const.SEARCH_SCOPE_WIKI_BLOBS``: ``wiki_blobs`` - + ``gitlab.const.SEARCH_SCOPE_COMMITS``: ``commits`` - + ``gitlab.const.SEARCH_SCOPE_BLOBS``: ``blobs`` - + ``gitlab.const.SEARCH_SCOPE_USERS``: ``users`` + + ``gitlab.const.SearchScope.PROJECTS``: ``projects`` + + ``gitlab.const.SearchScope.ISSUES``: ``issues`` + + ``gitlab.const.SearchScope.MERGE_REQUESTS``: ``merge_requests`` + + ``gitlab.const.SearchScope.MILESTONES``: ``milestones`` + + ``gitlab.const.SearchScope.WIKI_BLOBS``: ``wiki_blobs`` + + ``gitlab.const.SearchScope.COMMITS``: ``commits`` + + ``gitlab.const.SearchScope.BLOBS``: ``blobs`` + + ``gitlab.const.SearchScope.USERS``: ``users`` * specific global scope: - + ``gitlab.const.SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES``: ``snippet_titles`` + + ``gitlab.const.SearchScope.GLOBAL_SNIPPET_TITLES``: ``snippet_titles`` * specific project scope: - + ``gitlab.const.SEARCH_SCOPE_PROJECT_NOTES``: ``notes`` + + ``gitlab.const.SearchScope.PROJECT_NOTES``: ``notes`` Reference @@ -46,30 +46,30 @@ Examples Search for issues matching a specific string:: # global search - gl.search(gitlab.const.SEARCH_SCOPE_ISSUES, 'regression') + gl.search(gitlab.const.SearchScope.ISSUES.value, 'regression') # group search group = gl.groups.get('mygroup') - group.search(gitlab.const.SEARCH_SCOPE_ISSUES, 'regression') + group.search(gitlab.const.SearchScope.ISSUES.value, 'regression') # project search project = gl.projects.get('myproject') - project.search(gitlab.const.SEARCH_SCOPE_ISSUES, 'regression') + project.search(gitlab.const.SearchScope.ISSUES.value, 'regression') The ``search()`` methods implement the pagination support:: # get lists of 10 items, and start at page 2 - gl.search(gitlab.const.SEARCH_SCOPE_ISSUES, search_str, page=2, per_page=10) + gl.search(gitlab.const.SearchScope.ISSUES.value, search_str, page=2, per_page=10) # get a generator that will automatically make required API calls for # pagination - for item in gl.search(gitlab.const.SEARCH_SCOPE_ISSUES, search_str, iterator=True): + for item in gl.search(gitlab.const.SearchScope.ISSUES.value, search_str, iterator=True): do_something(item) The search API doesn't return objects, but dicts. If you need to act on objects, you need to create them explicitly:: - for item in gl.search(gitlab.const.SEARCH_SCOPE_ISSUES, search_str, iterator=True): + for item in gl.search(gitlab.const.SearchScope.ISSUES.value, search_str, iterator=True): issue_project = gl.projects.get(item['project_id'], lazy=True) issue = issue_project.issues.get(item['iid']) issue.state = 'closed' diff --git a/docs/gl_objects/snippets.rst b/docs/gl_objects/snippets.rst index 47166b9d0..b5ad3d02d 100644 --- a/docs/gl_objects/snippets.rst +++ b/docs/gl_objects/snippets.rst @@ -44,7 +44,7 @@ Create a snippet:: Update the snippet attributes:: - snippet.visibility_level = gitlab.const.VISIBILITY_PUBLIC + snippet.visibility_level = gitlab.const.Visibility.PUBLIC.value snippet.save() To update a snippet code you need to create a ``ProjectSnippet`` object:: diff --git a/gitlab/const.py b/gitlab/const.py index 0d35045c2..033044a94 100644 --- a/gitlab/const.py +++ b/gitlab/const.py @@ -15,6 +15,8 @@ # You should have received a copy of the GNU Lesser General Public License # along with this program. If not, see . +from enum import Enum, IntEnum + from gitlab._version import __title__, __version__ # NOTE(jlvillal): '_DEPRECATED' only affects users accessing constants via the @@ -22,6 +24,7 @@ # consumer of '_DEPRECATED' For example 'x = gitlab.NO_ACCESS'. We want users # to instead use constants by doing code like: gitlab.const.NO_ACCESS. _DEPRECATED = [ + "ADMIN_ACCESS", "DEFAULT_URL", "DEVELOPER_ACCESS", "GUEST_ACCESS", @@ -52,43 +55,91 @@ "VISIBILITY_PUBLIC", ] + +# https://gitlab.com/gitlab-org/gitlab/-/blob/e97357824bedf007e75f8782259fe07435b64fbb/lib/gitlab/access.rb#L12-18 +class AccessLevel(IntEnum): + NO_ACCESS: int = 0 + MINIMAL_ACCESS: int = 5 + GUEST: int = 10 + REPORTER: int = 20 + DEVELOPER: int = 30 + MAINTAINER: int = 40 + OWNER: int = 50 + ADMIN: int = 60 + + +# https://gitlab.com/gitlab-org/gitlab/-/blob/e97357824bedf007e75f8782259fe07435b64fbb/lib/gitlab/visibility_level.rb#L23-25 +class Visibility(Enum): + PRIVATE: str = "private" + INTERNAL: str = "internal" + PUBLIC: str = "public" + + +class NotificationLevel(Enum): + DISABLED: str = "disabled" + PARTICIPATING: str = "participating" + WATCH: str = "watch" + GLOBAL: str = "global" + MENTION: str = "mention" + CUSTOM: str = "custom" + + +# https://gitlab.com/gitlab-org/gitlab/-/blob/e97357824bedf007e75f8782259fe07435b64fbb/app/views/search/_category.html.haml#L10-37 +class SearchScope(Enum): + # all scopes (global, group and project) + PROJECTS: str = "projects" + ISSUES: str = "issues" + MERGE_REQUESTS: str = "merge_requests" + MILESTONES: str = "milestones" + WIKI_BLOBS: str = "wiki_blobs" + COMMITS: str = "commits" + BLOBS: str = "blobs" + USERS: str = "users" + + # specific global scope + GLOBAL_SNIPPET_TITLES: str = "snippet_titles" + + # specific project scope + PROJECT_NOTES: str = "notes" + + DEFAULT_URL: str = "https://gitlab.com" -NO_ACCESS: int = 0 -MINIMAL_ACCESS: int = 5 -GUEST_ACCESS: int = 10 -REPORTER_ACCESS: int = 20 -DEVELOPER_ACCESS: int = 30 -MAINTAINER_ACCESS: int = 40 -OWNER_ACCESS: int = 50 -ADMIN_ACCESS: int = 60 - -VISIBILITY_PRIVATE: str = "private" -VISIBILITY_INTERNAL: str = "internal" -VISIBILITY_PUBLIC: str = "public" - -NOTIFICATION_LEVEL_DISABLED: str = "disabled" -NOTIFICATION_LEVEL_PARTICIPATING: str = "participating" -NOTIFICATION_LEVEL_WATCH: str = "watch" -NOTIFICATION_LEVEL_GLOBAL: str = "global" -NOTIFICATION_LEVEL_MENTION: str = "mention" -NOTIFICATION_LEVEL_CUSTOM: str = "custom" +NO_ACCESS = AccessLevel.NO_ACCESS.value +MINIMAL_ACCESS = AccessLevel.MINIMAL_ACCESS.value +GUEST_ACCESS = AccessLevel.GUEST.value +REPORTER_ACCESS = AccessLevel.REPORTER.value +DEVELOPER_ACCESS = AccessLevel.DEVELOPER.value +MAINTAINER_ACCESS = AccessLevel.MAINTAINER.value +OWNER_ACCESS = AccessLevel.OWNER.value +ADMIN_ACCESS = AccessLevel.ADMIN.value + +VISIBILITY_PRIVATE = Visibility.PRIVATE.value +VISIBILITY_INTERNAL = Visibility.INTERNAL.value +VISIBILITY_PUBLIC = Visibility.PUBLIC.value + +NOTIFICATION_LEVEL_DISABLED = NotificationLevel.DISABLED.value +NOTIFICATION_LEVEL_PARTICIPATING = NotificationLevel.PARTICIPATING.value +NOTIFICATION_LEVEL_WATCH = NotificationLevel.WATCH.value +NOTIFICATION_LEVEL_GLOBAL = NotificationLevel.GLOBAL.value +NOTIFICATION_LEVEL_MENTION = NotificationLevel.MENTION.value +NOTIFICATION_LEVEL_CUSTOM = NotificationLevel.CUSTOM.value # Search scopes # all scopes (global, group and project) -SEARCH_SCOPE_PROJECTS: str = "projects" -SEARCH_SCOPE_ISSUES: str = "issues" -SEARCH_SCOPE_MERGE_REQUESTS: str = "merge_requests" -SEARCH_SCOPE_MILESTONES: str = "milestones" -SEARCH_SCOPE_WIKI_BLOBS: str = "wiki_blobs" -SEARCH_SCOPE_COMMITS: str = "commits" -SEARCH_SCOPE_BLOBS: str = "blobs" -SEARCH_SCOPE_USERS: str = "users" +SEARCH_SCOPE_PROJECTS = SearchScope.PROJECTS.value +SEARCH_SCOPE_ISSUES = SearchScope.ISSUES.value +SEARCH_SCOPE_MERGE_REQUESTS = SearchScope.MERGE_REQUESTS.value +SEARCH_SCOPE_MILESTONES = SearchScope.MILESTONES.value +SEARCH_SCOPE_WIKI_BLOBS = SearchScope.WIKI_BLOBS.value +SEARCH_SCOPE_COMMITS = SearchScope.COMMITS.value +SEARCH_SCOPE_BLOBS = SearchScope.BLOBS.value +SEARCH_SCOPE_USERS = SearchScope.USERS.value # specific global scope -SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES: str = "snippet_titles" +SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES = SearchScope.GLOBAL_SNIPPET_TITLES.value # specific project scope -SEARCH_SCOPE_PROJECT_NOTES: str = "notes" +SEARCH_SCOPE_PROJECT_NOTES = SearchScope.PROJECT_NOTES.value USER_AGENT: str = f"{__title__}/{__version__}"