Resolve conflicts from main.

CHANGES.rst

@@ -7,8 +7,8 @@ Unreleased
 
 -   Drop support for Python 3.7. :pr:`2588`
 -   Use modern packaging metadata with ``pyproject.toml`` instead of ``setup.cfg``.
-    :pr:`326`
--   Use ``flit_core`` instead of ``setuptools`` as build backend.
+    :pr:`2438`
+-   Use ``flit_core`` instead of ``setuptools`` as build backend. :pr:`2543`
 -   Deprecate the ``__version__`` attribute. Use feature detection, or
     ``importlib.metadata.version("click")``, instead. :issue:`2598`
 -   ``BaseCommand`` is deprecated. ``Command`` is the base class for all
@@ -41,7 +41,7 @@ Unreleased
     :pr:`2517`
 -   Keep stdout and stderr streams independent in ``CliRunner``. Always
     collect stderr output and never raise an exception. Add a new
-    output` stream to simulate what the user sees in its terminal. Removes
+    output stream to simulate what the user sees in its terminal. Removes
     the ``mix_stderr`` parameter in ``CliRunner``. :issue:`2522` :pr:`2523`
 -   ``Option.show_envvar`` now also shows environment variable in error messages.
     :issue:`2695` :pr:`2696`
@@ -50,7 +50,7 @@ Unreleased
     ``Context.with_resource`` to be closed on exit as well. :pr:`2680`
 -   Add ``ProgressBar(hidden: bool)`` to allow hiding the progressbar. :issue:`2609`
 -   A ``UserWarning`` will be shown when multiple parameters attempt to use the
-    same name. :issue:`2396``
+    same name. :issue:`2396`
 -   When using ``Option.envvar`` with ``Option.flag_value``, the ``flag_value``
     will always be used instead of the value of the environment variable.
     :issue:`2746` :pr:`2788`
@@ -60,7 +60,7 @@ Unreleased
     for groups, ``False`` for commands), the exit code is 2 instead of 0.
     :issue:`1489` :pr:`1489`
 -   Contexts created during shell completion are closed properly, fixing
-    ``ResourceWarning``s when using ``click.File``. :issue:`2644` :pr:`2800`
+    a ``ResourceWarning`` when using ``click.File``. :issue:`2644` :pr:`2800`
     :pr:`2767`
 -   ``click.edit(filename)`` now supports passing an iterable of filenames in
     case the editor supports editing multiple files at once. Its return type
@@ -88,13 +88,16 @@ 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`
+-   Add a ``catch_exceptions`` parameter to ``CliRunner``. If
+    ``catch_exceptions`` is not passed to ``CliRunner.invoke``,
+    the value from ``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`
+-   ``Choice`` is now generic and supports any iterable value.
+    This allows you to use enums and other non-``str`` values. :pr:`2796`
+    :issue:`605`
 
 Version 8.1.8
 -------------

docs/api.rst

@@ -113,6 +113,7 @@ Context
     :members:
     :member-order: bysource
 
+.. _click-api-types:
 
 Types
 -----

docs/documentation.rst

@@ -108,6 +108,42 @@ Or more explicitly:
 
     invoke(touch, args=['--help'])
 
+
+Showing Defaults
+---------------------------
+To control the appearance of defaults pass ``show_default``.
+
+.. click:example::
+
+    @click.command()
+    @click.option('--n', default=1, show_default=False, help='number of dots')
+    def dots(n):
+        click.echo('.' * n)
+
+.. click:run::
+
+    invoke(dots, args=['--help'])
+
+For single option boolean flags, the default remains hidden if the default value is False even if show default is true.
+
+.. click:example::
+
+    @click.command()
+    @click.option('--n', default=1, show_default=True)
+    @click.option("--gr", is_flag=True, show_default=True, default=False, help="Greet the world.")
+    @click.option("--br", is_flag=True, show_default=True, default=True, help="Add a thematic break")
+    def dots(n, gr, br):
+        if gr:
+            click.echo('Hello world!')
+        click.echo('.' * n)
+        if br:
+            click.echo('-' * n)
+
+.. click:run::
+
+   invoke(dots, args=['--help'])
+
+
 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.

docs/index.rst

@@ -72,10 +72,12 @@ usage patterns.
    virtualenv
    setuptools
    parameters
-   arguments
+   parameter-types
    options
-   commands-and-groups
+   option-decorators
+   arguments
    commands
+   commands-and-groups
    documentation
    prompts
    complex

docs/option-decorators.rst

@@ -0,0 +1,80 @@
+Options Shortcut Decorators
+===========================
+
+.. currentmodule:: click
+
+For convenience commonly used combinations of options arguments are available as their own decorators.
+
+.. contents::
+    :depth: 2
+    :local:
+
+Password Option
+------------------
+
+Click supports hidden prompts and asking for confirmation.  This is
+useful for password input:
+
+.. click:example::
+
+    import codecs
+
+    @click.command()
+    @click.option(
+        "--password", prompt=True, hide_input=True,
+        confirmation_prompt=True
+    )
+    def encode(password):
+        click.echo(f"encoded: {codecs.encode(password, 'rot13')}")
+
+.. click:run::
+
+    invoke(encode, input=['secret', 'secret'])
+
+Because this combination of parameters is quite common, this can also be
+replaced with the :func:`password_option` decorator:
+
+.. code-block:: python
+
+    @click.command()
+    @click.password_option()
+    def encrypt(password):
+        click.echo(f"encoded: to {codecs.encode(password, 'rot13')}")
+
+Confirmation Option
+--------------------
+
+For dangerous operations, it's very useful to be able to ask a user for
+confirmation.  This can be done by adding a boolean ``--yes`` flag and
+asking for confirmation if the user did not provide it and to fail in a
+callback:
+
+.. click:example::
+
+    def abort_if_false(ctx, param, value):
+        if not value:
+            ctx.abort()
+
+    @click.command()
+    @click.option('--yes', is_flag=True, callback=abort_if_false,
+                  expose_value=False,
+                  prompt='Are you sure you want to drop the db?')
+    def dropdb():
+        click.echo('Dropped all tables!')
+
+And what it looks like on the command line:
+
+.. click:run::
+
+    invoke(dropdb, input=['n'])
+    invoke(dropdb, args=['--yes'])
+
+Because this combination of parameters is quite common, this can also be
+replaced with the :func:`confirmation_option` decorator:
+
+.. click:example::
+
+    @click.command()
+    @click.confirmation_option(prompt='Are you sure you want to drop the db?')
+    def dropdb():
+        click.echo('Dropped all tables!')