Merge pull request #1688 from jspricke/enum

nejch · web-flow · commit f0ac3cda2912 · 2022-06-22T22:23:59.000+02:00
feat(api): Convert gitlab.const to Enums
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -15,13 +15,16 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+from enum import Enum, IntEnum
+
 from gitlab._version import __title__, __version__
 
 # NOTE(jlvillal): '_DEPRECATED' only affects users accessing constants via the
 # top-level gitlab.* namespace. See 'gitlab/__init__.py:__getattr__()' for the
 # 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__}"
