Implement to show the message with --help

CHANGES.rst

@@ -5,6 +5,9 @@ Version 8.2.0
 
 Unreleased
 
+-   Show deprecation warning message running ``--help`` Option
+    for ``@click.option``. :issue:`2263`
+
 
 Version 8.1.3
 -------------

src/click/core.py

@@ -2450,6 +2450,13 @@ class Option(Parameter):
     :param help: the help string.
     :param hidden: hide this option from help outputs.
 
+    :param deprecated: issues a message indicating that
+                       the command is deprecated showing help
+
+    .. versionchanged:: 8.2.0
+        Show deprecation warning message running ``--help`` Option
+        for ``@click.option``. :issue:`2263`
+
     .. versionchanged:: 8.1.0
         Help text indentation is cleaned here instead of only in the
         ``@option`` decorator.
@@ -2486,6 +2493,7 @@ def __init__(
         hidden: bool = False,
         show_choices: bool = True,
         show_envvar: bool = False,
+        deprecated: bool = False,
         **attrs: t.Any,
     ) -> None:
         if help:
@@ -2504,6 +2512,9 @@ def __init__(
         else:
             prompt_text = prompt
 
+        if deprecated:
+            help = help + "(DEPRECATED)" if help is not None else "(DEPRECATED)"
+
         self.prompt = prompt_text
         self.confirmation_prompt = confirmation_prompt
         self.prompt_required = prompt_required

tests/test_options.py

@@ -33,6 +33,16 @@ def test_invalid_option(runner):
     assert "'--foo'" in message
 
 
+def test_deprecated_option(runner):
+    @click.command()
+    @click.option("--foo", default="bar", deprecated=True)
+    def cmd(foo):
+        click.echo(foo)
+
+    result = runner.invoke(cmd, ["--help"])
+    assert re.search("(DEPRECATED)", result.output)
+
+
 def test_invalid_nargs(runner):
     with pytest.raises(TypeError, match="nargs=-1"):