Add tool-long-listing to ListCommand

This change adds the ability to list all the 'tool variant names'
alongside the version and release date of the tool.

When using the `aqt list tools` feature, I often find that I need more
information than the tool provides. I often need to know the release
date and the version for each tool, and I can't get that information
without looking up the Updates.xml file. This feature enables me to skip
that part.

aqt/archives.py

@@ -40,6 +40,7 @@ from typing import (
 
 import bs4
 from semantic_version import SimpleSpec, Version
+from texttable import Texttable
 
 from aqt import helper
 from aqt.exceptions import (
@@ -130,6 +131,20 @@ class ListCommand:
         def pretty_print(self) -> str:
             return "\n".join(self.strings)
 
+    class Table:
+        def __init__(self, head: List[str], rows: List[List[str]], max_width: int = 0):
+            # max_width is set to 0 by default: this disables wrapping of text table cells
+            self.head = head
+            self.rows = rows
+            self.max_width = max_width
+
+        def pretty_print(self) -> str:
+            table = Texttable(max_width=self.max_width)
+            table.set_deco(Texttable.HEADER)
+            table.header(self.head)
+            table.add_rows(self.rows, header=False)
+            return table.draw()
+
     def __init__(
         self,
         archive_id: ArchiveId,
@@ -140,6 +155,7 @@ class ListCommand:
         extensions_ver: Optional[str] = None,
         architectures_ver: Optional[str] = None,
         tool_name: Optional[str] = None,
+        tool_long_listing: Optional[str] = None,
     ):
         """
         Construct ListCommand.
@@ -160,6 +176,9 @@ class ListCommand:
             if tool_name:
                 self.request_type = "tool variant names"
                 self._action = lambda: self.fetch_tool_modules(tool_name)
+            elif tool_long_listing:
+                self.request_type = "tool long listing"
+                self._action = lambda: self.fetch_tool_long_listing(tool_long_listing)
             else:
                 self.request_type = "tools"
                 self._action = self.fetch_tools
@@ -275,6 +294,22 @@ class ListCommand:
         all_tools_data = self._fetch_tool_data(tool_name)
         return ListCommand.choose_highest_version_in_spec(all_tools_data, simple_spec)
 
+    def fetch_tool_long_listing(self, tool_name: str) -> Table:
+        head = [
+            "Tool Variant Name",
+            "Version",
+            "Release Date",
+            "Display Name",
+            "Description",
+        ]
+        keys = ("Version", "ReleaseDate", "DisplayName", "Description")
+        tool_data = self._fetch_tool_data(tool_name, keys_to_keep=keys)
+        rows = [
+            [name, *[content[key] for key in keys]]
+            for name, content in tool_data.items()
+        ]
+        return ListCommand.Table(head, rows)
+
     @staticmethod
     def choose_highest_version_in_spec(
         all_tools_data: Dict[str, Dict[str, str]], simple_spec: SimpleSpec

aqt/installer.py

@@ -510,6 +510,7 @@ class Cli:
             extensions_ver=args.extensions,
             architectures_ver=args.arch,
             tool_name=args.tool,
+            tool_long_listing=args.tool_long,
         )
         return command.run()
 
@@ -600,6 +601,16 @@ class Cli:
             # TODO: find a better word ^^^^^^^^^^^^^^^^^^^^; this is a mysterious help message
             "The output of this command is intended to be used with `aqt tool`.",
         )
+        output_modifier_exclusive_group.add_argument(
+            "--tool-long",
+            type=str,
+            metavar="TOOL_NAME",
+            help="The name of a tool. Use 'aqt list tools <host> <target>' to see accepted values. "
+            "This flag only works with the 'tools' category, and cannot be combined with any other flags. "
+            "When set, this prints all 'tool variant names' available, along with versions and release dates. "
+            # TODO: find a better word ^^^^^^^^^^^^^^^^^^^^; this is a mysterious help message
+            "The output of this command is formatted as a table.",
+        )
         list_parser.set_defaults(func=self.run_list)
 
     def show_help(self, args=None):

ci/steps.yml

@@ -76,6 +76,11 @@ steps:
         aqt list $qtmajor $(HOST)                                               # print all targets for host
         aqt list tools $(HOST) $(TARGET)                                        # print all tools for host/target
         aqt list tools $(HOST) $(TARGET) --tool tools_qt3dstudio_runtime_240    # print all tool variant names for qt3dstudio
+        aqt list tools $(HOST) $(TARGET) --tool-long tools_qt3dstudio_runtime_240    # print tool variant names, versions, release dates
+        if [[ "$(TARGET)" == "desktop" ]]; then
+          aqt list tools $(HOST) $(TARGET) --tool tools_qtcreator               # print all tool variant names for qtcreator
+          aqt list tools $(HOST) $(TARGET) --tool-long tools_qtcreator          # print tool variant names, versions, release dates
+        fi
         aqt list $qtmajor $(HOST) $(TARGET)                                     # print all versions of Qt
         if [[ $(HAS_WASM_EXTENSION) == "True" ]]; then
           aqt list $qtmajor $(HOST) $(TARGET) --extension wasm                  # print all wasm versions of Qt5

tests/data/mac-desktop-tools_cmake-expect.json

@@ -1,5 +1,14 @@
 {
   "modules": [
     "qt.tools.cmake"
+  ],
+  "long_listing": [
+    [
+      "qt.tools.cmake",
+      "3.19.2-202101071155",
+      "2021-01-07",
+      "CMake 3.19.2",
+      "CMake tools 3.19.2"
+    ]
   ]
 }

tests/data/mac-desktop-tools_ifw-expect.json

@@ -1,5 +1,14 @@
 {
   "modules": [
     "qt.tools.ifw.41"
+  ],
+  "long_listing": [
+    [
+      "qt.tools.ifw.41",
+      "4.1.1-202105261132",
+      "2021-05-26",
+      "Qt Installer Framework 4.1",
+      "The Qt Installer Framework provides a set of tools and utilities to create installers for the supported desktop Qt platforms: Linux, Microsoft Windows, and macOS."
+    ]
   ]
 }

tests/data/mac-desktop-tools_qtcreator-expect.json

@@ -3,5 +3,28 @@
     "qt.tools.qtcreator",
     "qt.tools.qtcreatordbg",
     "qt.tools.qtcreatordev"
+  ],
+  "long_listing": [
+    [
+      "qt.tools.qtcreator",
+      "4.15.1-0-202106081242",
+      "2021-06-08",
+      "Qt Creator 4.15.1",
+      "IDE for Qt application development"
+    ],
+    [
+      "qt.tools.qtcreatordbg",
+      "4.15.1-0-202106081242",
+      "2021-06-08",
+      "Qt Creator 4.15.1 Debug Symbols",
+      "Additional symbol files required to debug Qt Creator"
+    ],
+    [
+      "qt.tools.qtcreatordev",
+      "4.15.1-0-202106081242",
+      "2021-06-08",
+      "Qt Creator 4.15.1 Plugin Development",
+      "Headers and libs required to develop additional plugins"
+    ]
   ]
 }

tests/test_list.py

@@ -3,7 +3,7 @@ import re
 from pathlib import Path
 
 import pytest
-from semantic_version import Version, SimpleSpec
+from semantic_version import SimpleSpec, Version
 
 from aqt import archives, installer
 from aqt.archives import ListCommand
@@ -129,6 +129,29 @@ def test_tool_modules(monkeypatch, host: str, target: str, tool_name: str):
     assert modules.strings == expect["modules"]
 
 
+@pytest.mark.parametrize(
+    "host, target, tool_name",
+    [
+        ("mac", "desktop", "tools_cmake"),
+        ("mac", "desktop", "tools_ifw"),
+        ("mac", "desktop", "tools_qtcreator"),
+    ],
+)
+def test_tool_long_listing(monkeypatch, host: str, target: str, tool_name: str):
+    archive_id = ArchiveId("tools", host, target)
+    in_file = "{}-{}-{}-update.xml".format(host, target, tool_name)
+    expect_out_file = "{}-{}-{}-expect.json".format(host, target, tool_name)
+    _xml = (Path(__file__).parent / "data" / in_file).read_text("utf-8")
+    expect = json.loads(
+        (Path(__file__).parent / "data" / expect_out_file).read_text("utf-8")
+    )
+
+    monkeypatch.setattr(archives.ListCommand, "fetch_http", lambda self, _: _xml)
+
+    table = ListCommand(archive_id).fetch_tool_long_listing(tool_name)
+    assert table.rows == expect["long_listing"]
+
+
 @pytest.mark.parametrize(
     "cat, host, target, minor_ver, ver, ext, xmlfile, xmlexpect, htmlfile, htmlexpect",
     [