Support show_default string in prompts

When `show_default` is set to a string on an option with `prompt=True`,
use that string in the prompt instead of the actual default value,
matching the behavior of the help text.

Squashed from #2837 by Josh Cannon (@thejcannon).

Author: thejcannon

CHANGES.rst

@@ -13,6 +13,7 @@ Unreleased
     ``semver.Version``. :issue:`3298` :pr:`3299`
 -   Fix pager test pollution under parallel execution by using pytest's
     ``tmp_path`` fixture instead of a shared temporary file path. :pr:`3238`
+-   Add support for custom ``show_default`` string in prompts. :pr:`460a142`
 
 Version 8.3.2
 -------------

src/click/core.py

@@ -3164,10 +3164,10 @@ def prompt_for_value(self, ctx: Context) -> t.Any:
                 default = bool(default)
             return confirm(self.prompt, default)
 
-        # If show_default is set to True/False, provide this to `prompt` as well. For
-        # non-bool values of `show_default`, we use `prompt`'s default behavior
+        # If show_default is given, provide this to `prompt` as well,
+        # otherwise we use `prompt`'s default behavior
         prompt_kwargs: t.Any = {}
-        if isinstance(self.show_default, bool):
+        if self.show_default is not None:
             prompt_kwargs["show_default"] = self.show_default
 
         return prompt(

src/click/termui.py

@@ -60,14 +60,16 @@ def hidden_prompt_func(prompt: str) -> str:
 def _build_prompt(
     text: str,
     suffix: str,
-    show_default: bool = False,
+    show_default: bool | str = False,
     default: t.Any | None = None,
     show_choices: bool = True,
     type: ParamType | None = None,
 ) -> str:
     prompt = text
     if type is not None and show_choices and isinstance(type, Choice):
         prompt += f" ({', '.join(map(str, type.choices))})"
+    if isinstance(show_default, str):
+        default = f"({show_default})"
     if default is not None and show_default:
         prompt = f"{prompt} [{_format_default(default)}]"
     return f"{prompt}{suffix}"
@@ -88,7 +90,7 @@ def prompt(
     type: ParamType | t.Any | None = None,
     value_proc: t.Callable[[str], t.Any] | None = None,
     prompt_suffix: str = ": ",
-    show_default: bool = True,
+    show_default: bool | str = True,
     err: bool = False,
     show_choices: bool = True,
 ) -> t.Any:
@@ -112,13 +114,18 @@ def prompt(
                        convert a value.
     :param prompt_suffix: a suffix that should be added to the prompt.
     :param show_default: shows or hides the default value in the prompt.
+                         If this value is a string, it shows that string
+                         in parentheses instead of the actual value.
     :param err: if set to true the file defaults to ``stderr`` instead of
                 ``stdout``, the same as with echo.
     :param show_choices: Show or hide choices if the passed type is a Choice.
                          For example if type is a Choice of either day or week,
                          show_choices is true and text is "Group by" then the
                          prompt will be "Group by (day, week): ".
 
+    .. versionadded:: 8.2
+        ``show_default`` can be a custom string.
+
     .. versionchanged:: 8.3.1
         A space is no longer appended to the prompt.
 

tests/test_options.py

@@ -1259,6 +1259,19 @@ def test_show_default_string(runner):
     assert "[default: (unlimited)]" in message
 
 
+def test_string_show_default_shows_custom_string_in_prompt(runner):
+    @click.command()
+    @click.option(
+        "--arg1", show_default="custom", prompt=True, default="my-default-value"
+    )
+    def cmd(arg1):
+        pass
+
+    result = runner.invoke(cmd, input="my-input", standalone_mode=False)
+    assert "(custom)" in result.output
+    assert "my-default-value" not in result.output
+
+
 class _StrictEq:
     """Object whose ``__eq__`` raises on string comparison (like semver.Version)."""
 

tests/test_termui.py

@@ -612,6 +612,19 @@ def cmd(arg1):
     assert "my-default-value" not in result.output
 
 
+def test_string_show_default_shows_custom_string_in_prompt(runner):
+    @click.command()
+    @click.option(
+        "--arg1", show_default="custom", prompt=True, default="my-default-value"
+    )
+    def cmd(arg1):
+        pass
+
+    result = runner.invoke(cmd, input="my-input", standalone_mode=False)
+    assert "(custom)" in result.output
+    assert "my-default-value" not in result.output
+
+
 REPEAT = object()
 """Sentinel value to indicate that the prompt is expected to be repeated.