feat(cli): add a custom help formatter

weakcamel · JohnVillalovos · nejch · JohnVillalovos · commit 005ba93074d3 · 2022-07-28T07:09:08.000-07:00
Add a custom argparse help formatter that overrides the output
format to list items vertically.

The formatter is derived from argparse.HelpFormatter with minimal changes.

Co-authored-by: John Villalovos &lt;john@sodarock.com&gt;
Co-authored-by: Nejc Habjan &lt;nejc.habjan@siemens.com&gt;
diff --git a/gitlab/cli.py b/gitlab/cli.py
@@ -50,6 +50,23 @@
 __F = TypeVar("__F", bound=Callable[..., Any])
 
 
+class VerticalHelpFormatter(argparse.HelpFormatter):
+    def format_help(self) -> str:
+        result = super().format_help()
+        output = ""
+        indent = self._indent_increment * " "
+        for line in result.splitlines(keepends=True):
+            # All of our resources are on one line and wrapped inside braces.
+            # For example: {application,resource1,resource2}
+            # We then put each resource on its own line to make it easier to read.
+            if line.strip().startswith("{"):
+                choices = line.strip().strip("{}").split(",")
+                choices_str = f"\n{indent}".join(choices)
+                line = f"{indent}{choices_str}\n"
+            output += line
+        return output
+
+
 def register_custom_action(
     cls_names: Union[str, Tuple[str, ...]],
     mandatory: Tuple[str, ...] = (),
@@ -110,6 +127,7 @@ def _get_base_parser(add_help: bool = True) -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         add_help=add_help,
         description="GitLab API Command Line Interface",
+        formatter_class=VerticalHelpFormatter,
         allow_abbrev=False,
     )
     parser.add_argument("--version", help="Display the version.", action="store_true")
diff --git a/gitlab/v4/cli.py b/gitlab/v4/cli.py
@@ -377,7 +377,9 @@ def extend_parser(parser: argparse.ArgumentParser) -> argparse.ArgumentParser:
 
     for cls in sorted(classes, key=operator.attrgetter("__name__")):
         arg_name = cli.cls_to_gitlab_resource(cls)
-        object_group = subparsers.add_parser(arg_name)
+        object_group = subparsers.add_parser(
+            arg_name, formatter_class=cli.VerticalHelpFormatter
+        )
 
         object_subparsers = object_group.add_subparsers(
             title="action",
diff --git a/tests/functional/cli/test_cli.py b/tests/functional/cli/test_cli.py
@@ -34,6 +34,18 @@ def test_config_error_with_help_prints_help(script_runner):
     assert ret.returncode == 0
 
 
+def test_global_help_prints_resources_vertically(script_runner):
+    ret = script_runner.run("gitlab", "--help")
+    assert """resource:\n  application\n  application-appearance\n""" in ret.stdout
+    assert ret.returncode == 0
+
+
+def test_resource_help_prints_actions_vertically(script_runner):
+    ret = script_runner.run("gitlab", "project", "--help")
+    assert """action:\n  list\n  get""" in ret.stdout
+    assert ret.returncode == 0
+
+
 @pytest.mark.script_launch_mode("inprocess")
 @responses.activate
 def test_defaults_to_gitlab_com(script_runner, resp_get_project, monkeypatch):
