Repository: pallets/click
Pull request #2821 (2024-12-15 04:32:32)

Rewrite help page section.
Rewrite help page generation section, formerly documenting script.

AndreasBackx: Could you also rebase this on main?
Rowlando13: Can do both. 
Rowlando13: Do you want all docs based on main or just this branch?

Patch:
diff --git a/CHANGES.rst b/CHANGES.rst
index 057d700..a90ff58 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -88,13 +88,6 @@ Unreleased
     -   Parameters cannot be required nor prompted or an error is raised.
     -   A warning will be printed when something deprecated is used.
 
--   Add a ``catch_exceptions`` parameter to :class:`CliRunner`. If
-    ``catch_exceptions`` is not passed to :meth:`CliRunner.invoke`,
-    the value from :class:`CliRunner`. :issue:`2817` :pr:`2818`
--   ``Option.flag_value`` will no longer have a default value set based on
-    ``Option.default`` if ``Option.is_flag`` is ``False``. This results in
-    ``Option.default`` not needing to implement `__bool__`. :pr:`2829`
--   Incorrect ``click.edit`` typing has been corrected. :pr:`2804`
 
 Version 8.1.8
 -------------
diff --git a/docs/documentation.rst b/docs/documentation.rst
index da0aaa1..9de9fac 100644
--- a/docs/documentation.rst
+++ b/docs/documentation.rst
@@ -1,32 +1,29 @@
-Documenting Scripts
+Help Pages
 ===================
 
 .. currentmodule:: click
 
-Click makes it very easy to document your command line tools.  First of
-all, it automatically generates help pages for you.  While these are
-currently not customizable in terms of their layout, all of the text
-can be changed.
+Click makes it very easy to document your command line tools. For most things Click automatically generates help pages for you. By design the text is customizable, but the layout is not.
 
 Help Texts
-----------
+--------------
 
-Commands and options accept help arguments.  In the case of commands, the
-docstring of the function is automatically used if provided.
+Commands and options accept help arguments. For commands, the docstring of the function is automatically used if provided.
 
 Simple example:
 
 .. click:example::
 
     @click.command()
-    @click.option('--count', default=1, help='number of greetings')
     @click.argument('name')
-    def hello(count, name):
-        """This script prints hello NAME COUNT times."""
+    @click.option('--count', default=1, help='number of greetings')
+    def hello(name: str, count: int):
+        """This script prints hello and a name one or more times."""
         for x in range(count):
-            click.echo(f"Hello {name}!")
-
-And what it looks like:
+            if name:
+                click.echo(f"Hello {name}!")
+            else:
+                click.echo("Hello!")
 
 .. click:run::
 
@@ -35,15 +32,51 @@ And what it looks like:
 
 .. _documenting-arguments:
 
+Command Short Help
+------------------
+
+For subcommands, a short help snippet is generated. By default, it's the first sentence of the docstring. If too long, then it will ellipsize what cannot be fit on a single line with ``...``.  The short help snippet can also be overridden with ``short_help``:
+
+.. click:example::
+
+    @click.group()
+    def cli():
+        """A simple command line tool."""
+
+    @cli.command('init', short_help='init the repo')
+    def init():
+        """Initializes the repository."""
+
+
+.. click:run::
+
+    invoke(cli, args=['--help'])
+
+Command Epilog Help
+-------------------
+
+The help epilog is printed at the end of the help and is useful for showing example command usages or referencing additional help resources.
+
+.. click:example::
+
+    @click.command(
+    	epilog='See https://example.com for more details',
+  	)
+    def init():
+        """Initializes the repository."""
+
+
+.. click:run::
+
+    invoke(init, args=['--help'])
+
 Documenting Arguments
 ----------------------
 
-:func:`click.argument` does not take a ``help`` parameter. This is to
-follow the general convention of Unix tools of using arguments for only
-the most necessary things, and to document them in the command help text
-by referring to them by name.
+:class:`click.argument` does not take a ``help`` parameter. This follows the Unix Command Line Tools convention of using arguments only for necessary things and documenting them in the command help text
+by name. This should then be done via the docstring.
 
-You might prefer to reference the argument in the description:
+A brief example:
 
 .. click:example::
 
@@ -53,13 +86,12 @@ You might prefer to reference the argument in the description:
         """Print FILENAME."""
         click.echo(filename)
 
-And what it looks like:
 
 .. click:run::
 
     invoke(touch, args=['--help'])
 
-Or you might prefer to explicitly provide a description of the argument:
+Or more explicitly:
 
 .. click:example::
 
@@ -72,26 +104,36 @@ Or you might prefer to explicitly provide a description of the argument:
         """
         click.echo(filename)
 
-And what it looks like:
-
 .. click:run::
 
     invoke(touch, args=['--help'])
 
-For more examples, see the examples in :doc:`/arguments`.
+Click's Wrapping Behavior
+----------------------------
+Click's default wrapping ignores single new lines and rewraps the text based on the width of the terminal, to a maximum of 80 characters. In the example notice how the second grouping of three lines is rewrapped into a single paragraph.
 
+.. click:example::
 
-Preventing Rewrapping
----------------------
+    @click.command()
+    def cli():
+        """
+        This is a very long paragraph and as you
+        can see wrapped very early in the source text
+        but will be rewrapped to the terminal width in
+        the final output.
 
-The default behavior of Click is to rewrap text based on the width of the
-terminal, to a maximum 80 characters. In some circumstances, this can become
-a problem. The main issue is when showing code examples, where newlines are
-significant.
+        This is
+        a paragraph
+        that is compacted.
+        """
 
-Rewrapping can be disabled on a per-paragraph basis by adding a line with
-solely the ``\b`` escape marker in it.  This line will be removed from the
-help text and rewrapping will be disabled.
+.. click:run::
+
+    invoke(cli, args=['--help'])
+
+Escaping Click's Wrapping
+---------------------------
+Sometimes Click's wrapping can be a problem, such as when showing code examples where newlines are significant. This behavior can be escaped on a per-paragraph basis by adding a line with only ``\b`` . The ``\b`` is removed from the rendered help text.
 
 Example:
 
@@ -101,11 +143,6 @@ Example:
     def cli():
         """First paragraph.
 
-        This is a very long second paragraph and as you
-        can see wrapped very early in the source text
-        but will be rewrapped to the terminal width in
-        the final output.
-
         \b
         This is
         a paragraph
@@ -115,71 +152,55 @@ Example:
         that will be rewrapped again.
         """
 
-And what it looks like:
 
 .. click:run::
 
     invoke(cli, args=['--help'])
 
-To change the maximum width, pass ``max_content_width`` when calling the command.
+To change the rendering maximum width, pass ``max_content_width`` when calling the command.
 
 .. code-block:: python
 
     cli(max_content_width=120)
 
-
 .. _doc-meta-variables:
 
 Truncating Help Texts
 ---------------------
 
-Click gets command help text from function docstrings.  However if you
-already use docstrings to document function arguments you may not want
-to see :param: and :return: lines in your help text.
-
-You can use the ``\f`` escape marker to have Click truncate the help text
-after the marker.
+Click gets :class:`Command` help text from the docstring. If you do not want to include part of the docstring, add the ``\f`` escape marker to have Click truncate the help text after the marker.
 
 Example:
 
 .. click:example::
 
     @click.command()
-    @click.pass_context
-    def cli(ctx):
+    def cli():
         """First paragraph.
-
-        This is a very long second
-        paragraph and not correctly
-        wrapped but it will be rewrapped.
         \f
 
-        :param click.core.Context ctx: Click context.
+        Words to not be included.
         """
 
-And what it looks like:
-
 .. click:run::
 
     invoke(cli, args=['--help'])
 
 
-Meta Variables
---------------
+Placeholder / Meta Variable
+-----------------------------
 
-Options and parameters accept a ``metavar`` argument that can change the
-meta variable in the help page.  The default version is the parameter name
-in uppercase with underscores, but can be annotated differently if
-desired.  This can be customized at all levels:
+The default placeholder variable (`meta variable <https://en.wikipedia.org/wiki/Metasyntactic_variable#IETF_Requests_for_Comments>`_) in the help pages is the parameter name in uppercase with underscores. This can be changed for Commands and Parameters with the ``options_metavar`` and  ``metavar`` kwargs.
 
 .. click:example::
 
-    @click.command(options_metavar='<options>')
+    # This controls entry on the usage line.
+    @click.command(options_metavar='[[options]]')
     @click.option('--count', default=1, help='number of greetings',
                   metavar='<int>')
     @click.argument('name', metavar='<name>')
-    def hello(count, name):
-        """This script prints hello <name> <int> times."""
+    def hello(name: str, count: int) -> None:
+        """This script prints 'hello <name>' a total of <count> times."""
         for x in range(count):
             click.echo(f"Hello {name}!")
 
@@ -189,65 +210,9 @@ Example:
 
     invoke(hello, args=['--help'])
 
-
-Command Short Help
-------------------
-
-For commands, a short help snippet is generated.  By default, it's the first
-sentence of the help message of the command, unless it's too long.  This can
-also be overridden:
-
-.. click:example::
-
-    @click.group()
-    def cli():
-        """A simple command line tool."""
-
-    @cli.command('init', short_help='init the repo')
-    def init():
-        """Initializes the repository."""
-
-    @cli.command('delete', short_help='delete the repo')
-    def delete():
-        """Deletes the repository."""
-
-And what it looks like:
-
-.. click:run::
-
-    invoke(cli, prog_name='repo.py')
-
-Command Epilog Help
--------------------
-
-The help epilog is like the help string but it's printed at the end of the help
-page after everything else. Useful for showing example command usages or
-referencing additional help resources.
-
-.. click:example::
-
-    @click.command(epilog='Check out our docs at https://click.palletsprojects.com/ for more details')
-    def init():
-        """Initializes the repository."""
-
-And what it looks like:
-
-.. click:run::
-
-    invoke(init, prog_name='repo.py', args=['--help'])
-
 Help Parameter Customization
 ----------------------------
-
-.. versionadded:: 2.0
-
-The help parameter is implemented in Click in a very special manner.
-Unlike regular parameters it's automatically added by Click for any
-command and it performs automatic conflict resolution.  By default it's
-called ``--help``, but this can be changed.  If a command itself implements
-a parameter with the same name, the default help parameter stops accepting
-it.  There is a context setting that can be used to override the names of
-the help parameters called :attr:`~Context.help_option_names`.
+Help parameters are automatically added by Click for any command. The default is ``--help`` but can be override by the context setting :attr:`~Context.help_option_names`. Click also performs automatic conflict resolution on the default help parameter so if a command itself implements a parameter named ``help`` then the default help will not be run.
 
 This example changes the default parameters to ``-h`` and ``--help``
 instead of just ``--help``:
@@ -260,7 +225,6 @@ instead of just ``--help``:
     def cli():
         pass
 
-And what it looks like:
 
 .. click:run::
 
diff --git a/docs/index.rst b/docs/index.rst
index d094efb..0232587 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -72,11 +72,11 @@ usage patterns.
    virtualenv
    setuptools
    parameters
-   options
    arguments
+   options
    commands
-   prompts
    documentation
+   prompts
    complex
    advanced
    testing
diff --git a/src/click/_compat.py b/src/click/_compat.py
index f2726b9..feb8366 100644
--- a/src/click/_compat.py
+++ b/src/click/_compat.py
@@ -538,14 +538,14 @@ if sys.platform.startswith("win") and WIN:
         rv = t.cast(t.TextIO, ansi_wrapper.stream)
         _write = rv.write
 
-        def _safe_write(s: str) -> int:
+        def _safe_write(s):
             try:
                 return _write(s)
             except BaseException:
                 ansi_wrapper.reset_all()
                 raise
 
-        rv.write = _safe_write  # type: ignore[method-assign]
+        rv.write = _safe_write
 
         try:
             _ansi_stream_wrappers[stream] = rv
diff --git a/src/click/_termui_impl.py b/src/click/_termui_impl.py
index 833b9fe..a6c7e6b 100644
--- a/src/click/_termui_impl.py
+++ b/src/click/_termui_impl.py
@@ -545,18 +545,10 @@ class Editor:
                 _("{editor}: Editing failed: {e}").format(editor=editor, e=e)
             ) from e
 
-    @t.overload
-    def edit(self, text: bytes | bytearray) -> bytes | None: ...
-
-    # We cannot know whether or not the type expected is str or bytes when None
-    # is passed, so str is returned as that was what was done before.
-    @t.overload
-    def edit(self, text: str | None) -> str | None: ...
-
-    def edit(self, text: str | bytes | bytearray | None) -> str | bytes | None:
+    def edit(self, text: t.AnyStr | None) -> t.AnyStr | None:
         import tempfile
 
-        if text is None:
+        if not text:
             data = b""
         elif isinstance(text, (bytes, bytearray)):
             data = text
@@ -596,7 +588,7 @@ class Editor:
             if isinstance(text, (bytes, bytearray)):
                 return rv
 
-            return rv.decode("utf-8-sig").replace("\r\n", "\n")
+            return rv.decode("utf-8-sig").replace("\r\n", "\n")  # type: ignore
         finally:
             os.unlink(name)
 
@@ -674,7 +666,7 @@ def _translate_ch_to_exc(ch: str) -> None:
     return None
 
 
-if sys.platform == "win32":
+if WIN:
     import msvcrt
 
     @contextlib.contextmanager
@@ -711,11 +703,12 @@ if sys.platform == "win32":
         #
         # Anyway, Click doesn't claim to do this Right(tm), and using `getwch`
         # is doing the right thing in more situations than with `getch`.
+        func: t.Callable[[], str]
 
         if echo:
-            func = t.cast(t.Callable[[], str], msvcrt.getwche)
+            func = msvcrt.getwche  # type: ignore
         else:
-            func = t.cast(t.Callable[[], str], msvcrt.getwch)
+            func = msvcrt.getwch  # type: ignore
 
         rv = func()
 
diff --git a/src/click/_winconsole.py b/src/click/_winconsole.py
index b01035b..a91af0e 100644
--- a/src/click/_winconsole.py
+++ b/src/click/_winconsole.py
@@ -13,7 +13,6 @@ import io
 import sys
 import time
 import typing as t
-from ctypes import Array
 from ctypes import byref
 from ctypes import c_char
 from ctypes import c_char_p
@@ -68,14 +67,6 @@ STDERR_FILENO = 2
 EOF = b"\x1a"
 MAX_BYTES_WRITTEN = 32767
 
-if t.TYPE_CHECKING:
-    try:
-        # Using `typing_extensions.Buffer` instead of `collections.abc`
-        # on Windows for some reason does not have `Sized` implemented.
-        from collections.abc import Buffer  # type: ignore
-    except ImportError:
-        from typing_extensions import Buffer
-
 try:
     from ctypes import pythonapi
 except ImportError:
@@ -102,32 +93,32 @@ else:
     PyObject_GetBuffer = pythonapi.PyObject_GetBuffer
     PyBuffer_Release = pythonapi.PyBuffer_Release
 
-    def get_buffer(obj: Buffer, writable: bool = False) -> Array[c_char]:
+    def get_buffer(obj, writable=False):
         buf = Py_buffer()
-        flags: int = PyBUF_WRITABLE if writable else PyBUF_SIMPLE
+        flags = PyBUF_WRITABLE if writable else PyBUF_SIMPLE
         PyObject_GetBuffer(py_object(obj), byref(buf), flags)
 
         try:
-            buffer_type: Array[c_char] = c_char * buf.len
+            buffer_type = c_char * buf.len
             return buffer_type.from_address(buf.buf)
         finally:
             PyBuffer_Release(byref(buf))
 
 
 class _WindowsConsoleRawIOBase(io.RawIOBase):
-    def __init__(self, handle: int | None) -> None:
+    def __init__(self, handle):
         self.handle = handle
 
-    def isatty(self) -> t.Literal[True]:
+    def isatty(self):
         super().isatty()
         return True
 
 
 class _WindowsConsoleReader(_WindowsConsoleRawIOBase):
-    def readable(self) -> t.Literal[True]:
+    def readable(self):
         return True
 
-    def readinto(self, b: Buffer) -> int:
+    def readinto(self, b):
         bytes_to_be_read = len(b)
         if not bytes_to_be_read:
             return 0
@@ -159,18 +150,18 @@ class _WindowsConsoleReader(_WindowsConsoleRawIOBase):
 
 
 class _WindowsConsoleWriter(_WindowsConsoleRawIOBase):
-    def writable(self) -> t.Literal[True]:
+    def writable(self):
         return True
 
     @staticmethod
-    def _get_error_message(errno: int) -> str:
+    def _get_error_message(errno):
         if errno == ERROR_SUCCESS:
             return "ERROR_SUCCESS"
         elif errno == ERROR_NOT_ENOUGH_MEMORY:
             return "ERROR_NOT_ENOUGH_MEMORY"
         return f"Windows error {errno}"
 
-    def write(self, b: Buffer) -> int:
+    def write(self, b):
         bytes_to_be_written = len(b)
         buf = get_buffer(b)
         code_units_to_be_written = min(bytes_to_be_written, MAX_BYTES_WRITTEN) // 2
@@ -218,7 +209,7 @@ class ConsoleStream:
     def isatty(self) -> bool:
         return self.buffer.isatty()
 
-    def __repr__(self) -> str:
+    def __repr__(self):
         return f"<ConsoleStream name={self.name!r} encoding={self.encoding!r}>"
 
 
@@ -276,20 +267,16 @@ def _get_windows_console_stream(
     f: t.TextIO, encoding: str | None, errors: str | None
 ) -> t.TextIO | None:
     if (
-        get_buffer is None
-        or encoding not in {"utf-16-le", None}
-        or errors not in {"strict", None}
-        or not _is_console(f)
+        get_buffer is not None
+        and encoding in {"utf-16-le", None}
+        and errors in {"strict", None}
+        and _is_console(f)
     ):
-        return None
-
-    func = _stream_factories.get(f.fileno())
-    if func is None:
-        return None
-
-    b = getattr(f, "buffer", None)
+        func = _stream_factories.get(f.fileno())
+        if func is not None:
+            b = getattr(f, "buffer", None)
 
-    if b is None:
-        return None
+            if b is None:
+                return None
 
-    return func(b)
+            return func(b)
diff --git a/src/click/core.py b/src/click/core.py
index e783729..1c1a467 100644
--- a/src/click/core.py
+++ b/src/click/core.py
@@ -2597,10 +2597,11 @@ class Option(Parameter):
             else:
                 self.default = False
 
+        if flag_value is None:
+            flag_value = not self.default
+
         self.type: types.ParamType
         if is_flag and type is None:
-            if flag_value is None:
-                flag_value = not self.default
             # Re-guess the type from the flag value instead of the
             # default.
             self.type = types.convert_type(None, flag_value)
diff --git a/src/click/termui.py b/src/click/termui.py
index dcbb222..d30dc19 100644
--- a/src/click/termui.py
+++ b/src/click/termui.py
@@ -686,22 +686,12 @@ def secho(
 
 @t.overload
 def edit(
-    text: bytes | bytearray,
-    editor: str | None = None,
-    env: cabc.Mapping[str, str] | None = None,
-    require_save: bool = False,
-    extension: str = ".txt",
-) -> bytes | None: ...
-
-
-@t.overload
-def edit(
-    text: str,
+    text: t.AnyStr,
     editor: str | None = None,
     env: cabc.Mapping[str, str] | None = None,
     require_save: bool = True,
     extension: str = ".txt",
-) -> str | None: ...
+) -> t.AnyStr: ...
 
 
 @t.overload
@@ -716,13 +706,13 @@ def edit(
 
 
 def edit(
-    text: str | bytes | bytearray | None = None,
+    text: t.AnyStr | None = None,
     editor: str | None = None,
     env: cabc.Mapping[str, str] | None = None,
     require_save: bool = True,
     extension: str = ".txt",
     filename: str | cabc.Iterable[str] | None = None,
-) -> str | bytes | bytearray | None:
+) -> t.AnyStr | None:
     r"""Edits the given text in the defined editor.  If an editor is given
     (should be the full path to the executable but the regular operating
     system search path is used for finding the executable) it overrides
diff --git a/tox.ini b/tox.ini
index 744b162..5d0d186 100644
--- a/tox.ini
+++ b/tox.ini
@@ -23,15 +23,9 @@ commands = pre-commit run --all-files
 [testenv:typing]
 deps = -r requirements/typing.txt
 commands =
-    mypy --platform linux
-    mypy --platform darwin
-    mypy --platform win32
-    pyright tests/typing --pythonplatform Linux
-    pyright tests/typing --pythonplatform Darwin
-    pyright tests/typing --pythonplatform Windows
-    pyright --verifytypes click --ignoreexternal --pythonplatform Linux
-    pyright --verifytypes click --ignoreexternal --pythonplatform Darwin
-    pyright --verifytypes click --ignoreexternal --pythonplatform Windows
+    mypy
+    pyright tests/typing
+    pyright --verifytypes click --ignoreexternal
 
 [testenv:docs]
 deps = -r requirements/docs.txt


Test patch:
diff --git a/src/click/testing.py b/src/click/testing.py
index 9972d66..73462db 100644
--- a/src/click/testing.py
+++ b/src/click/testing.py
@@ -227,11 +227,6 @@ class CliRunner:
                        to `<stdout>`.  This is useful for showing examples in
                        some circumstances.  Note that regular prompts
                        will automatically echo the input.
-    :param catch_exceptions: Whether to catch any exceptions other than
-                             ``SystemExit`` when running :meth:`~CliRunner.invoke`.
-
-    .. versionchanged:: 8.2
-        Added the ``catch_exceptions`` parameter.
 
     .. versionchanged:: 8.2
         ``mix_stderr`` parameter has been removed.
@@ -242,12 +237,10 @@ class CliRunner:
         charset: str = "utf-8",
         env: cabc.Mapping[str, str | None] | None = None,
         echo_stdin: bool = False,
-        catch_exceptions: bool = True,
     ) -> None:
         self.charset = charset
         self.env: cabc.Mapping[str, str | None] = env or {}
         self.echo_stdin = echo_stdin
-        self.catch_exceptions = catch_exceptions
 
     def get_default_prog_name(self, cli: Command) -> str:
         """Given a command object it will return the default program name
@@ -417,7 +410,7 @@ class CliRunner:
         args: str | cabc.Sequence[str] | None = None,
         input: str | bytes | t.IO[t.Any] | None = None,
         env: cabc.Mapping[str, str | None] | None = None,
-        catch_exceptions: bool | None = None,
+        catch_exceptions: bool = True,
         color: bool = False,
         **extra: t.Any,
     ) -> Result:
@@ -436,8 +429,7 @@ class CliRunner:
         :param input: the input data for `sys.stdin`.
         :param env: the environment overrides.
         :param catch_exceptions: Whether to catch any other exceptions than
-                                 ``SystemExit``. If :data:`None`, the value
-                                 from :class:`CliRunner` is used.
+                                 ``SystemExit``.
         :param extra: the keyword arguments to pass to :meth:`main`.
         :param color: whether the output should contain color codes. The
                       application can still override this explicitly.
@@ -465,9 +457,6 @@ class CliRunner:
             traceback if available.
         """
         exc_info = None
-        if catch_exceptions is None:
-            catch_exceptions = self.catch_exceptions
-
         with self.isolation(input=input, env=env, color=color) as outstreams:
             return_value = None
             exception: BaseException | None = None
diff --git a/tests/test_info_dict.py b/tests/test_info_dict.py
index 11b6703..79d39ee 100644
--- a/tests/test_info_dict.py
+++ b/tests/test_info_dict.py
@@ -58,7 +58,7 @@ NUMBER_OPTION = (
         "help": None,
         "prompt": None,
         "is_flag": False,
-        "flag_value": None,
+        "flag_value": False,
         "count": False,
         "hidden": False,
     },
diff --git a/tests/test_testing.py b/tests/test_testing.py
index 55d6470..0f2d512 100644
--- a/tests/test_testing.py
+++ b/tests/test_testing.py
@@ -184,28 +184,6 @@ def test_catch_exceptions():
     assert result.exit_code == 1
 
 
-def test_catch_exceptions_cli_runner():
-    """Test that invoke `catch_exceptions` takes the value from CliRunner if not set
-    explicitly."""
-
-    class CustomError(Exception):
-        pass
-
-    @click.command()
-    def cli():
-        raise CustomError(1)
-
-    runner = CliRunner(catch_exceptions=False)
-
-    result = runner.invoke(cli, catch_exceptions=True)
-    assert isinstance(result.exception, CustomError)
-    assert type(result.exc_info) is tuple
-    assert len(result.exc_info) == 3
-
-    with pytest.raises(CustomError):
-        runner.invoke(cli)
-
-
 def test_with_color():
     @click.command()
     def cli():