Support downloading a single artifact file

Fixes #432

docs/gl_objects/builds.rst

@@ -297,7 +297,7 @@ Get a job:
    :start-after: # get job
    :end-before: # end get job
 
-Get a job artifact:
+Get the artifacts of a job:
 
 .. literalinclude:: builds.py
    :start-after: # artifacts
@@ -316,12 +316,17 @@ stream:
    :start-after: # stream artifacts with class
    :end-before: # end stream artifacts with class
 
-In this second example, you can directly stream the output into a file, and unzip it afterwards:
+In this second example, you can directly stream the output into a file, and
+unzip it afterwards:
 
 .. literalinclude:: builds.py
    :start-after: # stream artifacts with unzip
    :end-before: # end stream artifacts with unzip
 
+Get a single artifact file::
+
+    build_or_job.artifact('path/to/file')
+
 Mark a job artifact as kept when expiration is set:
 
 .. literalinclude:: builds.py

gitlab/v4/objects.py

@@ -1012,6 +1012,34 @@ def artifacts(self, streamed=False, action=None, chunk_size=1024,
                                               **kwargs)
         return utils.response_content(result, streamed, action, chunk_size)
 
+    @cli.register_custom_action('ProjectJob')
+    @exc.on_http_error(exc.GitlabGetError)
+    def artifact(self, path, streamed=False, action=None, chunk_size=1024,
+                 **kwargs):
+        """Get a single artifact file from within the job's artifacts archive.
+
+        Args:
+            path (str): Path of the artifact
+            streamed (bool): If True the data will be processed by chunks of
+                `chunk_size` and each chunk is passed to `action` for
+                treatment
+            action (callable): Callable responsible of dealing with chunk of
+                data
+            chunk_size (int): 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:
+            str: The artifacts if `streamed` is False, None otherwise.
+        """
+        path = '%s/%s/artifacts/%s' % (self.manager.path, self.get_id(), path)
+        result = self.manager.gitlab.http_get(path, streamed=streamed,
+                                              **kwargs)
+        return utils.response_content(result, streamed, action, chunk_size)
+
     @cli.register_custom_action('ProjectJob')
     @exc.on_http_error(exc.GitlabGetError)
     def trace(self, streamed=False, action=None, chunk_size=1024, **kwargs):