Skip to content

Commit f0ac3cd

Browse files
authored
Merge pull request #1688 from jspricke/enum
feat(api): Convert gitlab.const to Enums
2 parents 1feabc0 + c3c6086 commit f0ac3cd

File tree

8 files changed

+130
-79
lines changed

8 files changed

+130
-79
lines changed

docs/gl_objects/access_requests.rst

+6-6
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,11 @@ Users can request access to groups and projects.
77
When access is granted the user should be given a numerical access level. The
88
following constants are provided to represent the access levels:
99

10-
* ``gitlab.const.GUEST_ACCESS``: ``10``
11-
* ``gitlab.const.REPORTER_ACCESS``: ``20``
12-
* ``gitlab.const.DEVELOPER_ACCESS``: ``30``
13-
* ``gitlab.const.MAINTAINER_ACCESS``: ``40``
14-
* ``gitlab.const.OWNER_ACCESS``: ``50``
10+
* ``gitlab.const.AccessLevel.GUEST``: ``10``
11+
* ``gitlab.const.AccessLevel.REPORTER``: ``20``
12+
* ``gitlab.const.AccessLevel.DEVELOPER``: ``30``
13+
* ``gitlab.const.AccessLevel.MAINTAINER``: ``40``
14+
* ``gitlab.const.AccessLevel.OWNER``: ``50``
1515

1616
References
1717
----------
@@ -43,7 +43,7 @@ Create an access request::
4343
Approve an access request::
4444

4545
ar.approve() # defaults to DEVELOPER level
46-
ar.approve(access_level=gitlab.const.MAINTAINER_ACCESS) # explicitly set access level
46+
ar.approve(access_level=gitlab.const.AccessLevel.MAINTAINER.value) # explicitly set access level
4747

4848
Deny (delete) an access request::
4949

docs/gl_objects/groups.rst

+9-9
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ Remove a group::
8080

8181
Share/unshare the group with a group::
8282

83-
group.share(group2.id, gitlab.const.DEVELOPER_ACCESS)
83+
group.share(group2.id, gitlab.const.AccessLevel.DEVELOPER.value)
8484
group.unshare(group2.id)
8585

8686
Import / Export
@@ -237,11 +237,11 @@ Group members
237237

238238
The following constants define the supported access levels:
239239

240-
* ``gitlab.const.GUEST_ACCESS = 10``
241-
* ``gitlab.const.REPORTER_ACCESS = 20``
242-
* ``gitlab.const.DEVELOPER_ACCESS = 30``
243-
* ``gitlab.const.MAINTAINER_ACCESS = 40``
244-
* ``gitlab.const.OWNER_ACCESS = 50``
240+
* ``gitlab.const.AccessLevel.GUEST = 10``
241+
* ``gitlab.const.AccessLevel.REPORTER = 20``
242+
* ``gitlab.const.AccessLevel.DEVELOPER = 30``
243+
* ``gitlab.const.AccessLevel.MAINTAINER = 40``
244+
* ``gitlab.const.AccessLevel.OWNER = 50``
245245

246246
Reference
247247
---------
@@ -284,11 +284,11 @@ Get a member of a group, including members inherited through ancestor groups::
284284
Add a member to the group::
285285

286286
member = group.members.create({'user_id': user_id,
287-
'access_level': gitlab.const.GUEST_ACCESS})
287+
'access_level': gitlab.const.AccessLevel.GUEST.value})
288288

289289
Update a member (change the access level)::
290290

291-
member.access_level = gitlab.const.DEVELOPER_ACCESS
291+
member.access_level = gitlab.const.AccessLevel.DEVELOPER.value
292292
member.save()
293293

294294
Remove a member from the group::
@@ -316,7 +316,7 @@ LDAP group links
316316

317317
Add an LDAP group link to an existing GitLab group::
318318

319-
group.add_ldap_group_link(ldap_group_cn, gitlab.const.DEVELOPER_ACCESS, 'ldapmain')
319+
group.add_ldap_group_link(ldap_group_cn, gitlab.const.AccessLevel.DEVELOPER.value, 'ldapmain')
320320

321321
Remove a link::
322322

docs/gl_objects/notifications.rst

+8-8
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,12 @@ Notification settings
55
You can define notification settings globally, for groups and for projects.
66
Valid levels are defined as constants:
77

8-
* ``gitlab.const.NOTIFICATION_LEVEL_DISABLED``
9-
* ``gitlab.const.NOTIFICATION_LEVEL_PARTICIPATING``
10-
* ``gitlab.const.NOTIFICATION_LEVEL_WATCH``
11-
* ``gitlab.const.NOTIFICATION_LEVEL_GLOBAL``
12-
* ``gitlab.const.NOTIFICATION_LEVEL_MENTION``
13-
* ``gitlab.const.NOTIFICATION_LEVEL_CUSTOM``
8+
* ``gitlab.const.NotificationLevel.DISABLED``
9+
* ``gitlab.const.NotificationLevel.PARTICIPATING``
10+
* ``gitlab.const.NotificationLevel.WATCH``
11+
* ``gitlab.const.NotificationLevel.GLOBAL``
12+
* ``gitlab.const.NotificationLevel.MENTION``
13+
* ``gitlab.const.NotificationLevel.CUSTOM``
1414

1515
You get access to fine-grained settings if you use the
1616
``NOTIFICATION_LEVEL_CUSTOM`` level.
@@ -47,10 +47,10 @@ Get the notifications settings::
4747
Update the notifications settings::
4848

4949
# use a predefined level
50-
settings.level = gitlab.const.NOTIFICATION_LEVEL_WATCH
50+
settings.level = gitlab.const.NotificationLevel.WATCH.value
5151

5252
# create a custom setup
53-
settings.level = gitlab.const.NOTIFICATION_LEVEL_CUSTOM
53+
settings.level = gitlab.const.NotificationLevel.CUSTOM.value
5454
settings.save() # will create additional attributes, but not mandatory
5555

5656
settings.new_merge_request = True

docs/gl_objects/projects.rst

+7-7
Original file line numberDiff line numberDiff line change
@@ -446,9 +446,9 @@ Project snippets
446446

447447
The snippet visibility can be defined using the following constants:
448448

449-
* ``gitlab.const.VISIBILITY_PRIVATE``
450-
* ``gitlab.const.VISIBILITY_INTERNAL``
451-
* ``gitlab.const.VISIBILITY_PUBLIC``
449+
* ``gitlab.const.Visibility.PRIVATE``
450+
* ``gitlab.const.Visibility.INTERNAL``
451+
* ``gitlab.const.Visibility.PUBLIC``
452452

453453
Reference
454454
---------
@@ -487,7 +487,7 @@ Create a snippet::
487487
'file_name': 'foo.py',
488488
'code': 'import gitlab',
489489
'visibility_level':
490-
gitlab.const.VISIBILITY_PRIVATE})
490+
gitlab.const.Visibility.PRIVATE.value})
491491

492492
Update a snippet::
493493

@@ -553,11 +553,11 @@ Get a member of a project, including members inherited through ancestor groups::
553553
Add a project member::
554554

555555
member = project.members.create({'user_id': user.id, 'access_level':
556-
gitlab.const.DEVELOPER_ACCESS})
556+
gitlab.const.AccessLevel.DEVELOPER.value})
557557

558558
Modify a project member (change the access level)::
559559

560-
member.access_level = gitlab.const.MAINTAINER_ACCESS
560+
member.access_level = gitlab.const.AccessLevel.MAINTAINER.value
561561
member.save()
562562

563563
Remove a member from the project team::
@@ -568,7 +568,7 @@ Remove a member from the project team::
568568

569569
Share/unshare the project with a group::
570570

571-
project.share(group.id, gitlab.const.DEVELOPER_ACCESS)
571+
project.share(group.id, gitlab.const.AccessLevel.DEVELOPER.value)
572572
project.unshare(group.id)
573573

574574
Project hooks

docs/gl_objects/protected_branches.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ Create a protected branch::
3131

3232
p_branch = project.protectedbranches.create({
3333
'name': '*-stable',
34-
'merge_access_level': gitlab.const.DEVELOPER_ACCESS,
35-
'push_access_level': gitlab.const.MAINTAINER_ACCESS
34+
'merge_access_level': gitlab.const.AccessLevel.DEVELOPER.value,
35+
'push_access_level': gitlab.const.AccessLevel.MAINTAINER.value
3636
})
3737

3838
Create a protected branch with more granular access control::
@@ -41,7 +41,7 @@ Create a protected branch with more granular access control::
4141
'name': '*-stable',
4242
'allowed_to_push': [{"user_id": 99}, {"user_id": 98}],
4343
'allowed_to_merge': [{"group_id": 653}],
44-
'allowed_to_unprotect': [{"access_level": gitlab.const.MAINTAINER_ACCESS}]
44+
'allowed_to_unprotect': [{"access_level": gitlab.const.AccessLevel.MAINTAINER.value}]
4545
})
4646

4747
Delete a protected branch::

docs/gl_objects/search.rst

+16-16
Original file line numberDiff line numberDiff line change
@@ -9,24 +9,24 @@ string. The following constants are provided to represent the possible scopes:
99

1010
* Shared scopes (global, group and project):
1111

12-
+ ``gitlab.const.SEARCH_SCOPE_PROJECTS``: ``projects``
13-
+ ``gitlab.const.SEARCH_SCOPE_ISSUES``: ``issues``
14-
+ ``gitlab.const.SEARCH_SCOPE_MERGE_REQUESTS``: ``merge_requests``
15-
+ ``gitlab.const.SEARCH_SCOPE_MILESTONES``: ``milestones``
16-
+ ``gitlab.const.SEARCH_SCOPE_WIKI_BLOBS``: ``wiki_blobs``
17-
+ ``gitlab.const.SEARCH_SCOPE_COMMITS``: ``commits``
18-
+ ``gitlab.const.SEARCH_SCOPE_BLOBS``: ``blobs``
19-
+ ``gitlab.const.SEARCH_SCOPE_USERS``: ``users``
12+
+ ``gitlab.const.SearchScope.PROJECTS``: ``projects``
13+
+ ``gitlab.const.SearchScope.ISSUES``: ``issues``
14+
+ ``gitlab.const.SearchScope.MERGE_REQUESTS``: ``merge_requests``
15+
+ ``gitlab.const.SearchScope.MILESTONES``: ``milestones``
16+
+ ``gitlab.const.SearchScope.WIKI_BLOBS``: ``wiki_blobs``
17+
+ ``gitlab.const.SearchScope.COMMITS``: ``commits``
18+
+ ``gitlab.const.SearchScope.BLOBS``: ``blobs``
19+
+ ``gitlab.const.SearchScope.USERS``: ``users``
2020

2121

2222
* specific global scope:
2323

24-
+ ``gitlab.const.SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES``: ``snippet_titles``
24+
+ ``gitlab.const.SearchScope.GLOBAL_SNIPPET_TITLES``: ``snippet_titles``
2525

2626

2727
* specific project scope:
2828

29-
+ ``gitlab.const.SEARCH_SCOPE_PROJECT_NOTES``: ``notes``
29+
+ ``gitlab.const.SearchScope.PROJECT_NOTES``: ``notes``
3030

3131

3232
Reference
@@ -46,30 +46,30 @@ Examples
4646
Search for issues matching a specific string::
4747

4848
# global search
49-
gl.search(gitlab.const.SEARCH_SCOPE_ISSUES, 'regression')
49+
gl.search(gitlab.const.SearchScope.ISSUES.value, 'regression')
5050

5151
# group search
5252
group = gl.groups.get('mygroup')
53-
group.search(gitlab.const.SEARCH_SCOPE_ISSUES, 'regression')
53+
group.search(gitlab.const.SearchScope.ISSUES.value, 'regression')
5454

5555
# project search
5656
project = gl.projects.get('myproject')
57-
project.search(gitlab.const.SEARCH_SCOPE_ISSUES, 'regression')
57+
project.search(gitlab.const.SearchScope.ISSUES.value, 'regression')
5858

5959
The ``search()`` methods implement the pagination support::
6060

6161
# get lists of 10 items, and start at page 2
62-
gl.search(gitlab.const.SEARCH_SCOPE_ISSUES, search_str, page=2, per_page=10)
62+
gl.search(gitlab.const.SearchScope.ISSUES.value, search_str, page=2, per_page=10)
6363

6464
# get a generator that will automatically make required API calls for
6565
# pagination
66-
for item in gl.search(gitlab.const.SEARCH_SCOPE_ISSUES, search_str, iterator=True):
66+
for item in gl.search(gitlab.const.SearchScope.ISSUES.value, search_str, iterator=True):
6767
do_something(item)
6868

6969
The search API doesn't return objects, but dicts. If you need to act on
7070
objects, you need to create them explicitly::
7171

72-
for item in gl.search(gitlab.const.SEARCH_SCOPE_ISSUES, search_str, iterator=True):
72+
for item in gl.search(gitlab.const.SearchScope.ISSUES.value, search_str, iterator=True):
7373
issue_project = gl.projects.get(item['project_id'], lazy=True)
7474
issue = issue_project.issues.get(item['iid'])
7575
issue.state = 'closed'

docs/gl_objects/snippets.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Create a snippet::
4444

4545
Update the snippet attributes::
4646

47-
snippet.visibility_level = gitlab.const.VISIBILITY_PUBLIC
47+
snippet.visibility_level = gitlab.const.Visibility.PUBLIC.value
4848
snippet.save()
4949

5050
To update a snippet code you need to create a ``ProjectSnippet`` object::

gitlab/const.py

+80-29
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,16 @@
1515
# You should have received a copy of the GNU Lesser General Public License
1616
# along with this program. If not, see <http://www.gnu.org/licenses/>.
1717

18+
from enum import Enum, IntEnum
19+
1820
from gitlab._version import __title__, __version__
1921

2022
# NOTE(jlvillal): '_DEPRECATED' only affects users accessing constants via the
2123
# top-level gitlab.* namespace. See 'gitlab/__init__.py:__getattr__()' for the
2224
# consumer of '_DEPRECATED' For example 'x = gitlab.NO_ACCESS'. We want users
2325
# to instead use constants by doing code like: gitlab.const.NO_ACCESS.
2426
_DEPRECATED = [
27+
"ADMIN_ACCESS",
2528
"DEFAULT_URL",
2629
"DEVELOPER_ACCESS",
2730
"GUEST_ACCESS",
@@ -52,43 +55,91 @@
5255
"VISIBILITY_PUBLIC",
5356
]
5457

58+
59+
# https://gitlab.com/gitlab-org/gitlab/-/blob/e97357824bedf007e75f8782259fe07435b64fbb/lib/gitlab/access.rb#L12-18
60+
class AccessLevel(IntEnum):
61+
NO_ACCESS: int = 0
62+
MINIMAL_ACCESS: int = 5
63+
GUEST: int = 10
64+
REPORTER: int = 20
65+
DEVELOPER: int = 30
66+
MAINTAINER: int = 40
67+
OWNER: int = 50
68+
ADMIN: int = 60
69+
70+
71+
# https://gitlab.com/gitlab-org/gitlab/-/blob/e97357824bedf007e75f8782259fe07435b64fbb/lib/gitlab/visibility_level.rb#L23-25
72+
class Visibility(Enum):
73+
PRIVATE: str = "private"
74+
INTERNAL: str = "internal"
75+
PUBLIC: str = "public"
76+
77+
78+
class NotificationLevel(Enum):
79+
DISABLED: str = "disabled"
80+
PARTICIPATING: str = "participating"
81+
WATCH: str = "watch"
82+
GLOBAL: str = "global"
83+
MENTION: str = "mention"
84+
CUSTOM: str = "custom"
85+
86+
87+
# https://gitlab.com/gitlab-org/gitlab/-/blob/e97357824bedf007e75f8782259fe07435b64fbb/app/views/search/_category.html.haml#L10-37
88+
class SearchScope(Enum):
89+
# all scopes (global, group and project)
90+
PROJECTS: str = "projects"
91+
ISSUES: str = "issues"
92+
MERGE_REQUESTS: str = "merge_requests"
93+
MILESTONES: str = "milestones"
94+
WIKI_BLOBS: str = "wiki_blobs"
95+
COMMITS: str = "commits"
96+
BLOBS: str = "blobs"
97+
USERS: str = "users"
98+
99+
# specific global scope
100+
GLOBAL_SNIPPET_TITLES: str = "snippet_titles"
101+
102+
# specific project scope
103+
PROJECT_NOTES: str = "notes"
104+
105+
55106
DEFAULT_URL: str = "https://gitlab.com"
56107

57-
NO_ACCESS: int = 0
58-
MINIMAL_ACCESS: int = 5
59-
GUEST_ACCESS: int = 10
60-
REPORTER_ACCESS: int = 20
61-
DEVELOPER_ACCESS: int = 30
62-
MAINTAINER_ACCESS: int = 40
63-
OWNER_ACCESS: int = 50
64-
ADMIN_ACCESS: int = 60
65-
66-
VISIBILITY_PRIVATE: str = "private"
67-
VISIBILITY_INTERNAL: str = "internal"
68-
VISIBILITY_PUBLIC: str = "public"
69-
70-
NOTIFICATION_LEVEL_DISABLED: str = "disabled"
71-
NOTIFICATION_LEVEL_PARTICIPATING: str = "participating"
72-
NOTIFICATION_LEVEL_WATCH: str = "watch"
73-
NOTIFICATION_LEVEL_GLOBAL: str = "global"
74-
NOTIFICATION_LEVEL_MENTION: str = "mention"
75-
NOTIFICATION_LEVEL_CUSTOM: str = "custom"
108+
NO_ACCESS = AccessLevel.NO_ACCESS.value
109+
MINIMAL_ACCESS = AccessLevel.MINIMAL_ACCESS.value
110+
GUEST_ACCESS = AccessLevel.GUEST.value
111+
REPORTER_ACCESS = AccessLevel.REPORTER.value
112+
DEVELOPER_ACCESS = AccessLevel.DEVELOPER.value
113+
MAINTAINER_ACCESS = AccessLevel.MAINTAINER.value
114+
OWNER_ACCESS = AccessLevel.OWNER.value
115+
ADMIN_ACCESS = AccessLevel.ADMIN.value
116+
117+
VISIBILITY_PRIVATE = Visibility.PRIVATE.value
118+
VISIBILITY_INTERNAL = Visibility.INTERNAL.value
119+
VISIBILITY_PUBLIC = Visibility.PUBLIC.value
120+
121+
NOTIFICATION_LEVEL_DISABLED = NotificationLevel.DISABLED.value
122+
NOTIFICATION_LEVEL_PARTICIPATING = NotificationLevel.PARTICIPATING.value
123+
NOTIFICATION_LEVEL_WATCH = NotificationLevel.WATCH.value
124+
NOTIFICATION_LEVEL_GLOBAL = NotificationLevel.GLOBAL.value
125+
NOTIFICATION_LEVEL_MENTION = NotificationLevel.MENTION.value
126+
NOTIFICATION_LEVEL_CUSTOM = NotificationLevel.CUSTOM.value
76127

77128
# Search scopes
78129
# all scopes (global, group and project)
79-
SEARCH_SCOPE_PROJECTS: str = "projects"
80-
SEARCH_SCOPE_ISSUES: str = "issues"
81-
SEARCH_SCOPE_MERGE_REQUESTS: str = "merge_requests"
82-
SEARCH_SCOPE_MILESTONES: str = "milestones"
83-
SEARCH_SCOPE_WIKI_BLOBS: str = "wiki_blobs"
84-
SEARCH_SCOPE_COMMITS: str = "commits"
85-
SEARCH_SCOPE_BLOBS: str = "blobs"
86-
SEARCH_SCOPE_USERS: str = "users"
130+
SEARCH_SCOPE_PROJECTS = SearchScope.PROJECTS.value
131+
SEARCH_SCOPE_ISSUES = SearchScope.ISSUES.value
132+
SEARCH_SCOPE_MERGE_REQUESTS = SearchScope.MERGE_REQUESTS.value
133+
SEARCH_SCOPE_MILESTONES = SearchScope.MILESTONES.value
134+
SEARCH_SCOPE_WIKI_BLOBS = SearchScope.WIKI_BLOBS.value
135+
SEARCH_SCOPE_COMMITS = SearchScope.COMMITS.value
136+
SEARCH_SCOPE_BLOBS = SearchScope.BLOBS.value
137+
SEARCH_SCOPE_USERS = SearchScope.USERS.value
87138

88139
# specific global scope
89-
SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES: str = "snippet_titles"
140+
SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES = SearchScope.GLOBAL_SNIPPET_TITLES.value
90141

91142
# specific project scope
92-
SEARCH_SCOPE_PROJECT_NOTES: str = "notes"
143+
SEARCH_SCOPE_PROJECT_NOTES = SearchScope.PROJECT_NOTES.value
93144

94145
USER_AGENT: str = f"{__title__}/{__version__}"

0 commit comments

Comments
 (0)