Merge pull request #193 from dwreeves/one-last-change

update

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)]
@@ -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`

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

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

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")

docs/overrides/editor.html

@@ -128,6 +128,7 @@ <h1 id="terminal-header">Live Style Editor</h1>
 
 <p><strong>The style options here are not exhaustive!</strong>
 There are many more ways to customize your <strong>rich-click</strong> outputs.
+Modern terminals also support more than the 8 colors used on this page; <a href="https://rich.readthedocs.io/en/stable/appendix/colors.html">see here for more information about terminal colors</a>.
 The Live Style Editor seeks to represent a useful subset of the available styling options.</p>
 <div class="container">
     <div class="left-column">

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[/])

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)

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))
 

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,

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,

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,

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,

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,

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,

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,

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,

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,

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,

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,