From 679cfedb9cfcaab0dd6e33c6c004db554edff966 Mon Sep 17 00:00:00 2001 From: dwreeves Date: Mon, 29 Apr 2024 22:30:38 -0400 Subject: [PATCH 1/2] update --- CHANGELOG.md | 3 ++- docs/documentation/configuration.md | 2 +- docs/documentation/formatting_and_styles.md | 17 ++++++++++++---- docs/overrides/editor.html | 1 + src/rich_click/rich_click.py | 2 +- src/rich_click/rich_help_configuration.py | 2 +- src/rich_click/rich_help_rendering.py | 20 +++++++++++++------ ...ments with rich_config]-click8.config.json | 2 +- ...rrors with rich_config]-click8.config.json | 2 +- ...ative with rich_config]-click8.config.json | 2 +- ...ables with rich_config]-click8.config.json | 2 +- ...rting with rich_config]-click8.config.json | 2 +- ...kdown with rich_config]-click8.config.json | 2 +- ...fault with rich_config]-click8.config.json | 2 +- ...avars with rich_config]-click8.config.json | 2 +- ...arkup with rich_config]-click8.config.json | 2 +- ...imple with rich_config]-click8.config.json | 2 +- ...tyles with rich_config]-click8.config.json | 2 +- 18 files changed, 44 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1325c414..5af8c2dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,8 @@ - `RichHelpConfiguration()` is now asserted to be JSON serializable, as an option for porting configurations. That said, serialization is not a fully supported feature of the high-level API, so serialize the config at your own risk. - Related: `highlighter` is now deprecated in `RichHelpConfiguration`; please use `highlighter_patterns` instead. - Moved exclusively to `pyproject.toml` and removed `setup.py` / `setup.cfg`; thank you [@Stealthii](https://github.com/Stealthii)! -- Moved to `text_markup: Literal["markdown", "rich", None]` instead of booleans. +- Moved to `text_markup: Literal["markdown", "rich", "ansi", None]` instead of booleans. + - The default is now `ansi` instead of `None` to help support usage of `click.style()`. `None` is still supported. - Fixed issue where error messages would not print to `stderr` by default. - New configuration options: [[#178](https://github.com/ewels/rich-click/pull/178)] - `STYLE_OPTIONS_PANEL_BOX` diff --git a/docs/documentation/configuration.md b/docs/documentation/configuration.md index d8798796..bb038c89 100644 --- a/docs/documentation/configuration.md +++ b/docs/documentation/configuration.md @@ -197,7 +197,7 @@ SHOW_METAVARS_COLUMN = True # Show a column with the option metavar (eg. INTEGE APPEND_METAVARS_HELP = False # Append metavar (eg. [TEXT]) after the help text GROUP_ARGUMENTS_OPTIONS = False # Show arguments with options instead of in own panel OPTION_ENVVAR_FIRST = False # Show env vars before option help text instead of avert -TEXT_MARKUP = None # One of: "rich", "markdown", None. +TEXT_MARKUP = "ansi" # One of: "rich", "markdown", "ansi", None. USE_MARKDOWN_EMOJI = True # Parse emoji codes in markdown :smile: COMMAND_GROUPS = {} # Define sorted groups of panels to display subcommands OPTION_GROUPS = {} # Define sorted groups of panels to display options and arguments diff --git a/docs/documentation/formatting_and_styles.md b/docs/documentation/formatting_and_styles.md index 98abe882..d6882164 100644 --- a/docs/documentation/formatting_and_styles.md +++ b/docs/documentation/formatting_and_styles.md @@ -13,28 +13,37 @@ Note that most normal click options should still work, such as `show_default=Tru ### Text markup -**rich-click** supports 3 different values for `text_markup`, which determines how text is rendered: +**rich-click** supports 4 different values for `text_markup`, which determines how text is rendered: -- `None`: Rendered as plain text. This is the default. +- `'ansi'`: Rendered as plain text with ANSI escape codes handled. This is the default. - `'rich'`: Rendered using Rich's markup syntax. - `'markdown'`: Rendered with markdown. +- `None`: Rendered as plain text, ANSI escape codes are not handled. !!! warning Prior to **rich-click** 1.8.0, markup was controlled by the booleans `use_rich_markup` and `use_markdown`. These booleans have been silently deprecated (read: they will still be supported for the distant future), - and users are encouraged to use the `text_markup: Literal["markdown", "rich", None]` config option instead. + and users are encouraged to use the `text_markup` config option instead. Note that the previous behavior of `use_markdown` and `use_rich_markup` was that they are mutually exclusive, and that `use_markdown` takes precedence over `use_rich_markup`. +!!! note + Don't mix `click.style()` with `text_markup="rich"`! + If you want colors, bold, italic, and so on, then use [Rich markup](https://rich.readthedocs.io/en/stable/markup.html). + #### Rich markup -In order to be as widely compatible as possible with a simple import, **rich-click** does _not_ parse rich formatting markup (eg. `[red]`) by default. You need to opt-in to this behaviour. +In order to be as widely compatible as possible with a simple import, +**rich-click** does _not_ parse rich formatting markup (eg. `[red]`) by default. +You need to opt-in to this behaviour. Remember that you'll need to escape any regular square brackets using a back slash in your help texts, for example: `[dim]\[my-default: foo][\]` +For more information, read the Rich docs on [markup](https://rich.readthedocs.io/en/stable/markup.html) and [styles](https://rich.readthedocs.io/en/stable/style.html). + === "`RichHelpConfiguration()`" ```python help_config = click.RichHelpConfiguration(text_markup="rich") diff --git a/docs/overrides/editor.html b/docs/overrides/editor.html index f9afd722..e51a4cb0 100644 --- a/docs/overrides/editor.html +++ b/docs/overrides/editor.html @@ -128,6 +128,7 @@

Live Style Editor

The style options here are not exhaustive! There are many more ways to customize your rich-click outputs. +Modern terminals also support more than the 8 colors used on this page; see here for more information about terminal colors. The Live Style Editor seeks to represent a useful subset of the available styling options.

diff --git a/src/rich_click/rich_click.py b/src/rich_click/rich_click.py index d4940c73..f9fe147d 100644 --- a/src/rich_click/rich_click.py +++ b/src/rich_click/rich_click.py @@ -92,7 +92,7 @@ APPEND_METAVARS_HELP: bool = False # Append metavar (eg. [TEXT]) after the help text GROUP_ARGUMENTS_OPTIONS: bool = False # Show arguments with options instead of in own panel OPTION_ENVVAR_FIRST: bool = False # Show env vars before option help text instead of avert -TEXT_MARKUP: Literal["rich", "markdown", None] = None +TEXT_MARKUP: Literal["ansi", "rich", "markdown", None] = "ansi" USE_MARKDOWN: bool = False # Parse help strings as markdown USE_MARKDOWN_EMOJI: bool = True # Parse emoji codes in markdown :smile: USE_RICH_MARKUP: bool = False # Parse help strings for rich markup (eg. [red]my text[/]) diff --git a/src/rich_click/rich_help_configuration.py b/src/rich_click/rich_help_configuration.py index f22332c5..510cc116 100644 --- a/src/rich_click/rich_help_configuration.py +++ b/src/rich_click/rich_help_configuration.py @@ -144,7 +144,7 @@ class RichHelpConfiguration: """Show arguments with options instead of in own panel""" option_envvar_first: bool = field(default=False) """Show env vars before option help text instead of after""" - text_markup: Literal["rich", "markdown", None] = None + text_markup: Literal["ansi", "rich", "markdown", None] = "ansi" use_markdown: bool = field(default=False) """Silently deprecated; use `text_markup` field instead.""" use_markdown_emoji: bool = field(default=True) diff --git a/src/rich_click/rich_help_rendering.py b/src/rich_click/rich_help_rendering.py index 8ba8e8ec..aaf44c9c 100644 --- a/src/rich_click/rich_help_rendering.py +++ b/src/rich_click/rich_help_rendering.py @@ -63,15 +63,21 @@ def _make_rich_rext(text: str, style: StyleType, formatter: RichHelpFormatter) - config = formatter.config # Remove indentations from input text text = inspect.cleandoc(text) - if config.text_markup == "markdown": + + use_ansi = False + use_markdown = False + use_rich = False + + if config.use_markdown: + use_markdown = True + elif config.use_rich_markup: + use_rich = True + elif config.text_markup == "markdown": use_markdown = True - use_rich = False elif config.text_markup == "rich": - use_markdown = False use_rich = True - else: - use_markdown = config.use_markdown - use_rich = config.use_rich_markup + elif config.text_markup == "ansi": + use_ansi = True # TODO: # In a future major version release, decouple emojis and markdown. @@ -82,6 +88,8 @@ def _make_rich_rext(text: str, style: StyleType, formatter: RichHelpFormatter) - return Markdown(text, style=style) elif use_rich: return formatter.highlighter(Text.from_markup(text, style=style)) + elif use_ansi: + return formatter.highlighter(Text.from_ansi(text, style=style)) else: return formatter.highlighter(Text(text, style=style)) diff --git a/tests/expectations/test_rich_click[test arguments with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test arguments with rich_config]-click8.config.json index e9f16030..b23bf575 100644 --- a/tests/expectations/test_rich_click[test arguments with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test arguments with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": false, diff --git a/tests/expectations/test_rich_click[test custom errors with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test custom errors with rich_config]-click8.config.json index 29e88022..c1a212b4 100644 --- a/tests/expectations/test_rich_click[test custom errors with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test custom errors with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": false, diff --git a/tests/expectations/test_rich_click[test declarative with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test declarative with rich_config]-click8.config.json index 5ada03df..c3c8cb85 100644 --- a/tests/expectations/test_rich_click[test declarative with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test declarative with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": false, diff --git a/tests/expectations/test_rich_click[test environment variables with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test environment variables with rich_config]-click8.config.json index 5ada03df..c3c8cb85 100644 --- a/tests/expectations/test_rich_click[test environment variables with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test environment variables with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": false, diff --git a/tests/expectations/test_rich_click[test groups sorting with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test groups sorting with rich_config]-click8.config.json index 82daef64..03a86f7a 100644 --- a/tests/expectations/test_rich_click[test groups sorting with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test groups sorting with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": false, diff --git a/tests/expectations/test_rich_click[test markdown with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test markdown with rich_config]-click8.config.json index 70bfde9a..aa9c66fc 100644 --- a/tests/expectations/test_rich_click[test markdown with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test markdown with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": true, "use_markdown_emoji": true, "use_rich_markup": false, diff --git a/tests/expectations/test_rich_click[test metavars default with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test metavars default with rich_config]-click8.config.json index 5ada03df..c3c8cb85 100644 --- a/tests/expectations/test_rich_click[test metavars default with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test metavars default with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": false, diff --git a/tests/expectations/test_rich_click[test metavars with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test metavars with rich_config]-click8.config.json index 309c7b7f..ad792922 100644 --- a/tests/expectations/test_rich_click[test metavars with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test metavars with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": true, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": false, diff --git a/tests/expectations/test_rich_click[test rich markup with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test rich markup with rich_config]-click8.config.json index df704f3a..a8286d56 100644 --- a/tests/expectations/test_rich_click[test rich markup with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test rich markup with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": true, diff --git a/tests/expectations/test_rich_click[test simple with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test simple with rich_config]-click8.config.json index 5ada03df..c3c8cb85 100644 --- a/tests/expectations/test_rich_click[test simple with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test simple with rich_config]-click8.config.json @@ -80,7 +80,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": false, diff --git a/tests/expectations/test_rich_click[test table styles with rich_config]-click8.config.json b/tests/expectations/test_rich_click[test table styles with rich_config]-click8.config.json index 62a81a37..4141d110 100644 --- a/tests/expectations/test_rich_click[test table styles with rich_config]-click8.config.json +++ b/tests/expectations/test_rich_click[test table styles with rich_config]-click8.config.json @@ -88,7 +88,7 @@ "append_metavars_help": false, "group_arguments_options": false, "option_envvar_first": false, - "text_markup": null, + "text_markup": "ansi", "use_markdown": false, "use_markdown_emoji": true, "use_rich_markup": false, From 30af6dc03ce3c40d03d10f93976d0332a506bea2 Mon Sep 17 00:00:00 2001 From: dwreeves Date: Mon, 29 Apr 2024 22:32:08 -0400 Subject: [PATCH 2/2] move from dev to actual --- CHANGELOG.md | 2 +- docs/blog/posts/version-1.8.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5af8c2dd..45fa79bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Version 1.8.0dev (2023-04-09) +## Version 1.8.0 (2023-04-30) - Add `--rich-config` option to the `rich-click` CLI. - Lazy load Rich to reduce overhead when not rendering help text. [[#154](https://github.com/ewels/rich-click/pull/154)] diff --git a/docs/blog/posts/version-1.8.md b/docs/blog/posts/version-1.8.md index 3adb3261..a62a3ca5 100644 --- a/docs/blog/posts/version-1.8.md +++ b/docs/blog/posts/version-1.8.md @@ -679,7 +679,7 @@ We include the code we ran below. The metrics you see above were gathered by run # Times - uv pip install --no-binary :all: "rich-click==1.8.0dev7" + uv pip install --no-binary :all: "rich-click==1.8.0" get_times hello_argparse.py true get_times hello_click.py true @@ -699,7 +699,7 @@ We include the code we ran below. The metrics you see above were gathered by run # Memory profiling uv pip install memory-profiler - uv pip install --no-binary :all: "rich-click==1.8.0dev7" + uv pip install --no-binary :all: "rich-click==1.8.0" get_mprof hello_argparse.py true get_mprof hello_click.py true