✨ Upgrade autocompletion functionality for compatibility with shell_complete

docs/tutorial/options-autocompletion.md

@@ -214,7 +214,7 @@ Hello Sebastian
 
 And the same way as before, we want to provide **completion** for those names. But we don't want to provide the **same names** for completion if they were already given in previous parameters.
 
-For that, we will access and use the "Context". When you create a **Typer** application it uses Click underneath. And every Click application has a special object called a <a href="https://click.palletsprojects.com/en/7.x/commands/#nested-handling-and-contexts" class="external-link" target="_blank">"Context"</a> that is normally hidden.
+For that, we will access and use the "Context". When you create a **Typer** application it uses Click underneath. And every Click application has a special object called a <a href="https://click.palletsprojects.com/en/stable/commands/#nested-handling-and-contexts" class="external-link" target="_blank">"Context"</a> that is normally hidden.
 
 But you can access the context by declaring a function parameter of type `typer.Context`.
 
@@ -264,6 +264,36 @@ It's quite possible that if there's only one option left, your shell will comple
 
 ///
 
+## Reusing generic completer functions
+
+You may want to reuse completer functions across CLI applications or within the same CLI application. If you need to filter out previously supplied parameters the completer function will first have to determine which parameter it is being asked to complete.
+
+We can declare a parameter of type <a href="https://click.palletsprojects.com/en/stable/api/#click.Parameter" class="external-link" target="_blank">click.Parameter</a> along with the `click.Context` in our completer function to determine this. For example, lets revisit our above context example where we filter out duplicates but add a second greeter argument that reuses the same completer function:
+
+{* docs_src/options_autocompletion/tutorial010_an.py hl[15:16] *}
+
+/// tip
+
+You may also return <a href="https://click.palletsprojects.com/en/stable/api/#click.shell_completion.CompletionItem" class="external-link" target="_blank">click.shell_completion.CompletionItem</a> objects from completer functions instead of 2-tuples.
+
+///
+
+
+Check it:
+
+<div class="termy">
+
+```console
+$ typer ./main.py run --name Sebastian --greeter Camila --greeter [TAB][TAB]
+
+// Our function returns Sebastian too because it is completing greeter
+Carlos     -- The writer of scripts.
+Sebastian  -- The type hints guy.
+```
+
+</div>
+
+
 ## Getting the raw *CLI parameters*
 
 You can also get the raw *CLI parameters*, just a `list` of `str` with everything passed in the command line before the incomplete value.
@@ -381,6 +411,7 @@ You can declare function parameters of these types:
 
 * `str`: for the incomplete value.
 * `typer.Context`: for the current context.
+* `click.Parameter`: for the CLI parameter being completed.
 * `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**" ✨

docs_src/options_autocompletion/tutorial009.py

@@ -1,6 +1,7 @@
 from typing import List
 
 import typer
+from click.core import Parameter
 from rich.console import Console
 
 valid_completion_items = [
@@ -12,9 +13,8 @@
 err_console = Console(stderr=True)
 
 
-def complete_name(ctx: typer.Context, args: List[str], incomplete: str):
-    err_console.print(f"{args}")
-    names = ctx.params.get("name") or []
+def complete_name(ctx: typer.Context, param: Parameter, incomplete: str):
+    names = ctx.params.get(param.name) or []
     for name, help_text in valid_completion_items:
         if name.startswith(incomplete) and name not in names:
             yield (name, help_text)

docs_src/options_autocompletion/tutorial009_an.py

@@ -1,6 +1,7 @@
 from typing import List
 
 import typer
+from click.core import Parameter
 from rich.console import Console
 from typing_extensions import Annotated
 
@@ -13,9 +14,8 @@
 err_console = Console(stderr=True)
 
 
-def complete_name(ctx: typer.Context, args: List[str], incomplete: str):
-    err_console.print(f"{args}")
-    names = ctx.params.get("name") or []
+def complete_name(ctx: typer.Context, param: Parameter, incomplete: str):
+    names = ctx.params.get(param.name) or []
     for name, help_text in valid_completion_items:
         if name.startswith(incomplete) and name not in names:
             yield (name, help_text)

docs_src/options_autocompletion/tutorial010.py

@@ -0,0 +1,38 @@
+from typing import List
+
+import click
+import typer
+from click.shell_completion import CompletionItem
+
+valid_completion_items = [
+    ("Camila", "The reader of books."),
+    ("Carlos", "The writer of scripts."),
+    ("Sebastian", "The type hints guy."),
+]
+
+
+def complete_name(ctx: typer.Context, param: click.Parameter, incomplete: str):
+    names = (ctx.params.get(param.name) if param.name else []) or []
+    for name, help_text in valid_completion_items:
+        if name.startswith(incomplete) and name not in names:
+            yield CompletionItem(name, help=help_text)
+
+
+app = typer.Typer()
+
+
+@app.command()
+def main(
+    name: List[str] = typer.Option(
+        ["World"], help="The name to say hi to.", autocompletion=complete_name
+    ),
+    greeter: List[str] = typer.Option(
+        None, help="Who are the greeters?.", autocompletion=complete_name
+    ),
+):
+    for n in name:
+        print(f"Hello {n}, from {' and '.join(greeter or [])}")
+
+
+if __name__ == "__main__":
+    app()

docs_src/options_autocompletion/tutorial010_an.py

@@ -0,0 +1,41 @@
+from typing import List
+
+import click
+import typer
+from click.shell_completion import CompletionItem
+from typing_extensions import Annotated
+
+valid_completion_items = [
+    ("Camila", "The reader of books."),
+    ("Carlos", "The writer of scripts."),
+    ("Sebastian", "The type hints guy."),
+]
+
+
+def complete_name(ctx: typer.Context, param: click.Parameter, incomplete: str):
+    names = (ctx.params.get(param.name) if param.name else []) or []
+    for name, help_text in valid_completion_items:
+        if name.startswith(incomplete) and name not in names:
+            yield CompletionItem(name, help=help_text)
+
+
+app = typer.Typer()
+
+
+@app.command()
+def main(
+    name: Annotated[
+        List[str],
+        typer.Option(help="The name to say hi to.", autocompletion=complete_name),
+    ] = ["World"],
+    greeter: Annotated[
+        List[str],
+        typer.Option(help="Who are the greeters?.", autocompletion=complete_name),
+    ] = [],
+):
+    for n in name:
+        print(f"Hello {n}, from {' and '.join(greeter)}")
+
+
+if __name__ == "__main__":
+    app()

pyproject.toml

@@ -181,6 +181,7 @@ ignore = [
 "docs_src/options_autocompletion/tutorial007_an.py" = ["B006"]
 "docs_src/options_autocompletion/tutorial008_an.py" = ["B006"]
 "docs_src/options_autocompletion/tutorial009_an.py" = ["B006"]
+"docs_src/options_autocompletion/tutorial010_an.py" = ["B006"]
 "docs_src/parameter_types/enum/tutorial003_an.py" = ["B006"]
 # Loop control variable `value` not used within loop body
 "docs_src/progressbar/tutorial001.py" = ["B007"]

tests/assets/completion_no_types.py

@@ -3,9 +3,10 @@
 app = typer.Typer()
 
 
-def complete(ctx, args, incomplete):
+def complete(ctx, args, param, incomplete):
     typer.echo(f"info name is: {ctx.info_name}", err=True)
     typer.echo(f"args is: {args}", err=True)
+    typer.echo(f"param is: {param.name}", err=True)
     typer.echo(f"incomplete is: {incomplete}", err=True)
     return [
         ("Camila", "The reader of books."),

tests/assets/completion_no_types_order.py

@@ -3,9 +3,10 @@
 app = typer.Typer()
 
 
-def complete(args, incomplete, ctx):
+def complete(args, incomplete, ctx, param):
     typer.echo(f"info name is: {ctx.info_name}", err=True)
     typer.echo(f"args is: {args}", err=True)
+    typer.echo(f"param is: {param.name}", err=True)
     typer.echo(f"incomplete is: {incomplete}", err=True)
     return [
         ("Camila", "The reader of books."),

tests/test_others.py

@@ -176,7 +176,8 @@ def test_completion_untyped_parameters():
         },
     )
     assert "info name is: completion_no_types.py" in result.stderr
-    assert "args is: []" in result.stderr
+    assert "args is: ['--name', 'Sebastian', '--name']" in result.stderr
+    assert "param is: name" in result.stderr
     assert "incomplete is: Ca" in result.stderr
     assert '"Camila":"The reader of books."' in result.stdout
     assert '"Carlos":"The writer of scripts."' in result.stdout
@@ -202,7 +203,8 @@ def test_completion_untyped_parameters_different_order_correct_names():
         },
     )
     assert "info name is: completion_no_types_order.py" in result.stderr
-    assert "args is: []" in result.stderr
+    assert "args is: ['--name', 'Sebastian', '--name']" in result.stderr
+    assert "param is: name" in result.stderr
     assert "incomplete is: Ca" in result.stderr
     assert '"Camila":"The reader of books."' in result.stdout
     assert '"Carlos":"The writer of scripts."' in result.stdout

tests/test_tutorial/test_options_autocompletion/test_tutorial008.py

@@ -23,7 +23,7 @@ def test_completion():
     assert '"Camila":"The reader of books."' in result.stdout
     assert '"Carlos":"The writer of scripts."' in result.stdout
     assert '"Sebastian":"The type hints guy."' in result.stdout
-    assert "[]" in result.stderr
+    assert "--name" in result.stderr
 
 
 def test_1():

tests/test_tutorial/test_options_autocompletion/test_tutorial008_an.py

@@ -23,7 +23,7 @@ def test_completion():
     assert '"Camila":"The reader of books."' in result.stdout
     assert '"Carlos":"The writer of scripts."' in result.stdout
     assert '"Sebastian":"The type hints guy."' in result.stdout
-    assert "[]" in result.stderr
+    assert "--name" in result.stderr
 
 
 def test_1():

tests/test_tutorial/test_options_autocompletion/test_tutorial009.py

@@ -23,7 +23,6 @@ def test_completion():
     assert '"Camila":"The reader of books."' in result.stdout
     assert '"Carlos":"The writer of scripts."' in result.stdout
     assert '"Sebastian":"The type hints guy."' not in result.stdout
-    assert "[]" in result.stderr
 
 
 def test_1():

tests/test_tutorial/test_options_autocompletion/test_tutorial009_an.py

@@ -23,7 +23,6 @@ def test_completion():
     assert '"Camila":"The reader of books."' in result.stdout
     assert '"Carlos":"The writer of scripts."' in result.stdout
     assert '"Sebastian":"The type hints guy."' not in result.stdout
-    assert "[]" in result.stderr
 
 
 def test_1():

tests/test_tutorial/test_options_autocompletion/test_tutorial010.py

@@ -0,0 +1,90 @@
+import os
+import subprocess
+import sys
+
+from typer.testing import CliRunner
+
+from docs_src.options_autocompletion import tutorial010 as mod
+
+runner = CliRunner()
+
+
+def test_completion():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, " "],
+        capture_output=True,
+        encoding="utf-8",
+        env={
+            **os.environ,
+            "_TUTORIAL010.PY_COMPLETE": "complete_zsh",
+            "_TYPER_COMPLETE_ARGS": "tutorial010.py --name Sebastian --name ",
+        },
+    )
+    assert '"Camila":"The reader of books."' in result.stdout
+    assert '"Carlos":"The writer of scripts."' in result.stdout
+    assert '"Sebastian":"The type hints guy."' not in result.stdout
+
+
+def test_completion_greeter1():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, " "],
+        capture_output=True,
+        encoding="utf-8",
+        env={
+            **os.environ,
+            "_TUTORIAL010.PY_COMPLETE": "complete_zsh",
+            "_TYPER_COMPLETE_ARGS": "tutorial010.py --name Sebastian --greeter Ca",
+        },
+    )
+    assert '"Camila":"The reader of books."' in result.stdout
+    assert '"Carlos":"The writer of scripts."' in result.stdout
+    assert '"Sebastian":"The type hints guy."' not in result.stdout
+
+
+def test_completion_greeter2():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, " "],
+        capture_output=True,
+        encoding="utf-8",
+        env={
+            **os.environ,
+            "_TUTORIAL010.PY_COMPLETE": "complete_zsh",
+            "_TYPER_COMPLETE_ARGS": "tutorial010.py --name Sebastian --greeter Carlos --greeter ",
+        },
+    )
+    assert '"Camila":"The reader of books."' in result.stdout
+    assert '"Carlos":"The writer of scripts."' not in result.stdout
+    assert '"Sebastian":"The type hints guy."' in result.stdout
+
+
+def test_1():
+    result = runner.invoke(mod.app, ["--name", "Camila", "--name", "Sebastian"])
+    assert result.exit_code == 0
+    assert "Hello Camila" in result.output
+    assert "Hello Sebastian" in result.output
+
+
+def test_2():
+    result = runner.invoke(
+        mod.app, ["--name", "Camila", "--name", "Sebastian", "--greeter", "Carlos"]
+    )
+    assert result.exit_code == 0
+    assert "Hello Camila, from Carlos" in result.output
+    assert "Hello Sebastian, from Carlos" in result.output
+
+
+def test_3():
+    result = runner.invoke(
+        mod.app, ["--name", "Camila", "--greeter", "Carlos", "--greeter", "Sebastian"]
+    )
+    assert result.exit_code == 0
+    assert "Hello Camila, from Carlos and Sebastian" in result.output
+
+
+def test_script():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, "--help"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout