Merge branch 'main' into stable

Author: davidism

CHANGES.rst

@@ -1,23 +1,42 @@
 .. currentmodule:: click
 
-Version 8.2.x
--------------
-
-Unreleased
-
--   show correct auto complete value for nargs option in combination with flag option :issue:`2813`
+Version 8.3.0
+--------------
+
+Released 2025-09-15
+
+-   **Improved flag option handling**: Reworked the relationship between ``flag_value``
+    and ``default`` parameters for better consistency:
+
+    * The ``default`` parameter value is now preserved as-is and passed directly
+      to CLI functions (no more unexpected transformations)
+    * Exception: flag options with ``default=True`` maintain backward compatibility
+      by defaulting to their ``flag_value``
+    * The ``default`` parameter can now be any type (``bool``, ``None``, etc.)
+    * Fixes inconsistencies reported in: :issue:`1992` :issue:`2514` :issue:`2610`
+      :issue:`3024` :pr:`3030`
+-   Allow ``default`` to be set on ``Argument`` for ``nargs = -1``. :issue:`2164`
+    :pr:`3030`
+-   Show correct auto complete value for ``nargs`` option in combination with flag
+    option :issue:`2813`
+-   Show correct auto complete value for nargs option in combination with flag option :issue:`2813`
+-   Fix handling of quoted and escaped parameters in Fish autocompletion. :issue:`2995` :pr:`3013`
+-   Lazily import ``shutil``. :pr:`3023`
+-   Properly forward exception information to resources registered with
+    ``click.core.Context.with_resource()``. :issue:`2447` :pr:`3058`
+-   Fix regression related to EOF handling in CliRunner. :issue:`2939`:pr:`2940`
 
 Version 8.2.2
 -------------
 
 Released 2025-07-31
 
--   Fix reconciliation of `default`, `flag_value` and `type` parameters for
+-   Fix reconciliation of ``default``, ``flag_value`` and ``type`` parameters for
     flag options, as well as parsing and normalization of environment variables.
     :issue:`2952` :pr:`2956`
 -   Fix typing issue in ``BadParameter`` and ``MissingParameter`` exceptions for the
     parameter ``param_hint`` that did not allow for a sequence of string where the
-    underlying functino ``_join_param_hints`` allows for it. :issue:`2777` :pr:`2990`
+    underlying function ``_join_param_hints`` allows for it. :issue:`2777` :pr:`2990`
 -   Use the value of ``Enum`` choices to render their default value in help
     screen. Refs :issue:`2911` :pr:`3004`
 -   Fix completion for the Z shell (``zsh``) for completion items containing

docs/options.md

@@ -314,7 +314,7 @@ If you want to define an alias for the second option only, then you will need to
 
 ## Flag Value
 
-To have an flag pass a value to the underlying function set `flag_value`. This automatically sets `is_flag=True`. To set a default flag, set `default=True`. Setting flag values can be used to create patterns like this:
+To have an flag pass a value to the underlying function set `flag_value`. This automatically sets `is_flag=True`. To mark the flag as default, set `default=True`. Setting flag values can be used to create patterns like this:
 
 ```{eval-rst}
 .. click:example::
@@ -335,6 +335,26 @@ To have an flag pass a value to the underlying function set `flag_value`. This a
     invoke(info)
 ```
 
+````{note}
+The `default` value is given to the underlying function as-is. So if you set `default=None`, the value passed to the function is the `None` Python value. Same for any other type.
+
+But there is a special case for flags. If a flag has a `flag_value`, then setting `default=True` is interpreted as *the flag should be activated by default*. So instead of the underlying function receiving the `True` Python value, it will receive the `flag_value`.
+
+Which means, in example above, this option:
+
+```python
+@click.option('--upper', 'transformation', flag_value='upper', default=True)
+```
+
+is equivalent to:
+
+```python
+@click.option('--upper', 'transformation', flag_value='upper', default='upper')
+```
+
+Because the two are equivalent, it is recommended to always use the second form, and set `default` to the actual value you want to pass. And not use the special `True` case. This makes the code more explicit and predictable.
+````
+
 ## Values from Environment Variables
 
 To pass in a value in from a specific environment variable use `envvar`.
@@ -386,10 +406,11 @@ Here are the rules used to parse environment variable values for flag options:
    - If the flag option has a `flag_value` argument, passing that value in the environment variable will activate the flag, in addition to all the cases described above
    - Any other value is interpreted as deactivating the flag
 
-.. caution::
-    For boolean flags with a pair of values, the only recognized environment variable is the one provided to the `envvar` argument.
+```{caution}
+For boolean flags with a pair of values, the only recognized environment variable is the one provided to the `envvar` argument.
 
-    So an option defined as `--flag\--no-flag`, with a `envvar="FLAG"` parameter, there is no magical `NO_FLAG=<anything>` variable that is recognized. Only the `FLAG=<anything>` environment variable is recognized.
+So an option defined as `--flag\--no-flag`, with a `envvar="FLAG"` parameter, there is no magical `NO_FLAG=<anything>` variable that is recognized. Only the `FLAG=<anything>` environment variable is recognized.
+```
 
 Once the status of the flag has been determine to be activated or not, the `flag_value` is used as the value of the flag if it is activated. If the flag is not activated, the value of the flag is set to `None` by default.
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "click"
-version = "8.2.2"
+version = "8.3.0"
 description = "Composable command line interface toolkit"
 readme = "README.md"
 license = "BSD-3-Clause"

src/click/_utils.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import enum
+import typing as t
+
+
+class Sentinel(enum.Enum):
+    """Enum used to define sentinel values.
+
+    .. seealso::
+
+        `PEP 661 - Sentinel Values <https://peps.python.org/pep-0661/>`_.
+    """
+
+    UNSET = object()
+    FLAG_NEEDS_VALUE = object()
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+UNSET = Sentinel.UNSET
+"""Sentinel used to indicate that a value is not set."""
+
+FLAG_NEEDS_VALUE = Sentinel.FLAG_NEEDS_VALUE
+"""Sentinel used to indicate an option was passed as a flag without a
+value but is not a flag option.
+
+``Option.consume_value`` uses this to prompt or use the ``flag_value``.
+"""
+
+T_UNSET = t.Literal[UNSET]  # type: ignore[valid-type]
+"""Type hint for the :data:`UNSET` sentinel value."""
+
+T_FLAG_NEEDS_VALUE = t.Literal[FLAG_NEEDS_VALUE]  # type: ignore[valid-type]
+"""Type hint for the :data:`FLAG_NEEDS_VALUE` sentinel value."""