Add support for the search API

Gauvain Pocentek · Gauvain Pocentek · commit 97c8619c5b07 · 2018-05-21T16:21:48.000+02:00
Fixes #470
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -28,6 +28,7 @@ API examples
    gl_objects/pagesdomains
    gl_objects/projects
    gl_objects/runners
+   gl_objects/search
    gl_objects/settings
    gl_objects/snippets
    gl_objects/system_hooks
diff --git a/docs/gl_objects/search.rst b/docs/gl_objects/search.rst
@@ -0,0 +1,53 @@
+##########
+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.
+
+Reference
+---------
+
+* v4 API:
+
+  + :attr:`gitlab.Gitlab.search`
+  + :attr:`gitlab.v4.objects.Group.search`
+  + :attr:`gitlab.v4.objects.Project.search`
+
+* GitLab API: https://docs.gitlab.com/ce/api/search.html
+
+Examples
+--------
+
+Search for issues matching a specific string::
+
+    # global search
+    gl.search('issues', 'regression')
+
+    # group search
+    group = gl.groups.get('mygroup')
+    group.search('issues', 'regression')
+
+    # project search
+    project = gl.projects.get('myproject')
+    project.search('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)
+
+    # get a generator that will automatically make required API calls for
+    # pagination
+    for item in gl.search('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):
+        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/__init__.py b/gitlab/__init__.py
@@ -555,6 +555,25 @@ def http_delete(self, path, **kwargs):
         """
         return self.http_request('delete', path, **kwargs)
 
+    @on_http_error(GitlabSearchError)
+    def search(self, scope, search, **kwargs):
+        """Search GitLab resources matching the provided string.'
+
+        Args:
+            scope (str): Scope of the search
+            search (str): Search string
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabSearchError: If the server failed to perform the request
+
+        Returns:
+            GitlabList: A list of dicts describing the resources found.
+        """
+        data = {'scope': scope, 'search': search}
+        return self.http_list('/search', query_data=data, **kwargs)
+
 
 class GitlabList(object):
     """Generator representing a list of remote objects.
diff --git a/gitlab/exceptions.py b/gitlab/exceptions.py
@@ -197,6 +197,10 @@ class GitlabOwnershipError(GitlabOperationError):
     pass
 
 
+class GitlabSearchError(GitlabOperationError):
+    pass
+
+
 def on_http_error(error):
     """Manage GitlabHttpError exceptions.
 
diff --git a/gitlab/v4/objects.py b/gitlab/v4/objects.py
@@ -713,6 +713,27 @@ def transfer_project(self, to_project_id, **kwargs):
         path = '/groups/%d/projects/%d' % (self.id, to_project_id)
         self.manager.gitlab.http_post(path, **kwargs)
 
+    @cli.register_custom_action('Group', ('scope', 'search'))
+    @exc.on_http_error(exc.GitlabSearchError)
+    def search(self, scope, search, **kwargs):
+        """Search the group resources matching the provided string.'
+
+        Args:
+            scope (str): Scope of the search
+            search (str): Search string
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabSearchError: If the server failed to perform the request
+
+        Returns:
+            GitlabList: A list of dicts describing the resources found.
+        """
+        data = {'scope': scope, 'search': search}
+        path = '/groups/%d/search' % self.get_id()
+        return self.manager.gitlab.http_list(path, query_data=data, **kwargs)
+
 
 class GroupManager(CRUDMixin, RESTManager):
     _path = '/groups'
@@ -2867,6 +2888,27 @@ def upload(self, filename, filedata=None, filepath=None, **kwargs):
             "markdown": data['markdown']
         }
 
+    @cli.register_custom_action('Project', ('scope', 'search'))
+    @exc.on_http_error(exc.GitlabSearchError)
+    def search(self, scope, search, **kwargs):
+        """Search the project resources matching the provided string.'
+
+        Args:
+            scope (str): Scope of the search
+            search (str): Search string
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabSearchError: If the server failed to perform the request
+
+        Returns:
+            GitlabList: A list of dicts describing the resources found.
+        """
+        data = {'scope': scope, 'search': search}
+        path = '/projects/%d/search' % self.get_id()
+        return self.manager.gitlab.http_list(path, query_data=data, **kwargs)
+
 
 class ProjectManager(CRUDMixin, RESTManager):
     _path = '/projects'
