Implement runners global API

Gauvain Pocentek · Gauvain Pocentek · commit 6eb11fd73840 · 2016-07-17T09:16:34.000+02:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -6,4 +6,5 @@ API objects manipulation
 
    gl_objects/branches
    gl_objects/projects
+   gl_objects/runners
    gl_objects/users
diff --git a/docs/gl_objects/runners.py b/docs/gl_objects/runners.py
@@ -0,0 +1,22 @@
+# list
+# List owned runners
+runners = gl.runners.list()
+# List all runners, using a filter
+runners = gl.runners.all(scope='paused')
+# end list
+
+# get
+runner = gl.runners.get(runner_id)
+# end get
+
+# update
+runner = gl.runners.get(runner_id)
+runner.tag_list.append('new_tag')
+runner.save()
+# end update
+
+# delete
+gl.runners.delete(runner_id)
+# or
+runner.delete()
+# end delete
diff --git a/docs/gl_objects/runners.rst b/docs/gl_objects/runners.rst
@@ -0,0 +1,45 @@
+#######
+Runners
+#######
+
+Global runners
+==============
+
+Use :class:`~gitlab.objects.Runner` objects to manipulate runners. The
+:attr:`gitlab.Gitlab.runners` manager object provides helper functions.
+
+Examples
+--------
+
+Use the ``list()`` and ``all()`` methods to list runners.
+
+ The ``all()`` method accepts a ``scope`` parameter to filter the list. Allowed
+values for this parameter are ``specific``, ``shared``, ``active``, ``paused``
+and ``online``.
+
+.. note::
+
+   The returned objects hold minimal information about the runners. Use the
+   ``get()`` method to retrieve detail about a runner.
+
+.. literalinclude:: runners.py
+   :start-after: # list
+   :end-before: # end list
+
+Get a runner's detail:
+
+.. literalinclude:: runners.py
+   :start-after: # get
+   :end-before: # end get
+
+Update a runner:
+
+.. literalinclude:: runners.py
+   :start-after: # update
+   :end-before: # end update
+
+Remove a runner:
+
+.. literalinclude:: runners.py
+   :start-after: # delete
+   :end-before: # end delete
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
@@ -109,6 +109,7 @@ class Gitlab(object):
             snippets
         user_projects (UserProjectManager): Manager for GitLab projects users
         projects (ProjectManager): Manager for GitLab projects
+        runners (RunnerManager): Manager for the CI runners
         settings (ApplicationSettingsManager): manager for the Gitlab settings
         team_members (TeamMemberManager): Manager for GitLab teams members
         team_projects (TeamProjectManager): Manager for GitLab teams projects
@@ -169,6 +170,7 @@ def __init__(self, url, private_token=None, email=None, password=None,
         self.project_snippets = ProjectSnippetManager(self)
         self.user_projects = UserProjectManager(self)
         self.projects = ProjectManager(self)
+        self.runners = RunnerManager(self)
         self.team_members = TeamMemberManager(self)
         self.team_projects = TeamProjectManager(self)
         self.teams = TeamManager(self)
diff --git a/gitlab/objects.py b/gitlab/objects.py
@@ -1965,6 +1965,35 @@ def share(self, group_id, group_access, **kwargs):
         raise_error_from_response(r, GitlabCreateError, 201)
 
 
+class Runner(GitlabObject):
+    _url = '/runners'
+    canCreate = False
+    optionalUpdateAttrs = ['description', 'active', 'tag_list']
+
+
+class RunnerManager(BaseManager):
+    obj_cls = Runner
+
+    def all(self, scope=None, **kwargs):
+        """List all the runners.
+
+        Args:
+            scope (str): The scope of runners to show, one of: specific,
+                shared, active, paused, online
+
+        Returns:
+            list(Runner): a list of runners matching the scope.
+
+        Raises:
+            GitlabConnectionError: If the server cannot be reached.
+            GitlabListError; If the resource cannot be found
+        """
+        url = '/runners/all'
+        if scope is not None:
+            url += '?scope=' + scope
+        return self.gitlab._raw_list(url, self.obj_cls, **kwargs)
+
+
 class TeamMember(GitlabObject):
     _url = '/user_teams/%(team_id)s/members'
     canUpdate = False
