feat(api): add MR pipeline manager in favor of pipelines() method

nejch · nejch · commit 1cc86d8aabc2 · 2021-02-26T18:44:45.000+01:00
diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst
@@ -127,10 +127,6 @@ List the changes of a MR::
 
     changes = mr.changes()
 
-List the pipelines for a MR::
-
-    pipelines = mr.pipelines()
-
 List issues that will close on merge::
 
     mr.closes_issues()
@@ -185,3 +181,31 @@ Get user agent detail for the issue (admin only)::
 Attempt to rebase an MR::
 
     mr.rebase()
+
+Merge Request Pipelines
+=======================
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.MergeRequestPipeline`
+  + :class:`gitlab.v4.objects.MergeRequestPipelineManager`
+  + :attr:`gitlab.v4.objects.ProjectMergeRequest.pipelines`
+
+* GitLab API: https://docs.gitlab.com/ee/api/merge_requests.html#list-mr-pipelines
+
+Examples
+--------
+
+List pipelines for a merge request::
+
+    pipelines = mr.pipelines.list()
+
+    # Deprecated, will be removed
+    pipelines = mr.pipelines()
+
+Create a pipeline for a merge request::
+
+    pipeline = mr.pipelines.create()
diff --git a/gitlab/tests/objects/test_merge_request_pipelines.py b/gitlab/tests/objects/test_merge_request_pipelines.py
@@ -0,0 +1,66 @@
+"""
+GitLab API: https://docs.gitlab.com/ee/api/merge_requests.html#list-mr-pipelines
+"""
+import re
+
+import pytest
+import responses
+
+from gitlab.v4.objects import MergeRequestPipeline
+
+pipeline_content = {
+    "id": 1,
+    "sha": "959e04d7c7a30600c894bd3c0cd0e1ce7f42c11d",
+    "ref": "master",
+    "status": "success",
+}
+
+
+@pytest.fixture()
+def resp_list_merge_request_pipelines():
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.GET,
+            url="http://localhost/api/v4/projects/1/merge_requests/1/pipelines",
+            json=[pipeline_content],
+            content_type="application/json",
+            status=200,
+        )
+        yield rsps
+
+
+@pytest.fixture()
+def resp_create_merge_request_pipeline():
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.POST,
+            url="http://localhost/api/v4/projects/1/merge_requests/1/pipelines",
+            json=pipeline_content,
+            content_type="application/json",
+            status=201,
+        )
+        yield rsps
+
+
+def test_merge_requests_pipelines_deprecated_raises_warning(
+    project, resp_list_merge_request_pipelines
+):
+    with pytest.deprecated_call():
+        pipelines = project.mergerequests.get(1, lazy=True).pipelines()
+
+    assert len(pipelines) == 1
+    assert isinstance(pipelines[0], MergeRequestPipeline)
+    assert pipelines[0].sha == pipeline_content["sha"]
+
+
+def test_list_merge_requests_pipelines(project, resp_list_merge_request_pipelines):
+    pipelines = project.mergerequests.get(1, lazy=True).pipelines.list()
+    assert len(pipelines) == 1
+    assert isinstance(pipelines[0], MergeRequestPipeline)
+    assert pipelines[0].sha == pipeline_content["sha"]
+
+
+def test_create_merge_requests_pipelines(project, resp_create_merge_request_pipeline):
+    pipeline = project.mergerequests.get(1, lazy=True).pipelines.create()
+    assert isinstance(pipeline, MergeRequestPipeline)
+    assert pipeline.sha == pipeline_content["sha"]
diff --git a/gitlab/v4/objects/merge_requests.py b/gitlab/v4/objects/merge_requests.py
@@ -25,6 +25,7 @@
     ProjectMergeRequestResourceLabelEventManager,
     ProjectMergeRequestResourceMilestoneEventManager,
 )
+from .pipelines import MergeRequestPipelineManager
 
 
 __all__ = [
@@ -119,6 +120,7 @@ class ProjectMergeRequest(
         ("diffs", "ProjectMergeRequestDiffManager"),
         ("discussions", "ProjectMergeRequestDiscussionManager"),
         ("notes", "ProjectMergeRequestNoteManager"),
+        ("pipelines", "MergeRequestPipelineManager"),
         ("resourcelabelevents", "ProjectMergeRequestResourceLabelEventManager"),
         ("resourcemilestoneevents", "ProjectMergeRequestResourceMilestoneEventManager"),
     )
@@ -213,25 +215,6 @@ def changes(self, **kwargs):
         path = "%s/%s/changes" % (self.manager.path, self.get_id())
         return self.manager.gitlab.http_get(path, **kwargs)
 
-    @cli.register_custom_action("ProjectMergeRequest")
-    @exc.on_http_error(exc.GitlabListError)
-    def pipelines(self, **kwargs):
-        """List the merge request pipelines.
-
-        Args:
-            **kwargs: Extra options to send to the server (e.g. sudo)
-
-        Raises:
-            GitlabAuthenticationError: If authentication is not correct
-            GitlabListError: If the list could not be retrieved
-
-        Returns:
-            RESTObjectList: List of changes
-        """
-
-        path = "%s/%s/pipelines" % (self.manager.path, self.get_id())
-        return self.manager.gitlab.http_get(path, **kwargs)
-
     @cli.register_custom_action("ProjectMergeRequest", tuple(), ("sha"))
     @exc.on_http_error(exc.GitlabMRApprovalError)
     def approve(self, sha=None, **kwargs):
diff --git a/gitlab/v4/objects/pipelines.py b/gitlab/v4/objects/pipelines.py
@@ -1,3 +1,5 @@
+import warnings
+
 from gitlab import cli, types
 from gitlab import exceptions as exc
 from gitlab.base import RESTManager, RESTObject
@@ -15,6 +17,8 @@
 
 
 __all__ = [
+    "MergeRequestPipeline",
+    "MergeRequestPipelineManager",
     "ProjectPipeline",
     "ProjectPipelineManager",
     "ProjectPipelineJob",
@@ -30,6 +34,44 @@
 ]
 
 
+class MergeRequestPipeline(RESTObject):
+    pass
+
+
+class MergeRequestPipelineManager(CreateMixin, ListMixin, RESTManager):
+    _path = "/projects/%(project_id)s/merge_requests/%(mr_iid)s/pipelines"
+    _obj_cls = MergeRequestPipeline
+    _from_parent_attrs = {"project_id": "project_id", "mr_iid": "iid"}
+    _create_attrs = (tuple(), tuple())
+
+    # If the manager was called directly as a callable via
+    # mr.pipelines(), execute the deprecated method for now.
+    # TODO: in python-gitlab 3.0.0, remove this method entirely.
+
+    @cli.register_custom_action("ProjectMergeRequest")
+    @exc.on_http_error(exc.GitlabListError)
+    def __call__(self, **kwargs):
+        """List the merge request pipelines.
+
+        Args:
+            **kwargs: Extra options to send to the server (e.g. sudo)
+
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabListError: If the list could not be retrieved
+
+        Returns:
+            RESTObjectList: List of changes
+        """
+        warnings.warn(
+            "Calling the ProjectMergeRequest.pipelines() method on "
+            "merge request objects directly is deprecated and will be replaced "
+            "by ProjectMergeRequest.pipelines.list() in python-gitlab 3.0.0.\n",
+            DeprecationWarning,
+        )
+        return self.list(**kwargs)
+
+
 class ProjectPipeline(RESTObject, RefreshMixin, ObjectDeleteMixin):
     _managers = (
         ("jobs", "ProjectPipelineJobManager"),
