[Feature request] Themes

[dwreeves]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the documentation, with the integrated search.
• I already searched in Google "How to X" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.

Example Code

...

Description

Background

Hello! I co-maintain rich-click. https://github.com/ewels/rich-click This is Phil Ewel's project that I help keep up-to-date for him.

Typer vendored rich-click in I believe version 1.6. Since then we've added some nifty features, a lot of them are to make the internals more sane but the big user-facing feature that is really neat is themes. https://ewels.github.io/rich-click/latest/documentation/themes/ Because themes are so neat, we've also added patching to Typer, which works for versions of Typer <0.26. Of course, the vendoring of Click breaks that. https://ewels.github.io/rich-click/latest/documentation/typer_support/

The vendoring of Click makes perfect sense; Click continues to introduce a lot of tiny changes in minor version releases that break libraries trying to do complicated things. We also experience this ourselves, and so the vendoring is 100% understandable.

I also do not think Typer should care at all that our patching for typer >=0.26 no longer works. The number of people patching typer with rich-click is incredibly miniscule, so much so that it's been 2 days and nobody has raised an issue about it yet. Basically, we are 100% safe to ignore from Typer's perspective. We'll live with the pain of doing something slightly inadvisable.

Themes in Typer?

Instead what I am here to propose is that Typer might benefit a ton from having its own theming system, and I do believe rich-click's theming is a decent albeit imperfect starting point for how to think about CLI themes and what can be done with it. With the severing of the hard dependency on Click, this might be a good time to think about it?

Example of what themes look like in rich-click:

import rich_click as click
from rich_click import rich_config

@click.command()
@rich_config(help_config={"theme": "nord-nu"})
def cli():
    """Help text here."""

The benefit here is that the user gets access to a large swath of style changes in just a single line of code, and the style change is pre-configured to look pretty nice so the user doesn't need to fiddle too much to get something that looks good.

This would have some benefit to me because I could feel super comfortable removing Typer patching for good. It might even make rich-click truly legacy software, which would make my life easier, haha. I also think it would have a ton of benefit for Typer's users because Typer CLIs can be very same-y looking; also, Typer's vendoring of an old rich-click comes with it the problems that we wanted to address with themes in the first place with rich-click 1.9: mainly, that users largely avoid the color and style customization features because they are too impenetrable, and there is no high level, easy interface for customization in just a couple lines.

There are things I dislike about how we've implemented themes. And by we I mean me, since the majority of work was me, so I take full blame. I wouldn't suggest Typer copy our homework because our homework gets a B, maybe a B+ if you're feeling generous. Some of these things I dislike are fundamental limitations of rich-click's old designs which we are beholden to for backward compatibility, such as how the config for styling is "flat" instead of being nested (e.g. STYLE_OPTIONS_PANEL_TITLE_STYLE instead of options_panel.title.style). Some of these things I dislike were totally avoidable and I take all the blame, like how we do not have the concept of primary or secondary colors that can be mixed and matched, and how some of the themes are nonsense made-up names (e.g. quartz) instead of established color palettes like nord or dracula.

That said, there are a lot of neat ideas we've implemented, and the high level objective makes sense for us and could also make sense for Typer. For example: I like the idea of having different "formats" for CLIs, I like the idea of separating formats from color palettes so that they can be mixed-and-matched, and I like the idea of treating Parameter rendering as a method of the Parameter class which returns a "row" where the exact columns and their ordering is configurable via the Panel itself.

Examples

With a single line specifying the nord color palette, a user can get a CLI which looks like this:

Similarly with a single line, you can configure the formatting of the CLI help text itself. Here's one such example we call the nu format (also with the nord color palette):

Note the traditional "box" formatting uses the same code path as "nu". It's just applying different things at the same time. No hacks per se, just a lot of abstraction and plumbing to support everything at the same time.

Here's one more example for good measure: the cargo-slim theme, which combines the cargo color palette with the slim format. Here, note how the column ordering is slightly different (the shorthand options are in the front rather than in the middle); this is the column ordering I was referring to in action. Also note how across all 3 of the formats I've shown, the order and look of items within the help text is also different (e.g. [brackets] instead of (parentheses), [env: FOO=] vs.(Env: FOO), etc.). The "slim" theme is meant to mimic the look and feel of more traditional CLI help text, but of course it comes with the pretty colors for good measure.

If you'd like to play with themes, you can do something like this:

uvx --with rich-click --with "typer<0.26" --with "click<8.4" rich-click --theme cargo-slim [typer_cli_here.py] --help

Conclusion

So ultimately, themes in rich-click have been a mix of great decisions and meh decisions at the actual implementation level, but overall the feature has drawn a lot of excitement from users, and I think there is a place for Typer to take inspiration both at a high-level and a lower-level.

If the maintainers of Typer are interested in implementing themes, let me know if I can be of any help! I'd love to be of any assistance if this is of interest to Typer, and I'd love to further deprecate the software I maintain. 😆

Operating System

macOS

Operating System Details

No response

Project Version

0.26

Python Version

No response

Additional Context

No response

[dwreeves]

One more thing--

It would be interesting to understand what the goals are with vendoring Click. Are you looking to mostly keep Click as-is, and just build on top of that? Or are you looking to modify the Click integration itself over time and slowly morph it into something more appropriate for Typer?

As noted in the OP, one big thing that rich-click has really done since rich-click was vendored into Typer was to really align rich-click's internals with click's, to the extent that is reasonably possible. Even without themes, some of our work on the internals could be interesting for Typer.

For example, Typer still does what rich-click 1.6 did:

    def format_help(self, ctx: _click.Context, formatter: _click.HelpFormatter) -> None:
        if not HAS_RICH or self.rich_markup_mode is None:
            return super().format_help(ctx, formatter)
        from . import rich_utils

        return rich_utils.rich_format_help(
            obj=self,
            ctx=ctx,
            markup_mode=self.rich_markup_mode,
        )

Some notes on this and how/why we've changed this approach since 1.6:

• In Typer, just format_help is used, leaving the other methods in-tact. In practice, format_help() calls multiple methods: format_usage, format_help_text, format_options, format_epilog. All of these are interwoven into later version of rich-click. This is an extremely tiny detail since I doubt 99% of users care to override these methods in a very composable fashion, but it does show how some things in Click are either superfluous in Typer, or that the abstraction is not aligned (depending on your perspective and objectives).
• This writes directly to stdout via console.write(). In rich-click, we utilize a subclass of click.HelpFormatter, and write to a buffer, which means that in rich-click:
  • Writes are atomic (all or nothing). In rare cases, usually when the user is doing something weird, help text rendering can fail halfway through; this prevents writes to stdout in those situations.
  • Help text rendering and printing are decoupled. This supports a few advanced use cases, one of which is rendering to HTML and SVG (we've also had at least one user who wanted this for other purposes). E.g. rich-click --output html flask --help renders the Flask CLI as HTML, which is done via calling RichHelpFormatter().console.export_html().
  • Rendering is more generally aligned with how Click does rendering. Click does click.echo(ctx.get_help()) to render help text; in Typer and old versions of rich-click, this call still happens but just renders a \n and that's it. In rich-click 1.9, we do print(ctx.get_help()) and this does the actual rendering, rather than being a vestige of Click's assumptions (Also, we do print over click.echo because click.echo has some odd edge cases when it comes to rich help rendering; also click.echo is to my understanding legacy code from the really early Python 3 days, although I could be wrong about that).
• In Typer, help text rendering options are globals, not scoped to the CLI itself. In niche situations where CLIs are being threaded together, where multiple CLIs are fighting over the globals, this can cause unpredictable resolution order of the settings.

Both whether you'd even want to solve for these challenges, and if so how you'd want to solve for these problems, depend on what the objectives of the vendoring are other than dealing with Click's changes. Lastly, of course, whether you want any help solving these challenges and what that help looks like also depends on the objectives. For better or worse, rich-click is still strongly coupled to Click, so our solutions to these problems involve working within the constraints of Click the best we can: we just subclass everything and overwrite the corresponding methods. This could certainly work for Typer. But there's a question of whether Typer implements these as _click subclasses, or directly modifies the _click classes themselves to support these things.

Anyway, lots of rambling here. Just let me know if anything here is of interest, if you'd want any help, and if so what that help looks like. 🙂 I also understand if you're not interested in doing anything too dramatic!

[svlandeg]

Hi!

Thanks for reaching out. I can't speak for Tiangolo, who ultimately decides which features we'll have and maintain in Typer. But I do like the idea of themes in Typer, so it's something that we may discuss internally. Thanks for sharing some feedback on design decisions (the good and the bad), that's always useful.

With respect to the vendoring, the main goal was really to be able to have a more independent code base that will allow us to implement novel features more easily. In the coming months, we'll be making some decions with respect to "legacy" Click functionality. Things we'll want to keep, we'll want to document more clearly in the Typer docs & public API, and we'll reimplement such functionality properly within Typer's own code base. Things we won't want to maintain will probably be removed from the vendored code base.

[dwreeves]

Thanks so much for the response!

That makes perfect sense. So over time the vendored Click will be changing quite a bit, rather than it just being a snapshot-in-time of Click. That helps me know what I should be doing for Typer support in rich-click (basically: dropping it, as hooking into the internals will likely change across each minor release).

If there's anything you want help with, no matter how boring or unglamorous, let me know.