CLI: Port "ara host list" command from 0.x

This allows to list all hosts, those matching a provided host name or
for a specific playbook.

Change-Id: I882903bf86658fc04ff5af521c7c9c7e282d945a

ara/cli/host.py

@@ -0,0 +1,82 @@
+# Copyright (c) 2020 The ARA Records Ansible authors
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+import logging
+
+from cliff.lister import Lister
+
+from ara.cli.base import global_arguments
+from ara.clients.utils import get_client
+
+
+class HostList(Lister):
+    """ Returns a list of hosts based on search queries """
+
+    log = logging.getLogger(__name__)
+
+    def get_parser(self, prog_name):
+        parser = super(HostList, self).get_parser(prog_name)
+        parser = global_arguments(parser)
+        # fmt: off
+        # Host search arguments and ordering as per ara.api.filters.HostFilter
+        # TODO: non-exhaustive (searching for failed, ok, unreachable, etc.)
+        parser.add_argument(
+            "--name",
+            metavar="<name>",
+            default=None,
+            help=("List hosts matching the provided name (full or partial)"),
+        )
+        parser.add_argument(
+            "--playbook",
+            metavar="<playbook_id>",
+            default=None,
+            help=("List hosts for a specified playbook id"),
+        )
+        parser.add_argument(
+            "--order",
+            metavar="<order>",
+            default="-updated",
+            help=(
+                "Orders results by a field ('id', 'created', 'updated', 'name')\n"
+                "Defaults to '-updated' descending so the most recent host is at the top.\n"
+                "The order can be reversed by omitting the '-': ara host list --order=updated"
+            ),
+        )
+        parser.add_argument(
+            "--limit",
+            metavar="<limit>",
+            default=100,
+            help=("Returns the first <limit> determined by the ordering. Defaults to 100.")
+        )
+        # fmt: on
+        return parser
+
+    def take_action(self, args):
+        client = get_client(
+            client=args.client,
+            endpoint=args.server,
+            timeout=args.timeout,
+            username=args.username,
+            password=args.password,
+            verify=False if args.insecure else True,
+        )
+        query = {}
+        if args.name is not None:
+            query["name"] = args.name
+
+        if args.playbook is not None:
+            query["playbook"] = args.playbook
+
+        query["order"] = args.order
+        query["limit"] = args.limit
+
+        hosts = client.get("/api/v1/hosts", **query)
+        columns = ("id", "name", "playbook", "changed", "failed", "ok", "skipped", "unreachable", "updated")
+        # fmt: off
+        return (
+            columns, (
+                [host[column] for column in columns]
+                for host in hosts["results"]
+            )
+        )
+        # fmt: on

doc/source/cli.rst

@@ -65,6 +65,35 @@ ara playbook delete
 
 .. command-output:: ara playbook delete --help
 
+ara host list
+-------------
+
+.. command-output:: ara host list --help
+
+.. note::
+
+    From the perspective of ARA, each host is unique to a playbook run.
+    Their records contain the Ansible host facts as well as their stats for a
+    particular playbook run.
+
+Search for a specific host name across playbook runs against a local API server:
+
+.. code-block:: bash
+
+    ara host list --client http --server http://127.0.0.1:8000 --name localhost
+
+List the 100 most recently updated hosts using the offline API client:
+
+.. code-block:: bash
+
+    ara host list
+
+List the host results for a specific playbook and format the result in json:
+
+.. code-block:: bash
+
+    ara host list --playbook 1 -f json
+
 CLI: ara-manage (django)
 ========================
 

setup.cfg

@@ -38,6 +38,7 @@ ara.cli =
     playbook list = ara.cli.playbook:PlaybookList
     playbook show = ara.cli.playbook:PlaybookShow
     playbook delete = ara.cli.playbook:PlaybookDelete
+    host list = ara.cli.host:HostList
 
 [extras]
 server=