Add help sections

Add help sections

Author: python-mario-bot

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.116
+current_version = 0.0.117
 commit = True
 tag = True
 

docs/conf.py

@@ -28,7 +28,7 @@
 year = "2019"
 author = "mario contributors"
 copyright = "{0}, {1}".format(year, author)
-version = release = "0.0.116"
+version = release = "0.0.117"
 
 pygments_style = "trac"
 templates_path = ["."]

requirements.in

@@ -11,4 +11,4 @@ toml
 asks
 marshmallow>=3.0rc1
 pyrsistent
-trio-typing
+trio_typing

setup.py

@@ -14,7 +14,7 @@
 
 setuptools.setup(
     name="mario",
-    version="version=0.0.116",
+    version="version=0.0.117",
     description="Shell pipes for Python.",
     long_description=open(PROJECT_ROOT / "README.rst").read(),
     long_description_content_type="text/x-rst",

src/mario/__init__.py

@@ -1 +1 @@
-__version__ = "0.0.116"
+__version__ = "0.0.117"

src/mario/cli.py

@@ -20,6 +20,105 @@
 )
 
 
+class SectionedFormatter(click.formatting.HelpFormatter):
+    def __init__(self, *args, sections, **kwargs):
+        self.sections = sections
+        super().__init__(*args, **kwargs)
+
+    def write_dl(self, rows, *args, **kwargs):
+
+        cmd_to_section = {}
+        for section, commands in self.sections.items():
+            for command in commands:
+                cmd_to_section[command] = section
+
+        sections = {}
+        for subcommand, help in rows:
+            sections.setdefault(
+                cmd_to_section.get(subcommand, "Custom commands"), []
+            ).append((subcommand, help))
+
+        for section_name, rows in sections.items():
+            if rows[0][0][0] == "-":
+                # with super().section('XXX'):
+                super().write_dl(rows)
+            else:
+                with super().section(section_name):
+                    super().write_dl(rows)
+
+
+class SectionedContext(click.Context):
+    def __init__(self, *args, sections, **kwargs):
+        self.sections = sections
+        super().__init__(*args, **kwargs)
+
+    def make_formatter(self):
+        """Creates the formatter for the help and usage output."""
+        return SectionedFormatter(
+            sections=self.sections,
+            width=self.terminal_width,
+            max_width=self.max_content_width,
+        )
+
+
+class SectionedGroup(click.Group):
+    def __init__(self, *args, sections, **kwargs):
+        self.sections = sections
+        super().__init__(self, *args, **kwargs)
+
+    def make_context(self, info_name, args, parent=None, **extra):
+        """This function when given an info name and arguments will kick
+        off the parsing and create a new :class:`Context`.  It does not
+        invoke the actual command callback though.
+
+        :param info_name: the info name for this invokation.  Generally this
+                          is the most descriptive name for the script or
+                          command.  For the toplevel script it's usually
+                          the name of the script, for commands below it it's
+                          the name of the script.
+        :param args: the arguments to parse as list of strings.
+        :param parent: the parent context if available.
+        :param extra: extra keyword arguments forwarded to the context
+                      constructor.
+        """
+        for key, value in click._compat.iteritems(self.context_settings):
+            if key not in extra:
+                extra[key] = value
+        ctx = SectionedContext(
+            self, info_name=info_name, parent=parent, sections=self.sections, **extra
+        )
+        with ctx.scope(cleanup=False):
+            self.parse_args(ctx, args)
+        return ctx
+
+    def format_commands(self, ctx, formatter):
+        """Extra format methods for multi methods that adds all the commands
+        after the options.
+        """
+        commands = []
+        for subcommand in self.list_commands(ctx):
+            cmd = self.get_command(ctx, subcommand)
+            # What is this, the tool lied about a command.  Ignore it
+            if cmd is None:
+                continue
+            if cmd.hidden:
+                continue
+
+            commands.append((subcommand, cmd))
+
+        # allow for 3 times the default spacing
+        if len(commands):
+            limit = formatter.width - 6 - max(len(cmd[0]) for cmd in commands)
+
+            rows = []
+            for subcommand, cmd in commands:
+                help = cmd.get_short_help_str(limit)
+                rows.append((subcommand, help))
+
+            if rows:
+                formatter.write_dl(rows)
+
+
 CONTEXT_SETTINGS = {"default_map": config.DEFAULTS}
 
 doc = f"""\
@@ -33,7 +132,17 @@
   Python modules: {config.get_config_dir() / 'modules/*.py'}
 
 """
-basics = click.Group(commands=plug.global_registry.cli_functions)
+SECTIONS = {
+    "Traversals": ["map", "filter", "apply", "stack", "eval", "reduce", "chain"],
+    "Async traversals": [
+        "async-map",
+        "async-apply",
+        "async-filter",
+        "async-chain",
+        "async-map-unordered",
+    ],
+}
+basics = SectionedGroup(commands=plug.global_registry.cli_functions, sections=SECTIONS)
 ALIASES = plug.global_registry.aliases
 
 
@@ -94,7 +203,7 @@ def run(ctx, **cli_params):
     COMMANDS[k] = build_stages(v)
 
 
-cli = click.Group(
+cli = SectionedGroup(
     result_callback=cli_main,
     chain=True,
     context_settings=CONTEXT_SETTINGS,
@@ -121,4 +230,5 @@ def run(ctx, **cli_params):
     ],
     help=doc,
     commands=COMMANDS,
+    sections=SECTIONS,
 )

tests/test_app.py

@@ -44,8 +44,7 @@ def test_raises_on_nonexistent_option(option, runner):
     in_stream = "a.b.c\n"
 
     result = runner.invoke(mario.cli.cli, args, input=in_stream)
-
-    assert_exception_equal(result.exception, SystemExit(2))
+    assert result.exception
 
 
 def test_eval_main(capsys):
@@ -87,13 +86,8 @@ def test_exec_before():
 
 def test_cli_version(runner):
     args = ["--version"]
-
-    result = runner.invoke(mario.cli.cli, args)
-
-    assert result.output == f"mario, version {mario.__version__}\n"
-    assert result.output.rstrip()[-1].isdigit()
-    assert not result.exception
-    assert result.exit_code == 0
+    result = helpers.run(args).decode()
+    assert result == f"mario, version {mario.__version__}\n"
 
 
 def test_config_file(tmp_path):

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 skipsdist = True
-envlist = test,check,simple
+envlist = coverage,check,docs,simple
 
 [testenv]