Feature: theming support for list of subcommand aliases (#152)

* Feature: style list of subcommand aliases

* Dark theme: set default styles for `alias` and `alias_secondary`

cloup/_commands.py

@@ -24,8 +24,8 @@
 """
 import inspect
 from typing import (
-    Any, Callable, Dict, Iterable, List, NamedTuple, Optional, Tuple, Type,
-    TypeVar, Union, cast, overload,
+    Any, Callable, Dict, Iterable, List, NamedTuple, Optional, Sequence, Tuple,
+    Type, TypeVar, Union, cast, overload,
 )
 
 import click
@@ -36,6 +36,7 @@
 from ._sections import Section, SectionMixin
 from ._util import click_version_ge_8_1, first_bool, reindent
 from .constraints import ConstraintMixin
+from .styling import DEFAULT_THEME
 from .typing import AnyCallable
 
 ClickCommand = TypeVar('ClickCommand', bound=click.Command)
@@ -227,10 +228,26 @@ def format_subcommand_name(
     ) -> str:
         aliases = getattr(cmd, 'aliases', None)
         if aliases and self.must_show_subcommand_aliases(ctx):
-            alias_list = ', '.join(aliases)
-            return f"{name} ({alias_list})"
+            assert isinstance(ctx, cloup.Context)
+            theme = cast(
+                cloup.HelpTheme, ctx.formatter_settings.get("theme", DEFAULT_THEME)
+            )
+            alias_list = self.format_subcommand_aliases(aliases, theme)
+            return f"{name} {alias_list}"
         return name
 
+    @staticmethod
+    def format_subcommand_aliases(aliases: Sequence[str], theme: cloup.HelpTheme) -> str:
+        secondary_style = theme.alias_secondary
+        if secondary_style is None or secondary_style == theme.alias:
+            return theme.alias(f"({', '.join(aliases)})")
+        else:
+            return (
+                secondary_style("(")
+                + secondary_style(", ").join(theme.alias(alias) for alias in aliases)
+                + secondary_style(")")
+            )
+
     # MyPy complains because "Signature of "group" incompatible with supertype".
     # The supertype signature is (*args, **kwargs), which is compatible with
     # this provided that you pass all arguments (expect "name") as keyword arg.

cloup/styling.py

@@ -8,6 +8,7 @@
 import click
 
 from cloup._util import FrozenSpace, click_version_tuple, delete_keys, identity
+from cloup.typing import MISSING, Possibly
 
 IStyle = Callable[[str], str]
 """A callable that takes a string and returns a styled version of it."""
@@ -39,6 +40,8 @@ class HelpTheme(NamedTuple):
         Style of the second column of a definition list (help text).
     :param epilog:
         Style of the epilog.
+    :param alias:
+        Style of subcommand aliases in a definition lists.
     """
 
     invoked_command: IStyle = identity
@@ -62,6 +65,13 @@ class HelpTheme(NamedTuple):
     col2: IStyle = identity
     """Style of the second column of a definition list (help text)."""
 
+    alias: IStyle = identity
+    """Style of subcommand aliases in a definition lists."""
+
+    alias_secondary: Optional[IStyle] = None
+    """Style of separator and eventual parenthesis/brackets in subcommand alias lists.
+    If not provided, the ``alias`` style will be used."""
+
     epilog: IStyle = identity
     """Style of the epilog."""
 
@@ -73,9 +83,13 @@ def with_(
         section_help: Optional[IStyle] = None,
         col1: Optional[IStyle] = None,
         col2: Optional[IStyle] = None,
+        alias: Optional[IStyle] = None,
+        alias_secondary: Possibly[Optional[IStyle]] = MISSING,
         epilog: Optional[IStyle] = None,
     ) -> 'HelpTheme':
         kwargs = {key: val for key, val in locals().items() if val is not None}
+        if alias_secondary is MISSING:
+            del kwargs["alias_secondary"]
         kwargs.pop('self')
         if kwargs:
             return self._replace(**kwargs)
@@ -89,6 +103,8 @@ def dark() -> "HelpTheme":
             heading=Style(fg='bright_white', bold=True),
             constraint=Style(fg='magenta'),
             col1=Style(fg='bright_yellow'),
+            alias=Style(fg='yellow'),
+            alias_secondary=Style(fg='white'),
         )
 
     @staticmethod
@@ -184,3 +200,6 @@ class Color(FrozenSpace):
     bright_magenta = "bright_magenta"
     bright_cyan = "bright_cyan"
     bright_white = "bright_white"
+
+
+DEFAULT_THEME = HelpTheme()

examples/manim/main.py

@@ -41,6 +41,8 @@
             # col1=Style(...),
             col2=Style(dim=True),
             epilog=Style(fg=Color.bright_white, italic=True),
+            alias=Style(fg=Color.yellow),
+            alias_secondary=Style(fg=Color.white),
         ),
     ),
 )

tests/test_aliases.py

@@ -1,9 +1,12 @@
+from typing import Optional
+
 import click
 import pytest
 
 import cloup
-from cloup import Group
-from cloup._util import first_bool, reindent
+from cloup import Color, Group, HelpTheme, Style
+from cloup._util import first_bool, identity, reindent
+from cloup.styling import IStyle
 from cloup.typing import MISSING
 
 
@@ -168,3 +171,28 @@ def test_cloup_subgroup_help(cli, runner):
           --help  Show this message and exit.
     """)
     assert res.output == expected
+
+
+def test_alias_are_correctly_styled(runner):
+    red = Style(fg=Color.red)
+    green = Style(fg=Color.green)
+
+    def fmt(alias: IStyle = identity, alias_secondary: Optional[IStyle] = None):
+        theme = HelpTheme(alias=alias, alias_secondary=alias_secondary)
+        return Group.format_subcommand_aliases(["i", "add"], theme)
+
+    # No styles (default theme)
+    assert fmt() == "(i, add)"
+
+    # Only theme.alias
+    assert fmt(alias=green) == f"{green('(i, add)')}"
+
+    # Only theme.alias_secondary
+    assert fmt(alias_secondary=green) == (
+        green("(") + "i" + green(", ") + "add" + green(")")
+    )
+
+    # Both
+    assert fmt(alias=red, alias_secondary=green) == (
+        green("(") + red("i") + green(", ") + red("add") + green(")")
+    )

tests/test_formatting.py

@@ -9,12 +9,12 @@
 import pytest
 
 from cloup import HelpFormatter
-from cloup.typing import Possibly
 from cloup.formatting import HelpSection, unstyled_len
 from cloup.formatting.sep import (
     Hline, RowSepIf, RowSepPolicy, multiline_rows_are_at_least
 )
 from cloup.styling import HelpTheme, Style
+from cloup.typing import Possibly
 from tests.util import parametrize
 
 LOREM = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor."