feat(objects): add a complete artifacts manager

3 files changed, 133 insertions, 81 deletions

diff --git a/gitlab/v4/objects/__init__.py b/gitlab/v4/objects/__init__.py
index ac118c0..40f9bf3 100644
--- a/gitlab/v4/objects/__init__.py
+++ b/gitlab/v4/objects/__init__.py
@@ -18,6 +18,7 @@
 from .access_requests import *
 from .appearance import *
 from .applications import *
+from .artifacts import *
 from .audit_events import *
 from .award_emojis import *
 from .badges import *
diff --git a/gitlab/v4/objects/artifacts.py b/gitlab/v4/objects/artifacts.py
new file mode 100644
index 0000000..2c382ca
--- /dev/null
+++ b/gitlab/v4/objects/artifacts.py
@@ -0,0 +1,124 @@
+"""
+GitLab API:
+https://docs.gitlab.com/ee/api/job_artifacts.html
+"""
+import warnings
+from typing import Any, Callable, Optional, TYPE_CHECKING
+
+import requests
+
+from gitlab import cli
+from gitlab import exceptions as exc
+from gitlab import utils
+from gitlab.base import RESTManager, RESTObject
+
+__all__ = ["ProjectArtifact", "ProjectArtifactManager"]
+
+
+class ProjectArtifact(RESTObject):
+    """Dummy object to manage custom actions on artifacts"""
+    _id_attr = "ref_name"
+
+
+class ProjectArtifactManager(RESTManager):
+    _obj_cls = ProjectArtifact
+    _path = "/projects/{project_id}/jobs/artifacts"
+    _from_parent_attrs = {"project_id": "id"}
+
+    @cli.register_custom_action(
+        "Project", ("ref_name", "job"), ("job_token",), custom_action="artifacts"
+    )
+    def __call__(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Optional[bytes]:
+        warnings.warn(
+            "The project.artifacts() method is deprecated and will be "
+            "removed in a future version. Use project.artifacts.download() instead.\n",
+            DeprecationWarning,
+        )
+        return self.download(
+            *args,
+            **kwargs,
+        )
+
+    @cli.register_custom_action(
+        "ProjectArtifactManager", ("ref_name", "job"), ("job_token",)
+    )
+    @exc.on_http_error(exc.GitlabGetError)
+    def download(
+        self,
+        ref_name: str,
+        job: str,
+        streamed: bool = False,
+        action: Optional[Callable] = None,
+        chunk_size: int = 1024,
+        **kwargs: Any,
+    ) -> Optional[bytes]:
+        """Get the job artifacts archive from a specific tag or branch.
+        Args:
+            ref_name: Branch or tag name in repository. HEAD or SHA references
+            are not supported.
+            job: The name of the job.
+            job_token: Job token for multi-project pipeline triggers.
+            streamed: If True the data will be processed by chunks of
+                `chunk_size` and each chunk is passed to `action` for
+                treatment
+            action: Callable responsible of dealing with chunk of
+                data
+            chunk_size: Size of each chunk
+            **kwargs: Extra options to send to the server (e.g. sudo)
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabGetError: If the artifacts could not be retrieved
+        Returns:
+            The artifacts if `streamed` is False, None otherwise.
+        """
+        path = f"{self.path}/{ref_name}/download"
+        result = self.gitlab.http_get(
+            path, job=job, streamed=streamed, raw=True, **kwargs
+        )
+        if TYPE_CHECKING:
+            assert isinstance(result, requests.Response)
+        return utils.response_content(result, streamed, action, chunk_size)
+
+    @cli.register_custom_action("ProjectArtifactManager", ("ref_name", "artifact_path", "job"))
+    @exc.on_http_error(exc.GitlabGetError)
+    def raw(
+        self,
+        ref_name: str,
+        artifact_path: str,
+        job: str,
+        streamed: bool = False,
+        action: Optional[Callable] = None,
+        chunk_size: int = 1024,
+        **kwargs: Any,
+    ) -> Optional[bytes]:
+        """Download a single artifact file from a specific tag or branch from
+        within the job's artifacts archive.
+        Args:
+            ref_name: Branch or tag name in repository. HEAD or SHA references
+                are not supported.
+            artifact_path: Path to a file inside the artifacts archive.
+            job: The name of the job.
+            streamed: If True the data will be processed by chunks of
+                `chunk_size` and each chunk is passed to `action` for
+                treatment
+            action: Callable responsible of dealing with chunk of
+                data
+            chunk_size: Size of each chunk
+            **kwargs: Extra options to send to the server (e.g. sudo)
+        Raises:
+            GitlabAuthenticationError: If authentication is not correct
+            GitlabGetError: If the artifacts could not be retrieved
+        Returns:
+            The artifact if `streamed` is False, None otherwise.
+        """
+        path = f"{self.path}/{ref_name}/raw/{artifact_path}"
+        result = self.gitlab.http_get(
+            path, streamed=streamed, raw=True, job=job, **kwargs
+        )
+        if TYPE_CHECKING:
+            assert isinstance(result, requests.Response)
+        return utils.response_content(result, streamed, action, chunk_size)
diff --git a/gitlab/v4/objects/projects.py b/gitlab/v4/objects/projects.py
index 23f3d3c..d1e993b 100644
--- a/gitlab/v4/objects/projects.py
+++ b/gitlab/v4/objects/projects.py
@@ -18,6 +18,7 @@ from gitlab.mixins import (
 )
 
 from .access_requests import ProjectAccessRequestManager  # noqa: F401
+from .artifacts import ProjectArtifactManager  # noqa: F401
 from .audit_events import ProjectAuditEventManager  # noqa: F401
 from .badges import ProjectBadgeManager  # noqa: F401
 from .boards import ProjectBoardManager  # noqa: F401
@@ -136,6 +137,7 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO
     additionalstatistics: ProjectAdditionalStatisticsManager
     approvalrules: ProjectApprovalRuleManager
     approvals: ProjectApprovalManager
+    artifacts: ProjectArtifactManager
     audit_events: ProjectAuditEventManager
     badges: ProjectBadgeManager
     boards: ProjectBoardManager
@@ -553,94 +555,19 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO
         )
         return self.transfer(*args, **kwargs)
 
-    @cli.register_custom_action("Project", ("ref_name", "job"), ("job_token",))
-    @exc.on_http_error(exc.GitlabGetError)
-    def artifacts(
-        self,
-        ref_name: str,
-        job: str,
-        streamed: bool = False,
-        action: Optional[Callable] = None,
-        chunk_size: int = 1024,
-        **kwargs: Any,
-    ) -> Optional[bytes]:
-        """Get the job artifacts archive from a specific tag or branch.
-
-        Args:
-            ref_name: Branch or tag name in repository. HEAD or SHA references
-            are not supported.
-            artifact_path: Path to a file inside the artifacts archive.
-            job: The name of the job.
-            job_token: Job token for multi-project pipeline triggers.
-            streamed: If True the data will be processed by chunks of
-                `chunk_size` and each chunk is passed to `action` for
-                treatment
-            action: Callable responsible of dealing with chunk of
-                data
-            chunk_size: Size of each chunk
-            **kwargs: Extra options to send to the server (e.g. sudo)
-
-        Raises:
-            GitlabAuthenticationError: If authentication is not correct
-            GitlabGetError: If the artifacts could not be retrieved
-
-        Returns:
-            The artifacts if `streamed` is False, None otherwise.
-        """
-        path = f"/projects/{self.encoded_id}/jobs/artifacts/{ref_name}/download"
-        result = self.manager.gitlab.http_get(
-            path, job=job, streamed=streamed, raw=True, **kwargs
-        )
-        if TYPE_CHECKING:
-            assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, action, chunk_size)
-
     @cli.register_custom_action("Project", ("ref_name", "artifact_path", "job"))
     @exc.on_http_error(exc.GitlabGetError)
     def artifact(
         self,
-        ref_name: str,
-        artifact_path: str,
-        job: str,
-        streamed: bool = False,
-        action: Optional[Callable] = None,
-        chunk_size: int = 1024,
+        *args: Any,
         **kwargs: Any,
     ) -> Optional[bytes]:
-        """Download a single artifact file from a specific tag or branch from
-        within the job’s artifacts archive.
-
-        Args:
-            ref_name: Branch or tag name in repository. HEAD or SHA references
-                are not supported.
-            artifact_path: Path to a file inside the artifacts archive.
-            job: The name of the job.
-            streamed: If True the data will be processed by chunks of
-                `chunk_size` and each chunk is passed to `action` for
-                treatment
-            action: Callable responsible of dealing with chunk of
-                data
-            chunk_size: Size of each chunk
-            **kwargs: Extra options to send to the server (e.g. sudo)
-
-        Raises:
-            GitlabAuthenticationError: If authentication is not correct
-            GitlabGetError: If the artifacts could not be retrieved
-
-        Returns:
-            The artifacts if `streamed` is False, None otherwise.
-        """
-
-        path = (
-            f"/projects/{self.encoded_id}/jobs/artifacts/{ref_name}/raw/"
-            f"{artifact_path}?job={job}"
-        )
-        result = self.manager.gitlab.http_get(
-            path, streamed=streamed, raw=True, **kwargs
+        warnings.warn(
+            "The project.artifact() method is deprecated and will be "
+            "removed in a future version. Use project.artifacts.raw() instead.",
+            DeprecationWarning,
         )
-        if TYPE_CHECKING:
-            assert isinstance(result, requests.Response)
-        return utils.response_content(result, streamed, action, chunk_size)
+        return self.artifacts.raw(*args, **kwargs)
 
 
 class ProjectManager(CRUDMixin, RESTManager):