It seems that the py.typed file is not getting distributed, so mypy is not recognizing installed rich-click as being typed. I think you need to explicitly add it to package_data (options.package_data in setup.cfg).

Hi @ewels, rich-click is an awesome package and I love that it's a drop-in replacement for click. However, I'm running into a small issue with rewrapping. click uses the \b flag to prevent rewrapping for a paragraph, which allows you to preserve newlines in a command's help. rich-click doesn't seem to support that flag and removes newlines.

Say you have a command foo:

@click.command()
def foo():
    """This is a command.

    \b
    Examples
        $ foo
        $ foo bar
    """
    return

Here's the output of foo --help using just click:

With rich-click, the newlines are lost.

Using Markdown instead might be an alternative, but would require rewriting docstrings and would break compatibility with click. Any chance of support being added for \b in rich-click?

Thanks!

Added the following tools to pre-commit:

• iSort (import formatter)
• Black (general formatter)
• Flake8 (style checker)
• Mypy (type checker)

Furthermore, modified the README.md to contain new instructions.

Two more things are left to do:

• [x] Run pre-commit on the entire codebase.
• [ ] Add item to changelog.

This looks great! Thank you for sharing this.

I tried using the import in a Typer project and (unsurprisingly) it didn't work. Even if there's no official code support for using this with Typer, some docs would be super helpful since I would love to use it for my CLI.

Nested commands are not formatted at all. Because I couldn't get my script to work correctly I tried the simple example script. I get:

$ python rich_click_ex1.py

 Usage: rich_click_ex1.py [OPTIONS] COMMAND [ARGS]...

 My amazing tool does all the things.
 This is a minimal example based on documentation from the 'click' package.
 You can try using --help at the top level and also for specific group
 subcommands.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --debug/--no-debug  -d/-n    Enable debug mode. Newlines are removed by      │
│                              default.                                        │
│                              Double newlines are preserved.                  │
│ --help                       Show this message and exit.                     │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ download  Optionally use short-help for the group help text                  │
│ sync      Synchronise all your files between two places. Example command     │
│           that doesn't do much except print to the terminal.                 │
╰──────────────────────────────────────────────────────────────────────────────╯

This works as advertised. However:

$ python rich_click_ex1.py sync --help
Debug mode is off
Usage: rich_click_ex1.py sync [OPTIONS]

  Synchronise all your files between two places. Example command that
  doesn't do much except print to the terminal.

Options:
  --type TEXT  Type of file to sync  [default: files; required]
  --all
  --help       Show this message and exit.

This does not work as advertised. Am I missing something? Should the example script be updated or is this a bug?

This one might be niche, not that useful, and (maybe) annoying to implement. I decided to post it here anyway.

I noticed that when I have several commands, the help dialogue looks very busy and difficult to read:

╭─ Modules ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│  download-database          Download the latest version of Genomad's database and save it in the DESTINATION         │
│                             directory.                                                                               │
│  annotate                   Predict the genes in the INPUT file (FASTA format), annotate them using Genomad's        │
│                             markers (located in the DATABASE directory), and write the results to the OUTPUT         │
│                             directory.                                                                               │
│  find-proviruses            Find integrated viruses within the sequences in INPUT file using the Genomad markers     │
│                             (located in the DATABASE directory) and write the results to the OUTPUT directory. This  │
│                             command depends on the data generated by the annotate module.                            │
│  marker-classification      Classify the sequences in the INPUT file (FASTA format) based on the presence of         │
│                             Genomad markers (located in the DATABASE directory) and write the results to the OUTPUT  │
│                             directory. This command depends on the data generated by the annotate module.            │
│  nn-classification          Classify the sequences in the INPUT file (FASTA format) using the Genomad neural         │
│                             network and write the results to the OUTPUT directory.                                   │
│  aggregated-classification  Aggregate the results of the marker-classification and nn-classification modules to      │
│                             classify the sequences in the INPUT file (FASTA format) and write the results to the     │
│                             OUTPUT directory.                                                                        │
│  score-calibration          Performs score calibration of the sequences in the INPUT file (FASTA format) using the   │
│                             batch correction method and write the results to the OUTPUT directory. This module       │
│                             requires that at least one of the classification modules was classified previously       │
│                             (marker-classification, nn-classification, aggregated-classification).                   │
│  summary                    Generates a classification report file for the sequences in the INPUT file (FASTA        │
│                             format) and write it to the OUTPUT directory.                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

If I add an additional line to separate the commands, the dialogue looks much better.

╭─ Modules ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│  download-database          Download the latest version of Genomad's database and save it in the DESTINATION         │
│                             directory.                                                                               │
│                                                                                                                      │
│  annotate                   Predict the genes in the INPUT file (FASTA format), annotate them using Genomad's        │
│                             markers (located in the DATABASE directory), and write the results to the OUTPUT         │
│                             directory.                                                                               │
│                                                                                                                      │
│  find-proviruses            Find integrated viruses within the sequences in INPUT file using the Genomad markers     │
│                             (located in the DATABASE directory) and write the results to the OUTPUT directory. This  │
│                             command depends on the data generated by the annotate module.                            │
│                                                                                                                      │
│  marker-classification      Classify the sequences in the INPUT file (FASTA format) based on the presence of         │
│                             Genomad markers (located in the DATABASE directory) and write the results to the OUTPUT  │
│                             directory. This command depends on the data generated by the annotate module.            │
│                                                                                                                      │
│  nn-classification          Classify the sequences in the INPUT file (FASTA format) using the Genomad neural         │
│                             network and write the results to the OUTPUT directory.                                   │
│                                                                                                                      │
│  aggregated-classification  Aggregate the results of the marker-classification and nn-classification modules to      │
│                             classify the sequences in the INPUT file (FASTA format) and write the results to the     │
│                             OUTPUT directory.                                                                        │
│                                                                                                                      │
│  score-calibration          Performs score calibration of the sequences in the INPUT file (FASTA format) using the   │
│                             batch correction method and write the results to the OUTPUT directory. This module       │
│                             requires that at least one of the classification modules was classified previously       │
│                             (marker-classification, nn-classification, aggregated-classification).                   │
│                                                                                                                      │
│  summary                    Generates a classification report file for the sequences in the INPUT file (FASTA        │
│                             format) and write it to the OUTPUT directory.                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

I apologize in advance for how obscure this bug is.

I'll start by taking the simple Typer demo and modifying it to have download return a string:

import rich_click.typer as typer

app = typer.Typer()

@app.command()
def sync(
    type: str = typer.Option("files", help="Type of file to sync"),
    all: bool = typer.Option(False, help="Sync all the things?"),
):
    print("Syncing")


@app.command()
def download(all: bool = typer.Option(False, help="Get everything")):
    return "Shouldn't appear" # <-- RETURNS A STRING NOW


if __name__ == "__main__":
    app()

When run directly, everything is normal:

$ python vdsearch/test.py download
$

Now let's pip install -e . with testy mapped to test:app

$ testy download
Shouldn't appear
$

I've gotten around this bug by defining wrapper functions for my functions but it would be nice to get to the bottom of what's going on.

rich_click is not cleaning indentations if click version is ≥ 8.10. The cause is probably this change in the backend.

This code:

def cli():
    """
    Foo: bar

    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
    tempor incididunt ut labore et dolore magna aliqua. Pellentesque habitant
    morbi tristique senectus. Leo a diam sollicitudin tempor.
    """

Is generating this:

 Foo: bar
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod     tempor incididunt ut
 labore et dolore magna aliqua. Pellentesque habitant     morbi tristique senectus. Leo a diam
 sollicitudin tempor.

Instead of this:

 Foo: bar
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore
 et dolore magna aliqua. Pellentesque habitant morbi tristique senectus. Leo a diam sollicitudin
 tempor.

Not sure if this is an issue with my own VSCode setup, but for some reason, I am not getting proper autocompletions for rich_click on lines after the import. As I type the import I do get the expected completions, but after that, when using the imported module, they don't show up.

Because the completion for rich_click.r did not show rich_click, I was confused for a moment.

First of a couple refactorings that are coming up. This refactoring:

• Removes local imports. It's generally more preferred to use absolute imports.
• I moved the classes out of rich_click.py. This made the rich_click.py unnecessarily large..
• Moved the creation of the console into a function, as it's used all over the place.

I think to tune this file down more, we might consider moving all rich specific tools to a file called rich_utils and moving the click items into click_utils.

Hi @ewels, I came across another discrepancy between click and rich-click that's giving me a little trouble: how command short help is handled.

click generates short help from the first sentence of the command's help unless short_help is explicitly passed to the command, in which case that will be used. rich-click seems to use the first paragraph instead, and you can't overwrite it using short_help.

Here's a minimum reproducible example using rich-click==1.2.0.

@click.group()
def foo():
    """
    Help for group.
    """
    pass

@foo.command()
def command():
    """
    Help for command. This sentence shouldn't be included in the short help.
    """
    pass

@foo.command(short_help="This won't be used by rich-click")
def command2():
    """
    This should be overwritten by the explicitly passed short-help.
    """
    pass

Output of foo --help using click:

And using rich-click:

Thanks again for making rich-click!

This is a large PR, and for that I apologize. I'm happy to make changes and provide additional explanation based on feedback.

The main focus of this PR is to add support for isolating Rich Click's formatting and help configuration. The design supports isolation of these components by:

1. Extending Click's HelpFormatter class
2. Creating a HelpConfiguration class that doubles the current module-level settings
3. Adding a decorator that allows the HelpConfiguration to be passed into Click via the supported context_settings argument provided by the Command and Group classes.

Since this package does have an established user base I attempted to maintain the module-level settings behavior to prevent any breaking changes. I also added some tests to help verify the test suite using pytest and pytest-cov for test coverage. The tests are the bulk of this change as I used a snapshot-based approach to capture the input and output of the examples, and then validate their compatibility between module-level and context-level configuration.

I got it a bit carried away and added a few other nuggets since they seemed closely related.

1. The Rich Console object can also be configured per command and is distinct from the Console instance used internally by the formatter. The RichHelpFormatter creates a console based on the RichHelpConfiguration as the tight coupling between the Formatter and Click's internals make it difficult to allow the Console to be configured externally (i.e. one example is that Click expects help formatting to be buffered).
2. RichContext class was created to allow creation of the custom formatter.
3. The Rich Command, Group, and Context now expose the Console and RichHelpConfiguration properties. I thought this might make sense, but happy to remove if it might cause problems elsewhere.
4. Added contributor vscode settings

rich_click override's click's default (and correct) behavior of writing exceptions (e.g., raise click.ClickException('There's a problem!')) to stderr. This has implications for CI/CD, for example, where a rich_click application may raise an exception but because it's being output to stdout, the task still passes.

Right now all of the functions in the rich_click module are difficult to override and extend behavior unless you extend one of the RichCommand or RichGroup classes. And even then, you can't really get access the the internals since the formatter is not being used and the results of rich_format_help are not returned to the caller.

It would be nice if the Rich Console and rich_click configuration state could be configured/extended through class inheritance.

This leads to two implementation changes.

• One, move this behavior into a class with the configuration state encapsulated in the class.
• Two, create extensible methods that allow one to change the Console configuration and/or results of certain formatting functions.

For the first item, I think it might be possible to provide a class implementation of the formatter that could contain the state, and then expose a new method on the Context object that would allow you to configure the formatter before making the call to rich_format_help. For the most part, the module state is not a big problem since help generation is fired only once before application termination. However, one issue I've found is that letting the configuration sit in module state makes testing help messages difficult, since state changes leak across tests. I think it's also generally good practice to isolate state, and will make this library more reusable across the Click ecosystem.

I think the changes for one would solve most of the issues with two. If you implement the formatter interface, others could hook into that functionality, and it could be configured along with whatever method or attribute you expose on the Context.

In Click, get_help calls the format_help method with a formatter that is expected to hold a buffer of the text that should be returned from the method as a string. Since rich_click does not write the terminal output to the buffer, but directly to the console, it breaks callers of get_help that expect to receive the console output.

def get_help(self, ctx: Context) -> str:
    """Formats the help into a string and returns it.

    Calls :meth:`format_help` internally.
    """
    formatter = ctx.make_formatter()
    self.format_help(ctx, formatter)
    return formatter.getvalue().rstrip("\n")

This may not be a problem for rich_click to solve, as I'm not sure the formatter interface would support all of the capabilities of Rich. But, it would be great if the API of Click could be maintained.

Is this a problem that can be fixed by the following:

1. Pass a string buffer to Rich Console that writes help output.
2. Create a stub formatter implementing the getvalue method that returns the string buffer, or, override the get_help method to call format_help without the formatter and return the string buffer directly from Rich.

Rich Reference:

• https://rich.readthedocs.io/en/stable/console.html#capturing-output

When building a cli with a required argument, when the command is specified without the required argument, rich-click prints the error as expected. But there is an exception to this, which is when the user tries to run the command with --help.

In this case, the user is aware that an argument is required, but wants to get the full help, but because the required argument is not passed, the required argument error shows instead of the help message.

I submit that using --help is a valid case where the required argument error should not override the following behaviour, which is the printing of the help string.

To be fair, the same issue occurs in click as well, but there is a workaround for that in click which is to override the UsageError show method as shown in the SO link: https://stackoverflow.com/questions/39596070/python-click-custom-error-message

How do I do something similar with rich-click?