From 3424333bc98fcfc4733f2c5f1bf9a93b9a02135b Mon Sep 17 00:00:00 2001
From: Pierre Tardy <tardyp@gmail.com>
Date: Mon, 5 Feb 2018 15:55:11 +0100
Subject: [PATCH] introduce RefreshMixin

RefreshMixin 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.
---
 docs/gl_objects/builds.py   | 16 ++++++++++++++++
 docs/gl_objects/builds.rst  |  6 ++++++
 gitlab/mixins.py            | 19 +++++++++++++++++++
 gitlab/tests/test_mixins.py | 19 +++++++++++++++++++
 gitlab/v4/objects.py        |  6 +++---
 5 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/docs/gl_objects/builds.py b/docs/gl_objects/builds.py
index 0f616e842..03d3653cb 100644
--- a/docs/gl_objects/builds.py
+++ b/docs/gl_objects/builds.py
@@ -44,6 +44,22 @@
 trigger.delete()
 # end trigger delete
 
+# 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.refresh()
+    os.sleep(1)
+
+# end pipeline trigger
+
 # list
 builds = project.builds.list()  # v3
 jobs = project.jobs.list()  # v4
diff --git a/docs/gl_objects/builds.rst b/docs/gl_objects/builds.rst
index 2791188eb..c9b73305a 100644
--- a/docs/gl_objects/builds.rst
+++ b/docs/gl_objects/builds.rst
@@ -102,6 +102,12 @@ Remove a trigger:
    :start-after: # trigger delete
    :end-before: # end trigger delete
 
+Full example with wait for finish:
+
+.. literalinclude:: builds.py
+   :start-after: # pipeline trigger
+   :end-before: # end pipeline trigger
+
 Pipeline schedule
 =================
 
diff --git a/gitlab/mixins.py b/gitlab/mixins.py
index cb35efc8d..ea21e1021 100644
--- 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 RefreshMixin(object):
+    @exc.on_http_error(exc.GitlabGetError)
+    def refresh(self, **kwargs):
+        """Refresh 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
index c51322aac..5c1059791 100644
--- 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_refresh_mixin(self):
+        class O(RefreshMixin, 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.refresh()
+            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
index 16564e4e2..80a6ca562 100644
--- 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, RefreshMixin):
     @cli.register_custom_action('ProjectJob')
     @exc.on_http_error(exc.GitlabJobCancelError)
     def cancel(self, **kwargs):
@@ -1045,7 +1045,7 @@ class ProjectJobManager(RetrieveMixin, RESTManager):
     _from_parent_attrs = {'project_id': 'id'}
 
 
-class ProjectCommitStatus(RESTObject):
+class ProjectCommitStatus(RESTObject, RefreshMixin):
     pass
 
 
@@ -1964,7 +1964,7 @@ class ProjectPipelineJobsManager(ListMixin, RESTManager):
     _list_filters = ('scope',)
 
 
-class ProjectPipeline(RESTObject):
+class ProjectPipeline(RESTObject, RefreshMixin):
     _managers = (('jobs', 'ProjectPipelineJobManager'), )
 
     @cli.register_custom_action('ProjectPipeline')