🗑️ Deprecate shell_complete and continue to use autocompletion for CLI parameters (#974)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Sebastián Ramírez <[email protected]>

Author: 3 people

docs/tutorial/options-autocompletion.md

@@ -384,3 +384,13 @@ You can declare function parameters of these types:
 * `List[str]`: for the raw *CLI parameters*.
 
 It doesn't matter how you name them, in which order, or which ones of the 3 options you declare. It will all "**just work**" ✨
+
+## Comparison to Click functionality
+
+Note that Click 7 had a similar [`autocompletion` function](https://click.palletsprojects.com/en/7.x/bashcomplete/), but it worked slightly differently.
+
+It required the callback function to take exactly the 3 arguments `ctx`, `args` and `incomplete` in that exact order, instead of matching them dynamically based on types, as Typer does.
+
+Since Click 8, this functionality has been replaced by [`shell_complete`](https://click.palletsprojects.com/en/8.1.x/api/#click.ParamType.shell_complete), which still depends on the exact order of arguments for the callback function.
+
+However, Typer continues to use the `autocompletion` functionality as described on this page.

pyproject.toml

@@ -115,8 +115,6 @@ xfail_strict = true
 junit_family = "xunit2"
 filterwarnings = [
     "error",
-    # TODO: until I refactor completion to use the new shell_complete
-    "ignore:'autocompletion' is renamed to 'shell_complete'. The old name is deprecated and will be removed in Click 8.1. See the docs about 'Parameter' for information about new behavior.:DeprecationWarning:typer",
     # For pytest-xdist
     'ignore::DeprecationWarning:xdist',
 ]

tests/assets/compat_click7_8.py

@@ -1,28 +1,18 @@
-from typing import List
-
-import click
 import typer
 
 app = typer.Typer()
 
 
-def shell_complete(
-    ctx: click.Context, param: click.Parameter, incomplete: str
-) -> List[str]:
-    return ["Jonny"]
-
-
 @app.command(context_settings={"auto_envvar_prefix": "TEST"})
 def main(
     name: str = typer.Option("John", hidden=True),
     lastname: str = typer.Option("Doe", "/lastname", show_default="Mr. Doe"),
     age: int = typer.Option(lambda: 42, show_default=True),
-    nickname: str = typer.Option("", shell_complete=shell_complete),
 ):
     """
     Say hello.
     """
-    print(f"Hello {name} {lastname}, it seems you have {age}, {nickname}")
+    print(f"Hello {name} {lastname}, it seems you have {age}")
 
 
 if __name__ == "__main__":

tests/test_compat/test_option_get_help.py

@@ -1,7 +1,3 @@
-import os
-import subprocess
-import sys
-
 import typer.core
 from typer.testing import CliRunner
 
@@ -37,17 +33,3 @@ def test_coverage_call():
     result = runner.invoke(mod.app)
     assert result.exit_code == 0
     assert "Hello John Doe, it seems you have 42" in result.output
-
-
-def test_completion():
-    result = subprocess.run(
-        [sys.executable, "-m", "coverage", "run", mod.__file__, " "],
-        capture_output=True,
-        encoding="utf-8",
-        env={
-            **os.environ,
-            "_COMPAT_CLICK7_8.PY_COMPLETE": "complete_zsh",
-            "_TYPER_COMPLETE_ARGS": "compat_click7_8.py --nickname ",
-        },
-    )
-    assert "Jonny" in result.stdout

typer/core.py

@@ -62,17 +62,18 @@ def _typer_param_setup_autocompletion_compat(
         Callable[[click.Context, List[str], str], List[Union[Tuple[str, str], str]]]
     ] = None,
 ) -> None:
-    if autocompletion is not None and self._custom_shell_complete is None:
+    if self._custom_shell_complete is not None:
         import warnings
 
         warnings.warn(
-            "'autocompletion' is renamed to 'shell_complete'. The old name is"
-            " deprecated and will be removed in Click 8.1. See the docs about"
-            " 'Parameter' for information about new behavior.",
+            "In Typer, only the parameter 'autocompletion' is supported. "
+            "The support for 'shell_complete' is deprecated and will be removed in upcoming versions. ",
             DeprecationWarning,
             stacklevel=2,
         )
 
+    if autocompletion is not None:
+
         def compat_autocompletion(
             ctx: click.Context, param: click.core.Parameter, incomplete: str
         ) -> List["click.shell_completion.CompletionItem"]:
@@ -267,6 +268,8 @@ def __init__(
         expose_value: bool = True,
         is_eager: bool = False,
         envvar: Optional[Union[str, List[str]]] = None,
+        # Note that shell_complete is not fully supported and will be removed in future versions
+        # TODO: Remove shell_complete in a future version (after 0.16.0)
         shell_complete: Optional[
             Callable[
                 [click.Context, click.Parameter, str],
@@ -406,6 +409,8 @@ def __init__(
         expose_value: bool = True,
         is_eager: bool = False,
         envvar: Optional[Union[str, List[str]]] = None,
+        # Note that shell_complete is not fully supported and will be removed in future versions
+        # TODO: Remove shell_complete in a future version (after 0.16.0)
         shell_complete: Optional[
             Callable[
                 [click.Context, click.Parameter, str],

typer/models.py

@@ -173,6 +173,8 @@ def __init__(
         expose_value: bool = True,
         is_eager: bool = False,
         envvar: Optional[Union[str, List[str]]] = None,
+        # Note that shell_complete is not fully supported and will be removed in future versions
+        # TODO: Remove shell_complete in a future version (after 0.16.0)
         shell_complete: Optional[
             Callable[
                 [click.Context, click.Parameter, str],
@@ -281,6 +283,8 @@ def __init__(
         expose_value: bool = True,
         is_eager: bool = False,
         envvar: Optional[Union[str, List[str]]] = None,
+        # Note that shell_complete is not fully supported and will be removed in future versions
+        # TODO: Remove shell_complete in a future version (after 0.16.0)
         shell_complete: Optional[
             Callable[
                 [click.Context, click.Parameter, str],
@@ -408,6 +412,8 @@ def __init__(
         expose_value: bool = True,
         is_eager: bool = False,
         envvar: Optional[Union[str, List[str]]] = None,
+        # Note that shell_complete is not fully supported and will be removed in future versions
+        # TODO: Remove shell_complete in a future version (after 0.16.0)
         shell_complete: Optional[
             Callable[
                 [click.Context, click.Parameter, str],

typer/params.py

@@ -19,6 +19,8 @@ def Option(
     expose_value: bool = True,
     is_eager: bool = False,
     envvar: Optional[Union[str, List[str]]] = None,
+    # Note that shell_complete is not fully supported and will be removed in future versions
+    # TODO: Remove shell_complete in a future version (after 0.16.0)
     shell_complete: Optional[
         Callable[
             [click.Context, click.Parameter, str],
@@ -83,6 +85,8 @@ def Option(
     expose_value: bool = True,
     is_eager: bool = False,
     envvar: Optional[Union[str, List[str]]] = None,
+    # Note that shell_complete is not fully supported and will be removed in future versions
+    # TODO: Remove shell_complete in a future version (after 0.16.0)
     shell_complete: Optional[
         Callable[
             [click.Context, click.Parameter, str],
@@ -145,6 +149,8 @@ def Option(
     expose_value: bool = True,
     is_eager: bool = False,
     envvar: Optional[Union[str, List[str]]] = None,
+    # Note that shell_complete is not fully supported and will be removed in future versions
+    # TODO: Remove shell_complete in a future version (after 0.16.0)
     shell_complete: Optional[
         Callable[
             [click.Context, click.Parameter, str],
@@ -265,6 +271,8 @@ def Argument(
     expose_value: bool = True,
     is_eager: bool = False,
     envvar: Optional[Union[str, List[str]]] = None,
+    # Note that shell_complete is not fully supported and will be removed in future versions
+    # TODO: Remove shell_complete in a future version (after 0.16.0)
     shell_complete: Optional[
         Callable[
             [click.Context, click.Parameter, str],
@@ -320,6 +328,8 @@ def Argument(
     expose_value: bool = True,
     is_eager: bool = False,
     envvar: Optional[Union[str, List[str]]] = None,
+    # Note that shell_complete is not fully supported and will be removed in future versions
+    # TODO: Remove shell_complete in a future version (after 0.16.0)
     shell_complete: Optional[
         Callable[
             [click.Context, click.Parameter, str],
@@ -373,6 +383,8 @@ def Argument(
     expose_value: bool = True,
     is_eager: bool = False,
     envvar: Optional[Union[str, List[str]]] = None,
+    # Note that shell_complete is not fully supported and will be removed in future versions
+    # TODO: Remove shell_complete in a future version (after 0.16.0)
     shell_complete: Optional[
         Callable[
             [click.Context, click.Parameter, str],