new: Improve generated command help page formatting using Rich (#585)

Author: lgarber-akamai

linodecli/__init__.py

@@ -15,16 +15,15 @@
 from linodecli import plugins
 
 from .arg_helpers import (
-    action_help,
     bake_command,
-    help_with_ops,
     register_args,
     register_plugin,
     remove_plugin,
 )
 from .cli import CLI
 from .completion import bake_completions, get_completions
 from .configuration import ENV_TOKEN_NAME
+from .help_pages import print_help_action, print_help_default
 from .helpers import handle_url_overrides
 from .output import OutputMode
 
@@ -155,7 +154,7 @@ def main():  # pylint: disable=too-many-branches,too-many-statements
     # handle a help for the CLI
     if parsed.command is None or (parsed.command is None and parsed.help):
         parser.print_help()
-        help_with_ops(cli.ops, cli.config)
+        print_help_default(cli.ops, cli.config)
         sys.exit(0)
 
     # configure
@@ -257,6 +256,6 @@ def main():  # pylint: disable=too-many-branches,too-many-statements
 
     if parsed.command is not None and parsed.action is not None:
         if parsed.help:
-            action_help(cli, parsed.command, parsed.action)
+            print_help_action(cli, parsed.command, parsed.action)
             sys.exit(0)
         cli.handle_command(parsed.command, parsed.action, args)

linodecli/arg_helpers.py

@@ -5,14 +5,10 @@
 
 import os
 import sys
-import textwrap
 from importlib import import_module
 
 import requests
 import yaml
-from rich import box
-from rich import print as rprint
-from rich.table import Table
 
 from linodecli import plugins
 
@@ -247,176 +243,6 @@ def remove_plugin(plugin_name, config):
     return f"Plugin {plugin_name} removed", 0
 
 
-# pylint: disable=too-many-locals
-def help_with_ops(ops, config):
-    """
-    Prints help output with options from the API spec
-    """
-
-    # Environment variables overrides
-    print("\nEnvironment variables:")
-    env_variables = {
-        "LINODE_CLI_TOKEN": "A Linode Personal Access Token for the CLI to make requests with. "
-        "If specified, the configuration step will be skipped.",
-        "LINODE_CLI_CA": "The path to a custom Certificate Authority file to verify "
-        "API requests against.",
-        "LINODE_CLI_API_HOST": "Overrides the target host for API requests. "
-        "(e.g. 'api.linode.com')",
-        "LINODE_CLI_API_VERSION": "Overrides the target Linode API version for API requests. "
-        "(e.g. 'v4beta')",
-        "LINODE_CLI_API_SCHEME": "Overrides the target scheme used for API requests. "
-        "(e.g. 'https')",
-    }
-
-    table = Table(show_header=True, header_style="", box=box.SQUARE)
-    table.add_column("Name")
-    table.add_column("Description")
-
-    for k, v in env_variables.items():
-        table.add_row(k, v)
-
-    rprint(table)
-
-    # commands to manage CLI users (don't call out to API)
-    print("\nCLI user management commands:")
-    um_commands = [["configure", "set-user", "show-users"], ["remove-user"]]
-    table = Table(show_header=False)
-    for cmd in um_commands:
-        table.add_row(*cmd)
-    rprint(table)
-
-    # commands to manage plugins (don't call out to API)
-    print("\nCLI Plugin management commands:")
-    pm_commands = [["register-plugin", "remove-plugin"]]
-    table = Table(show_header=False)
-    for cmd in pm_commands:
-        table.add_row(*cmd)
-    rprint(table)
-
-    # other CLI commands
-    print("\nOther CLI commands:")
-    other_commands = [["completion"]]
-    table = Table(show_header=False)
-    for cmd in other_commands:
-        table.add_row(*cmd)
-    rprint(table)
-
-    # commands generated from the spec (call the API directly)
-    print("\nAvailable commands:")
-
-    content = list(sorted(ops.keys()))
-    proc = []
-    for i in range(0, len(content), 3):
-        proc.append(content[i : i + 3])
-    if content[i + 3 :]:
-        proc.append(content[i + 3 :])
-
-    table = Table(show_header=False)
-    for cmd in proc:
-        table.add_row(*cmd)
-    rprint(table)
-
-    # plugins registered to the CLI (do arbitrary things)
-    if plugins.available(config):
-        # only show this if there are any available plugins
-        print("Available plugins:")
-
-        plugin_content = list(plugins.available(config))
-        plugin_proc = []
-
-        for i in range(0, len(plugin_content), 3):
-            plugin_proc.append(plugin_content[i : i + 3])
-        if plugin_content[i + 3 :]:
-            plugin_proc.append(plugin_content[i + 3 :])
-
-        plugin_table = Table(show_header=False)
-        for plugin in plugin_proc:
-            plugin_table.add_row(*plugin)
-        rprint(plugin_table)
-
-    print("\nTo reconfigure, call `linode-cli configure`")
-    print(
-        "For comprehensive documentation,"
-        "visit https://www.linode.com/docs/api/"
-    )
-
-
-def action_help(cli, command, action):  # pylint: disable=too-many-branches
-    """
-    Prints help relevant to the command and action
-    """
-    try:
-        op = cli.find_operation(command, action)
-    except ValueError:
-        return
-    print(f"linode-cli {command} {action}", end="")
-
-    for param in op.params:
-        pname = param.name.upper()
-        print(f" [{pname}]", end="")
-
-    print()
-    print(op.summary)
-
-    if op.docs_url:
-        rprint(f"API Documentation: [link={op.docs_url}]{op.docs_url}[/link]")
-
-    if len(op.samples) > 0:
-        print()
-        print(f"Example Usage{'s' if len(op.samples) > 1 else ''}: ")
-
-        rprint(
-            *[
-                # Indent all samples for readability; strip and trailing newlines
-                textwrap.indent(v.get("source").rstrip(), "  ")
-                for v in op.samples
-            ],
-            sep="\n\n",
-        )
-
-    print()
-    if op.method == "get" and op.action == "list":
-        filterable_attrs = [
-            attr for attr in op.response_model.attrs if attr.filterable
-        ]
-
-        if filterable_attrs:
-            print("You may filter results with:")
-            for attr in filterable_attrs:
-                print(f"  --{attr.name}")
-            print(
-                "Additionally, you may order results using --order-by and --order."
-            )
-        return
-    if op.args:
-        print("Arguments:")
-        for arg in sorted(op.args, key=lambda s: not s.required):
-            if arg.read_only:
-                continue
-            is_required = (
-                "(required) "
-                if op.method in {"post", "put"} and arg.required
-                else ""
-            )
-
-            extensions = []
-
-            if arg.format == "json":
-                extensions.append("JSON")
-
-            if arg.nullable:
-                extensions.append("nullable")
-
-            if arg.is_parent:
-                extensions.append("conflicts with children")
-
-            suffix = (
-                f" ({', '.join(extensions)})" if len(extensions) > 0 else ""
-            )
-
-            print(f"  --{arg.path}: {is_required}{arg.description}{suffix}")
-
-
 def bake_command(cli, spec_loc):
     """
     Handle a bake command from args

linodecli/baked/request.py

@@ -16,6 +16,7 @@ def __init__(
         prefix=None,
         is_parent=False,
         parent=None,
+        depth=0,
     ):  # pylint: disable=too-many-arguments
         """
         Parses a single Schema node into a argument the CLI can use when making
@@ -33,6 +34,8 @@ def __init__(
         :type is_parent: bool
         :param parent: If applicable, the path to the parent list for this argument.
         :type parent: Optional[str]
+        :param depth: The depth of this argument, or how many parent arguments this argument has.
+        :type depth: int
         """
         #: The name of this argument, mostly used for display and docs
         self.name = name
@@ -85,6 +88,10 @@ def __init__(
         #: e.g. --interfaces.ipv4.nat_1_1
         self.parent = parent
 
+        #: The depth of this argument, or how many parent arguments this argument has.
+        #: This is useful when formatting help pages.
+        self.depth = depth
+
         #: The path of the path element in the schema.
         self.prefix = prefix
 
@@ -103,7 +110,7 @@ def __init__(
             )
 
 
-def _parse_request_model(schema, prefix=None, parent=None):
+def _parse_request_model(schema, prefix=None, parent=None, depth=0):
     """
     Parses a schema into a list of OpenAPIRequest objects
     :param schema: The schema to parse as a request model
@@ -130,6 +137,9 @@ def _parse_request_model(schema, prefix=None, parent=None):
                     v,
                     prefix=pref,
                     parent=parent,
+                    # NOTE: We do not increment the depth because dicts do not have
+                    # parent arguments.
+                    depth=depth,
                 )
             elif (
                 v.type == "array"
@@ -150,10 +160,16 @@ def _parse_request_model(schema, prefix=None, parent=None):
                         prefix=prefix,
                         is_parent=True,
                         parent=parent,
+                        depth=depth,
                     )
                 )
 
-                args += _parse_request_model(v.items, prefix=pref, parent=pref)
+                args += _parse_request_model(
+                    v.items,
+                    prefix=pref,
+                    parent=pref,
+                    depth=depth + 1,
+                )
             else:
                 # required fields are defined in the schema above the property, so
                 # we have to check here if required fields are defined/if this key
@@ -163,7 +179,12 @@ def _parse_request_model(schema, prefix=None, parent=None):
                     required = k in schema.required
                 args.append(
                     OpenAPIRequestArg(
-                        k, v, required, prefix=prefix, parent=parent
+                        k,
+                        v,
+                        required,
+                        prefix=prefix,
+                        parent=parent,
+                        depth=depth,
                     )
                 )