feat(cli): add a custom help formatter

weakcamel · nejch · commit 3b3bcce4d995 · 2022-07-26T23:23:27.000+02: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.
diff --git a/gitlab/_formatter.py b/gitlab/_formatter.py
@@ -0,0 +1,137 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Derived from Python argparse standard module with necessary modifications.
+#
+# Original author of argparse: Steven J. Bethard <steven.bethard@gmail.com>.
+# New maintainer of argparse as of 29 August 2019:  Raymond Hettinger <raymond.hettinger@gmail.com>
+#
+# pylint: skip-file
+# type: ignore
+
+import argparse
+import re as _re
+from gettext import gettext as _
+
+
+class VerticalHelpFormatter(argparse.HelpFormatter):
+    def _metavar_formatter(self, action, default_metavar):
+        if action.metavar is not None:
+            result = action.metavar
+        elif action.choices is not None:
+            choice_strs = [str(choice) for choice in action.choices]
+            indentation = self._indent_increment * " "
+            sep = "\n" + (indentation * 2)
+            result = sep + sep.join(choice_strs)
+        else:
+            result = default_metavar
+
+        def format(tuple_size):
+            if isinstance(result, tuple):
+                return result
+            else:
+                return (result,) * tuple_size
+
+        return format
+
+    # This method was copied almost as-is from parent class,
+    # the only change required was disabling some validation which doesn't make
+    # sense with multi-line choice lists
+    def _format_usage(self, usage, actions, groups, prefix):
+        if prefix is None:
+            prefix = _("usage: ")
+
+        # if usage is specified, use that
+        if usage is not None:
+            usage = usage % dict(prog=self._prog)
+
+        # if no optionals or positionals are available, usage is just prog
+        elif usage is None and not actions:
+            usage = "%(prog)s" % dict(prog=self._prog)
+
+        # if optionals and positionals are available, calculate usage
+        elif usage is None:
+            prog = "%(prog)s" % dict(prog=self._prog)
+
+            # split optionals from positionals
+            optionals = []
+            positionals = []
+            for action in actions:
+                if action.option_strings:
+                    optionals.append(action)
+                else:
+                    positionals.append(action)
+
+            # build full usage string
+            format = self._format_actions_usage
+            action_usage = format(optionals + positionals, groups)
+            usage = " ".join([s for s in [prog, action_usage] if s])
+
+            # wrap the usage parts if it's too long
+            text_width = self._width - self._current_indent
+            if len(prefix) + len(usage) > text_width:
+
+                # break usage into wrappable parts
+                # fmt: off
+                part_regexp = (
+                    r"\(.*?\)+(?=\s|$)|"
+                    r"\[.*?\]+(?=\s|$)|"
+                    r"\S+"
+                )
+                # fmt: on
+                opt_usage = format(optionals, groups)
+                pos_usage = format(positionals, groups)
+                opt_parts = _re.findall(part_regexp, opt_usage)
+                pos_parts = _re.findall(part_regexp, pos_usage)
+                # Disabled the validation due to possible multiline output
+                # assert ' '.join(opt_parts) == opt_usage
+                # assert ' '.join(pos_parts) == pos_usage
+
+                # helper for wrapping lines
+                def get_lines(parts, indent, prefix=None):
+                    lines = []
+                    line = []
+                    if prefix is not None:
+                        line_len = len(prefix) - 1
+                    else:
+                        line_len = len(indent) - 1
+                    for part in parts:
+                        if line_len + 1 + len(part) > text_width and line:
+                            lines.append(indent + " ".join(line))
+                            line = []
+                            line_len = len(indent) - 1
+                        line.append(part)
+                        line_len += len(part) + 1
+                    if line:
+                        lines.append(indent + " ".join(line))
+                    if prefix is not None:
+                        lines[0] = lines[0][len(indent) :]
+                    return lines
+
+                # if prog is short, follow it with optionals or positionals
+                if len(prefix) + len(prog) <= 0.75 * text_width:
+                    indent = " " * (len(prefix) + len(prog) + 1)
+                    if opt_parts:
+                        lines = get_lines([prog] + opt_parts, indent, prefix)
+                        lines.extend(get_lines(pos_parts, indent))
+                    elif pos_parts:
+                        lines = get_lines([prog] + pos_parts, indent, prefix)
+                    else:
+                        lines = [prog]
+
+                # if prog is long, put it on its own line
+                else:
+                    indent = " " * len(prefix)
+                    parts = opt_parts + pos_parts
+                    lines = get_lines(parts, indent)
+                    if len(lines) > 1:
+                        lines = []
+                        lines.extend(get_lines(opt_parts, indent))
+                        lines.extend(get_lines(pos_parts, indent))
+                    lines = [prog] + lines
+
+                # join lines into usage
+                usage = "\n".join(lines)
+
+        # prefix with 'usage:'
+        return "%s%s\n\n" % (prefix, usage)
diff --git a/gitlab/cli.py b/gitlab/cli.py
@@ -27,6 +27,7 @@
 
 from requests.structures import CaseInsensitiveDict
 
+import gitlab._formatter
 import gitlab.config
 from gitlab.base import RESTObject
 
@@ -110,6 +111,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=gitlab._formatter.VerticalHelpFormatter,  # type: ignore
         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,10 @@ 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=gitlab._formatter.VerticalHelpFormatter,  # type: ignore
+        )
 
         object_subparsers = object_group.add_subparsers(
             title="action",
