Addition of bst artifact list-contents:becky/artifact_list_contents

this commit introduces the bst artifact list-contents
command. When used it provides the user with a list of
the contents within the artifact.
Tests and a NEWS entry have also been added for the command.

2 files changed, 60 insertions, 0 deletions

diff --git a/src/buildstream/_frontend/cli.py b/src/buildstream/_frontend/cli.py
index 276f81a6a..36383b3dd 100644
--- a/src/buildstream/_frontend/cli.py
+++ b/src/buildstream/_frontend/cli.py
@@ -1218,6 +1218,30 @@ def artifact_log(app, artifacts):
                         click.echo_via_pager(data)
 
 
+################################################################
+#                Artifact List-Contents Command                #
+################################################################
+@artifact.command(name='list-contents', short_help="List the contents of an artifact")
+@click.argument('artifacts', type=click.Path(), nargs=-1)
+@click.pass_obj
+def artifact_list_contents(app, artifacts):
+    """List the contents of an artifact.
+
+    Note that 'artifacts' can be element names, which must end in '.bst',
+    or artifact references, which must be in the format `<project_name>/<element>/<key>`.
+
+    """
+    # Note that the backticks in the above docstring are important for the
+    # generated docs. When sphinx is generating rst output from the help output
+    # of this command, the asterisks will be interpreted as emphasis tokens if
+    # they are not somehow escaped.
+
+    with app.initialized():
+        elements_to_files = app.stream.artifact_list_contents(artifacts)
+        click.echo(app.logger._pretty_print_dictionary(elements_to_files))
+        sys.exit(0)
+
+
 ###################################################################
 #                     Artifact Delete Command                     #
 ###################################################################
diff --git a/src/buildstream/_frontend/widget.py b/src/buildstream/_frontend/widget.py
index fbde249a9..b0472bd45 100644
--- a/src/buildstream/_frontend/widget.py
+++ b/src/buildstream/_frontend/widget.py
@@ -801,3 +801,39 @@ class LogLine(Widget):
             text += '\n'
 
         return text
+
+    # _pretty_print_dictionary()
+    #
+    # Formats a dictionary so it can be easily read by the user
+    #
+    # Args:
+    #    values: A dictionary
+    #    style_value: Whether to use the content profile for the values
+    #
+    # Returns:
+    #    (str): The formatted values
+    #
+    def _pretty_print_dictionary(self, values, style_value=True):
+        text = ''
+        max_key_len = 0
+        for key, value in values.items():
+            max_key_len = max(len(key), max_key_len)
+
+        for key, value in values.items():
+            if isinstance(value, str) and '\n' in value:
+                text += self.format_profile.fmt("  {}:".format(key))
+                text += textwrap.indent(value, self._indent)
+                continue
+
+            text += self.format_profile.fmt("  {}:{}".format(key, ' ' * (max_key_len - len(key))))
+
+            value_list = ''
+            for item in value:
+                value_list += "\n\t{}".format(item)
+            if style_value:
+                text += self.content_profile.fmt(value_list)
+            else:
+                text += value_list
+            text += '\n'
+
+        return text