Ensure that 'type_cast_value' never gets 'UNSET'

In order to ensure that user-defined `type_cast_value` hooks are never
called with a value of `UNSET`, it is necessary to intercept `UNSET`
values and, in the particular cases in which `UNSET` needs special
handling, preempt any call to `type_cast_value()`.

`process_value()` is updated to check before calling `type_cast_value`
and to skip the call entirely if an `UNSET` value is detected. Passing
a value of `None` would not have the same effect for `click.Option`,
which previously had logic which is specific to the `value is UNSET`
case, and which cannot be reliably detected if a `None` value is
passed in.

This means that `type_cast_value()` is no longer guaranteed to be called
during argument processing, but when it is called, it's guaranteed not to
see an `UNSET` value. New tests explore this only from the perspective of
checking if `UNSET` is ever passed, not in terms of pinning down when/if
the hook gets called.

resolves #3069

Author: sirosen

CHANGES.rst

@@ -11,6 +11,8 @@ Unreleased
     the ``Context.invoke()`` method. :issue:`3066` :issue:`3065` :pr:`3068`
 -   Fix conversion of ``Sentinel.UNSET`` happening too early, which caused incorrect
     behavior for multiple parameters using the same name. :issue:`3071` :pr:`3079`
+-   When ``Sentinel.UNSET`` is found during parsing, it will skip calls to
+    ``type_cast_value``. :issue:`3069`
 
 Version 8.3.0
 --------------

src/click/core.py

@@ -2338,7 +2338,7 @@ def type_cast_value(self, ctx: Context, value: t.Any) -> t.Any:
         """Convert and validate a value against the parameter's
         :attr:`type`, :attr:`multiple`, and :attr:`nargs`.
         """
-        if value in (None, UNSET):
+        if value is None:
             if self.multiple or self.nargs == -1:
                 return ()
             else:
@@ -2421,7 +2421,16 @@ def process_value(self, ctx: Context, value: t.Any) -> t.Any:
 
         :meta private:
         """
-        value = self.type_cast_value(ctx, value)
+        # shelter `type_cast_value` from ever seeing an `UNSET` value by handling the
+        # cases in which `UNSET` gets special treatment explicitly at this layer
+        #
+        # Refs:
+        # https://github.com/pallets/click/issues/3069
+        if value is UNSET:
+            if self.multiple or self.nargs == -1:
+                value = ()
+        else:
+            value = self.type_cast_value(ctx, value)
 
         if self.required and self.value_is_missing(value):
             raise MissingParameter(ctx=ctx, param=self)
@@ -3256,13 +3265,22 @@ def consume_value(
 
         return value, source
 
-    def type_cast_value(self, ctx: Context, value: t.Any) -> t.Any:
-        if self.is_flag and not self.required:
-            if value is UNSET:
-                if self.is_bool_flag:
-                    # If the flag is a boolean flag, we return False if it is not set.
-                    value = False
-        return super().type_cast_value(ctx, value)
+    def process_value(self, ctx: Context, value: t.Any) -> t.Any:
+        # process_value has to be overridden on Options in order to capture
+        # `value == UNSET` cases before `type_cast_value()` gets called.
+        #
+        # Refs:
+        # https://github.com/pallets/click/issues/3069
+        if self.is_flag and not self.required and self.is_bool_flag and value is UNSET:
+            value = False
+
+            if self.callback is not None:
+                value = self.callback(ctx, self, value)
+
+            return value
+
+        # in the normal case, rely on Parameter.process_value
+        return super().process_value(ctx, value)
 
 
 class Argument(Parameter):

tests/test_arguments.py

@@ -579,3 +579,40 @@ def cli(one, two):
 
     with pytest.warns(UserWarning):
         runner.invoke(cli, [])
+
+
+@pytest.mark.parametrize(
+    ("argument_kwargs", "pass_argv"),
+    (
+        # there is a large potential parameter space to explore here
+        # this is just a very small sample of it
+        ({}, ["myvalue"]),
+        ({"nargs": -1}, []),
+        ({"nargs": -1}, ["myvalue"]),
+        ({"default": None}, ["myvalue"]),
+        ({"required": False}, []),
+        ({"required": False}, ["myvalue"]),
+    ),
+)
+def test_argument_custom_class_can_override_type_cast_value_and_never_sees_unset(
+    runner, argument_kwargs, pass_argv
+):
+    """
+    Test that overriding type_cast_value is supported
+
+    In particular, the argument is never passed an UNSET sentinel value.
+    """
+
+    class CustomArgument(click.Argument):
+        def type_cast_value(self, ctx, value):
+            assert value is not UNSET
+            return value
+
+    @click.command()
+    @click.argument("myarg", **argument_kwargs, cls=CustomArgument)
+    def cmd(myarg):
+        click.echo("ok")
+
+    result = runner.invoke(cmd, pass_argv)
+    assert not result.exception
+    assert result.exit_code == 0

tests/test_options.py

@@ -1012,6 +1012,42 @@ def cmd(testoption):
     assert "you wont see me" not in result.output
 
 
+@pytest.mark.parametrize(
+    ("param_decl", "option_kwargs", "pass_argv"),
+    (
+        # there is a large potential parameter space to explore here
+        # this is just a very small sample of it
+        ("--opt", {}, []),
+        ("--opt", {"multiple": True}, []),
+        ("--opt", {"is_flag": True}, []),
+        ("--opt/--no-opt", {"is_flag": True, "default": None}, []),
+        ("--req", {"is_flag": True, "required": True}, ["--req"]),
+    ),
+)
+def test_option_custom_class_can_override_type_cast_value_and_never_sees_unset(
+    runner, param_decl, option_kwargs, pass_argv
+):
+    """
+    Test that overriding type_cast_value is supported
+
+    In particular, the option is never passed an UNSET sentinel value.
+    """
+
+    class CustomOption(click.Option):
+        def type_cast_value(self, ctx, value):
+            assert value is not UNSET
+            return value
+
+    @click.command()
+    @click.option("myparam", param_decl, **option_kwargs, cls=CustomOption)
+    def cmd(myparam):
+        click.echo("ok")
+
+    result = runner.invoke(cmd, pass_argv)
+    assert not result.exception
+    assert result.exit_code == 0
+
+
 def test_option_custom_class_reusable(runner):
     """Ensure we can reuse a custom class option. See Issue #926"""