introduce ReadMixin

tardyp · tardyp · commit 1b6a2e2ea906 · 2018-02-05T16:36:22.000+01:00
ReadMixin allows to update a REST object so that you can poll on it.
This is mostly useful for pipelines and jobs, but could be set on most of other objects, with unknown usecases.
diff --git a/docs/gl_objects/projects.py b/docs/gl_objects/projects.py
@@ -333,6 +333,22 @@
 pipeline = project.pipelines.create({'ref': 'master'})
 # end pipeline create
 
+# pipeline trigger
+def get_or_create_trigger(project):
+    trigger_decription = 'my_trigger_id'
+    for t in project.triggers.list():
+        if t.description == trigger_decription:
+            return t
+    return project.triggers.create({'description': trigger_decription})
+
+trigger = get_or_create_trigger(project)
+pipeline = project.trigger_pipeline('master', trigger.token, variables={"DEPLOY_ZONE": "us-west1"})
+while pipeline.finished_at is None:
+    pipeline.read()
+    os.sleep(1)
+
+# end pipeline trigger
+
 # pipeline retry
 pipeline.retry()
 # end pipeline retry
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
@@ -658,6 +658,12 @@ Create a pipeline for a particular reference:
    :start-after: # pipeline create
    :end-before: # end pipeline create
 
+Trigger a pipeline for a particular reference with variables and wait for completion:
+
+.. literalinclude:: projects.py
+   :start-after: # pipeline trigger
+   :end-before: # end pipeline trigger
+
 Project Services
 ================
 
diff --git a/gitlab/mixins.py b/gitlab/mixins.py
@@ -68,6 +68,25 @@ def get(self, id=None, **kwargs):
         return self._obj_cls(self, server_data)
 
 
+class ReadMixin(object):
+    @exc.on_http_error(exc.GitlabGetError)
+    def read(self, **kwargs):
+        """Read and update a single object from server.
+
+        Args:
+            **kwargs: Extra options to send to the Gitlab server (e.g. sudo)
+
+        Returns None (updates the object)
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabGetError: If the server cannot perform the request
+        """
+        path = '%s/%s' % (self.manager.path, self.id)
+        server_data = self.manager.gitlab.http_get(path, **kwargs)
+        self._update_attrs(server_data)
+
+
 class ListMixin(object):
     @exc.on_http_error(exc.GitlabListError)
     def list(self, **kwargs):
diff --git a/gitlab/tests/test_mixins.py b/gitlab/tests/test_mixins.py
@@ -153,6 +153,25 @@ def resp_cont(url, request):
             self.assertEqual(obj.foo, 'bar')
             self.assertEqual(obj.id, 42)
 
+    def test_read_mixin(self):
+        class O(ReadMixin, FakeObject):
+            pass
+
+        @urlmatch(scheme="http", netloc="localhost", path='/api/v4/tests/42',
+                  method="get")
+        def resp_cont(url, request):
+            headers = {'Content-Type': 'application/json'}
+            content = '{"id": 42, "foo": "bar"}'
+            return response(200, content, headers, None, 5, request)
+
+        with HTTMock(resp_cont):
+            mgr = FakeManager(self.gl)
+            obj = O(mgr, {'id': 42})
+            res = obj.read()
+            self.assertIsNone(res)
+            self.assertEqual(obj.foo, 'bar')
+            self.assertEqual(obj.id, 42)
+
     def test_get_without_id_mixin(self):
         class M(GetWithoutIdMixin, FakeManager):
             pass
diff --git a/gitlab/v4/objects.py b/gitlab/v4/objects.py
@@ -909,7 +909,7 @@ class ProjectCustomAttributeManager(RetrieveMixin, SetMixin, DeleteMixin,
     _from_parent_attrs = {'project_id': 'id'}
 
 
-class ProjectJob(RESTObject):
+class ProjectJob(RESTObject, ReadMixin):
     @cli.register_custom_action('ProjectJob')
     @exc.on_http_error(exc.GitlabJobCancelError)
     def cancel(self, **kwargs):
@@ -1964,7 +1964,7 @@ class ProjectPipelineJobsManager(ListMixin, RESTManager):
     _list_filters = ('scope',)
 
 
-class ProjectPipeline(RESTObject):
+class ProjectPipeline(RESTObject, ReadMixin):
     _managers = (('jobs', 'ProjectPipelineJobManager'), )
 
     @cli.register_custom_action('ProjectPipeline')
