Merge pull request #1131 from valentingregoire/master

max-wittig · web-flow · commit 8cb8040198a6 · 2020-10-12T10:49:27.000+02:00
feat: added constants for search API
diff --git a/docs/gl_objects/badges.rst b/docs/gl_objects/badges.rst
@@ -28,7 +28,7 @@ List badges::
 
     badges = group_or_project.badges.list()
 
-Get ad badge::
+Get a badge::
 
     badge = group_or_project.badges.get(badge_id)
 
diff --git a/docs/gl_objects/search.rst b/docs/gl_objects/search.rst
@@ -4,7 +4,30 @@ Search API
 
 You can search for resources at the top level, in a project or in a group.
 Searches are based on a scope (issues, merge requests, and so on) and a search
-string.
+string. The following constants are provided to represent the possible scopes:
+
+
+* Shared scopes (global, group and project):
+
+  + ``gitlab.SEARCH_SCOPE_PROJECTS``: ``projects``
+  + ``gitlab.SEARCH_SCOPE_ISSUES``: ``issues``
+  + ``gitlab.SEARCH_SCOPE_MERGE_REQUESTS``: ``merge_requests``
+  + ``gitlab.SEARCH_SCOPE_MILESTONES``: ``milestones``
+  + ``gitlab.SEARCH_SCOPE_WIKI_BLOBS``: ``wiki_blobs``
+  + ``gitlab.SEARCH_SCOPE_COMMITS``: ``commits``
+  + ``gitlab.SEARCH_SCOPE_BLOBS``: ``blobs``
+  + ``gitlab.SEARCH_SCOPE_USERS``: ``users``
+
+
+* specific global scope:
+
+  + ``gitlab.SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES``: ``snippet_titles``
+
+
+* specific project scope:
+
+  + ``gitlab.SEARCH_SCOPE_PROJECT_NOTES``: ``notes``
+
 
 Reference
 ---------
@@ -23,31 +46,32 @@ Examples
 Search for issues matching a specific string::
 
     # global search
-    gl.search('issues', 'regression')
+    gl.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression')
 
     # group search
     group = gl.groups.get('mygroup')
-    group.search('issues', 'regression')
+    group.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression')
 
     # project search
     project = gl.projects.get('myproject')
-    project.search('issues', 'regression')
+    project.search(gitlab.SEARCH_SCOPE_ISSUES, 'regression')
 
 The ``search()`` methods implement the pagination support::
 
     # get lists of 10 items, and start at page 2
-    gl.search('issues', search_str, page=2, per_page=10)
+    gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, page=2, per_page=10)
 
     # get a generator that will automatically make required API calls for
     # pagination
-    for item in gl.search('issues', search_str, as_list=False):
+    for item in gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, as_list=False):
         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('issues', search_str, as_list=False):
+    for item in gl.search(gitlab.SEARCH_SCOPE_ISSUES, search_str, as_list=False):
         issue_project = gl.projects.get(item['project_id'], lazy=True)
         issue = issue_project.issues.get(item['iid'])
         issue.state = 'closed'
         issue.save()
+
diff --git a/gitlab/const.py b/gitlab/const.py
@@ -33,3 +33,20 @@
 NOTIFICATION_LEVEL_GLOBAL = "global"
 NOTIFICATION_LEVEL_MENTION = "mention"
 NOTIFICATION_LEVEL_CUSTOM = "custom"
+
+# Search scopes
+# all scopes (global, group and  project)
+SEARCH_SCOPE_PROJECTS = "projects"
+SEARCH_SCOPE_ISSUES = "issues"
+SEARCH_SCOPE_MERGE_REQUESTS = "merge_requests"
+SEARCH_SCOPE_MILESTONES = "milestones"
+SEARCH_SCOPE_WIKI_BLOBS = "wiki_blobs"
+SEARCH_SCOPE_COMMITS = "commits"
+SEARCH_SCOPE_BLOBS = "blobs"
+SEARCH_SCOPE_USERS = "users"
+
+# specific global scope
+SEARCH_SCOPE_GLOBAL_SNIPPET_TITLES = "snippet_titles"
+
+# specific project scope
+SEARCH_SCOPE_PROJECT_NOTES = "notes"
