Inconsistent highlighting in help section

[km2023-4]

Dear authors, I recently started using rich-click and have to say it looks amazing.

While playing around with click's command help sections, though, I noticed some inconsistent colouring/highlighting:

It seems that the argument related regex in the OptionHighlighter class (rich_help_configuration.py) is not handling things consistenly. Removing the regex seems to be more pleasing on the eyes...

class OptionHighlighter(rich.highlighter.RegexHighlighter):
    """Highlights our special options."""

    highlights = [        
        r"(^|\W)(?P<switch>\-\w+)(?![a-zA-Z0-9])",
        r"(^|\W)(?P<option>\-\-[\w\-]+)(?![a-zA-Z0-9])",
        # r"(^|\W)(?P<argument>[A-Z0-9\_]+)(?![_a-zA-Z0-9])",        
        r"(?P<metavar>\<[^\>]+\>)",
        r"(?P<usage>Usage: )",
    ]

Do we really need to auto highlight words in capitals or numbers inside the help section?

[ewels]

Good spot! I think that this regex is intended to highlight positional arguments in the first Usage: line. This bit (^^):

$ python examples/06_arguments.py --help

 Usage: 06_arguments.py [OPTIONS] INPUT
                                  ^^^^^

Totally agree that it's not specific enough though, and it shouldn't be highlighting the random capital letters in the rest of the help text 👍🏻

[km2023-4]

The following does the job for me. Limits the highlighter to the "Usage" line:

class OptionHighlighter(rich.highlighter.RegexHighlighter):
    """Highlights our special options."""

    highlights = [
        r"(^|\W)(?P<switch>\-\w+)(?![a-zA-Z0-9])",
        r"(^|\W)(?P<option>\-\-[\w\-]+)(?![a-zA-Z0-9])",
        # r"(^|\W)(?P<argument>[A-Z0-9\_]+)(?![_a-zA-Z0-9])", # old
        r"(Usage:.*\])(?P<argument>[\s\w]+)", # new
        r"(Usage:.*\[)(?P<option>OPTIONS)\]", # new
        r"(?P<metavar>\<[^\>]+\>)",
        r"(?P<usage>Usage: )",
    ]

Full example to test would be (python <.py file> test-command --help):

import rich_click as click

click.rich_click.USE_RICH_MARKUP = True


@click.group()
def cli():
    pass


@cli.command()
@click.argument("a")
@click.argument("argument_2")
@click.option("--test-option0", "-t", is_flag=True, help="An option.")
@click.option(
    "--test-option1",
    "-o",
    is_flag=True,
    help="A second option with highlighted single capital 'A'?",
)
@click.option(
    "--test-option2",
    "-S",
    "-s",
    is_flag=True,
    help="Another option but with inconsistent highlighting of switch '-S','-s'.",
)
@click.option(
    "--test-option3",
    help="An option with weird looking highlighting: v2.0, d-A-ta, dataset0.5, v0.5-test-0.5, [blue]something-N-ot-SO-blue[/]",
)
def test_command(a, argument2, test_option0, test_option1, test_option2, test_option3):
    """
    A test command.
    """
    pass


if __name__ == "__main__":
    cli()

[ewels]

Nice, thanks! Unfortunately your example script actually flagged that it's not working with subcommands though 😅

Struggled to find a succinct regex that would match all three whilst being limited to that line. So followed your lead and added 3, one for each section. I actually went even more explicit, as if we're only targeting that first line I think that we can explicitly look for the words OPTIONS etc, rather than all uppercase words. Hopefully these are stable.

Tested locally and working as expected now.

[ewels]

I think that we can explicitly look for the words OPTIONS etc, rather than all uppercase words. Hopefully these are stable.

Nope, I was wrong. Too simplistic. Arguments are listed there by name, with and without square brackets (depending on whether they're required or not).

[ewels]

Updated example 6 to give a more varied usage string:

 Usage: 06_arguments.py [OPTIONS] INPUT OUTPUT {yaml|json} [FLAVOUR]

[ewels]

Ok, I think that got it.. 🤞🏻

[km2023-4]

Awesome! Thanks for dealing with this so quickly!

[km2023-4]

I noticed that the metavar highlighting can still play up a little when using '<' or '>' in the help section...

[ewels]

That doesn't really bother me so much, as wrapping things in < foo > is generally accepted notation for metavars. In contrast the option thing was much more generic; any capital letters (also I don't think it worked for required enumerated option args).

That being said, I'm not actually sure what that regex is meant to be highlighting..? I'm struggling to find any standard click output that uses <> now.. 🤔