CLI Option autocompletion¶
As you have seen, apps built with Typer have completion in your shell that works when you create a Python package or using the typer
command.
It normally completes CLI options, CLI arguments, and subcommands (that you will learn about later).
But you can also provide auto completion for the values of CLI options and CLI arguments. We will learn about that here.
Review completion¶
Before checking how to provide custom completions, let's check again how it works.
After installing completion for your own Python package (or using the typer
command), when you use your CLI program and start adding a CLI option with --
an then hit TAB, your shell will show you the available CLI options (the same for CLI arguments, etc).
To check it quickly without creating a new Python package, use the typer
command.
Then let's create small example program:
import typer
from typing_extensions import Annotated
app = typer.Typer()
@app.command()
def main(name: Annotated[str, typer.Option(help="The name to say hi to.")] = "World"):
print(f"Hello {name}")
if __name__ == "__main__":
app()
Tip
Prefer to use the Annotated
version if possible.
import typer
app = typer.Typer()
@app.command()
def main(name: str = typer.Option("World", help="The name to say hi to.")):
print(f"Hello {name}")
if __name__ == "__main__":
app()
And let's try it with the typer
command to get completion:
// Hit the TAB key in your keyboard below where you see the: [TAB]
$ typer ./main.py [TAB][TAB]
// Depending on your terminal/shell you will get some completion like this ✨
run -- Run the provided Typer app.
utils -- Extra utility commands for Typer apps.
// Then try with "run" and --
$ typer ./main.py run --[TAB][TAB]
// You will get completion for --name, depending on your terminal it will look something like this
--name -- The name to say hi to.
// And you can run it as if it was with Python directly
$ typer ./main.py run --name Camila
Hello Camila
Custom completion for values¶
Right now we get completion for the CLI option names, but not for the values.
We can provide completion for the values creating an autocompletion
function, similar to the callback
functions from CLI Option Callback and Context:
import typer
from typing_extensions import Annotated
def complete_name():
return ["Camila", "Carlos", "Sebastian"]
app = typer.Typer()
@app.command()
def main(
name: Annotated[
str, typer.Option(help="The name to say hi to.", autocompletion=complete_name)
] = "World",
):
print(f"Hello {name}")
if __name__ == "__main__":
app()
Tip
Prefer to use the Annotated
version if possible.
import typer
def complete_name():
return ["Camila", "Carlos", "Sebastian"]
app = typer.Typer()
@app.command()
def main(
name: str = typer.Option(
"World", help="The name to say hi to.", autocompletion=complete_name
),
):
print(f"Hello {name}")
if __name__ == "__main__":
app()
We return a list
of strings from the complete_name()
function.
And then we get those values when using completion:
$ typer ./main.py run --name [TAB][TAB]
// We get the values returned from the function 🎉
Camila Carlos Sebastian
We got the basics working. Now let's improve it.
Check the incomplete value¶
Right now, we always return those values, even if users start typing Sebast
and then hit TAB, they will also get the completion for Camila
and Carlos
(depending on the shell), while we should only get completion for Sebastian
.
But we can fix that so that it always works correctly.
Modify the complete_name()
function to receive a parameter of type str
, it will contain the incomplete value.
Then we can check and return only the values that start with the incomplete value from the command line:
import typer
from typing_extensions import Annotated
valid_names = ["Camila", "Carlos", "Sebastian"]
def complete_name(incomplete: str):
completion = []
for name in valid_names:
if name.startswith(incomplete):
completion.append(name)
return completion
app = typer.Typer()
@app.command()
def main(
name: Annotated[
str, typer.Option(help="The name to say hi to.", autocompletion=complete_name)
] = "World",
):
print(f"Hello {name}")
if __name__ == "__main__":
app()
Tip
Prefer to use the Annotated
version if possible.
import typer
valid_names = ["Camila", "Carlos", "Sebastian"]
def complete_name(incomplete: str):
completion = []
for name in valid_names:
if name.startswith(incomplete):
completion.append(name)
return completion
app = typer.Typer()
@app.command()
def main(
name: str = typer.Option(
"World", help="The name to say hi to.", autocompletion=complete_name
),
):
print(f"Hello {name}")
if __name__ == "__main__":
app()
Now let's try it:
$ typer ./main.py run --name Ca[TAB][TAB]
// We get the values returned from the function that start with Ca 🎉
Camila Carlos
Now we are only returning the valid values, that start with Ca
, we are no longer returning Sebastian
as a completion option.
Tip
You have to declare the incomplete value of type str
and that's what you will receive in the function.
No matter if the actual value will be an int
, or something else, when doing completion, you will only get a str
as the incomplete value.
And the same way, you can only return str
, not int
, etc.
Add help to completions¶
Right now we are returning a list
of str
.
But some shells (Zsh, Fish, PowerShell) are capable of showing extra help text for completion.
We can provide that extra help text so that those shells can show it.
In the complete_name()
function, instead of providing one str
per completion element, we provide a tuple
with 2 items. The first item is the actual completion string, and the second item is the help text.
So, in the end, we return a list
of tuples
of str
:
import typer
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(incomplete: str):
completion = []
for name, help_text in valid_completion_items:
if name.startswith(incomplete):
completion_item = (name, help_text)
completion.append(completion_item)
return completion
app = typer.Typer()
@app.command()
def main(
name: Annotated[
str, typer.Option(help="The name to say hi to.", autocompletion=complete_name)
] = "World",
):
print(f"Hello {name}")
if __name__ == "__main__":
app()
Tip
Prefer to use the Annotated
version if possible.
import typer
valid_completion_items = [
("Camila", "The reader of books."),
("Carlos", "The writer of scripts."),
("Sebastian", "The type hints guy."),
]
def complete_name(incomplete: str):
completion = []
for name, help_text in valid_completion_items:
if name.startswith(incomplete):
completion_item = (name, help_text)
completion.append(completion_item)
return completion
app = typer.Typer()
@app.command()
def main(
name: str = typer.Option(
"World", help="The name to say hi to.", autocompletion=complete_name
),
):
print(f"Hello {name}")
if __name__ == "__main__":
app()
Tip
If you want to have help text for each item, make sure each item in the list is a tuple
. Not a list
.
Click checks specifically for a tuple
when extracting the help text.
So in the end, the return will be a list
(or other iterable) of tuples
of 2 str
.
Info
The help text will be visible in Zsh, Fish, and PowerShell.
Bash doesn't support showing the help text, but completion will still work the same.
If you have a shell like Zsh, it would look like:
$ typer ./main.py run --name [TAB][TAB]
// We get the completion items with their help text 🎉
Camila -- The reader of books.
Carlos -- The writer of scripts.
Sebastian -- The type hints guy.
Simplify with yield
¶
Instead of creating and returning a list with values (str
or tuple
), we can use yield
with each value that we want in the completion.
That way our function will be a generator that Typer (actually Click) can iterate:
import typer
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(incomplete: str):
for name, help_text in valid_completion_items:
if name.startswith(incomplete):
yield (name, help_text)
app = typer.Typer()
@app.command()
def main(
name: Annotated[
str, typer.Option(help="The name to say hi to.", autocompletion=complete_name)
] = "World",
):
print(f"Hello {name}")
if __name__ == "__main__":
app()
Tip
Prefer to use the Annotated
version if possible.
import typer
valid_completion_items = [
("Camila", "The reader of books."),
("Carlos", "The writer of scripts."),
("Sebastian", "The type hints guy."),
]
def complete_name(incomplete: str):
for name, help_text in valid_completion_items:
if name.startswith(incomplete):
yield (name, help_text)
app = typer.Typer()
@app.command()
def main(
name: str = typer.Option(
"World", help="The name to say hi to.", autocompletion=complete_name
),
):
print(f"Hello {name}")
if __name__ == "__main__":
app()
That simplifies our code a bit and works the same.
Tip
If all the yield
part seems complex for you, don't worry, you can just use the version with the list
above.
In the end, that's just to save us a couple of lines of code.
Info
The function can use yield
, so it doesn't have to return strictly a list
, it just has to be iterable.
But each of the elements for completion has to be a str
or a tuple
(when containing a help text).
Access other CLI parameters with the Context¶
Let's say that now we want to modify the program to be able to "say hi" to multiple people at the same time.
So, we will allow multiple --name
CLI options.
Tip
You will learn more about CLI parameters with multiple values later in the tutorial.
So, for now, take this as a sneak peek 😉.
For this we use a List
of str
:
from typing import List
import typer
from typing_extensions import Annotated
app = typer.Typer()
@app.command()
def main(
name: Annotated[List[str], typer.Option(help="The name to say hi to.")] = ["World"],
):
for each_name in name:
print(f"Hello {each_name}")
if __name__ == "__main__":
app()
Tip
Prefer to use the Annotated
version if possible.
from typing import List
import typer
app = typer.Typer()
@app.command()
def main(name: List[str] = typer.Option(["World"], help="The name to say hi to.")):
for each_name in name:
print(f"Hello {each_name}")
if __name__ == "__main__":
app()
And then we can use it like:
$ typer ./main.py run --name Camila --name Sebastian
Hello Camila
Hello Sebastian
Getting completion for multiple values¶
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 "Context" that is normally hidden.
But you can access the context by declaring a function parameter of type typer.Context
.
And from that context you can get the current values for each parameter.
from typing import List
import typer
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, incomplete: str):
names = ctx.params.get("name") or []
for name, help_text in valid_completion_items:
if name.startswith(incomplete) and name not in names:
yield (name, 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"],
):
for n in name:
print(f"Hello {n}")
if __name__ == "__main__":
app()
Tip
Prefer to use the Annotated
version if possible.
from typing import List
import typer
valid_completion_items = [
("Camila", "The reader of books."),
("Carlos", "The writer of scripts."),
("Sebastian", "The type hints guy."),
]
def complete_name(ctx: typer.Context, incomplete: str):
names = ctx.params.get("name") or []
for name, help_text in valid_completion_items:
if name.startswith(incomplete) and name not in names:
yield (name, 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
),
):
for n in name:
print(f"Hello {n}")
if __name__ == "__main__":
app()
We are getting the names
already provided with --name
in the command line before this completion was triggered.
If there's no --name
in the command line, it will be None
, so we use or []
to make sure we have a list
(even if empty) to check its contents later.
Then, when we have a completion candidate, we check if each name
was already provided with --name
by checking if it's in that list of names
with name not in names
.
And then we yield
each item that has not been used yet.
Check it:
$ typer ./main.py run --name [TAB][TAB]
// The first time we trigger completion, we get all the names
Camila -- The reader of books.
Carlos -- The writer of scripts.
Sebastian -- The type hints guy.
// Add a name and trigger completion again
$ typer ./main.py run --name Sebastian --name Ca[TAB][TAB]
// Now we get completion only for the names we haven't used 🎉
Camila -- The reader of books.
Carlos -- The writer of scripts.
// And if we add another of the available names:
$ typer ./main.py run --name Sebastian --name Camila --name [TAB][TAB]
// We get completion for the only available one
Carlos -- The writer of scripts.
Tip
It's quite possible that if there's only one option left, your shell will complete it right away instead of showing the option with the help text, to save you more typing.
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.
For example, something like ["typer", "main.py", "run", "--name"]
.
Tip
This would be for advanced scenarios, in most use cases you would be better off using the context.
But it's still possible if you need it.
As a simple example, let's show it on the screen before completion.
Because completion is based on the output printed by your program (handled internally by Typer), during completion we can't just print something else as we normally do.
Printing to "standard error"¶
Tip
If you need a refresher about what is "standard output" and "standard error" check the section in Printing and Colors: "Standard Output" and "Standard Error".
The completion system only reads from "standard output", so, printing to "standard error" won't break completion. 🚀
You can print to "standard error" with a Rich Console(stderr=True)
.
Using stderr=True
tells Rich that the output should be shown in "standard error".
from typing import List
import typer
from rich.console import Console
from typing_extensions import Annotated
valid_completion_items = [
("Camila", "The reader of books."),
("Carlos", "The writer of scripts."),
("Sebastian", "The type hints guy."),
]
err_console = Console(stderr=True)
def complete_name(args: List[str], incomplete: str):
err_console.print(f"{args}")
for name, help_text in valid_completion_items:
if name.startswith(incomplete):
yield (name, 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"],
):
for n in name:
print(f"Hello {n}")
if __name__ == "__main__":
app()
Tip
Prefer to use the Annotated
version if possible.
from typing import List
import typer
from rich.console import Console
valid_completion_items = [
("Camila", "The reader of books."),
("Carlos", "The writer of scripts."),
("Sebastian", "The type hints guy."),
]
err_console = Console(stderr=True)
def complete_name(args: List[str], incomplete: str):
err_console.print(f"{args}")
for name, help_text in valid_completion_items:
if name.startswith(incomplete):
yield (name, 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
),
):
for n in name:
print(f"Hello {n}")
if __name__ == "__main__":
app()
Info
If you can't install and use Rich, you can also use print(lastname, file=sys.stderr)
or typer.echo("some text", err=True)
instead.
We get all the CLI parameters as a raw list
of str
by declaring a parameter with type List[str]
, here it's named args
.
Tip
Here we name the list of all the raw CLI parameters args
because that's the convention with Click.
But it doesn't contain only CLI arguments, it has everything, including CLI options and values, as a raw list
of str
.
And then we just print it to "standard error".
$ typer ./main.py run --name [TAB][TAB]
// First we see the raw CLI parameters
['./main.py', 'run', '--name']
// And then we see the actual completion
Camila -- The reader of books.
Carlos -- The writer of scripts.
Sebastian -- The type hints guy.
Tip
This is a very simple (and quite useless) example, just so you know how it works and that you can use it.
But it's probably useful only in very advanced use cases.
Getting the Context and the raw CLI parameters¶
Of course, you can declare everything if you need it, the context, the raw CLI parameters, and the incomplete str
:
from typing import List
import typer
from rich.console import Console
from typing_extensions import Annotated
valid_completion_items = [
("Camila", "The reader of books."),
("Carlos", "The writer of scripts."),
("Sebastian", "The type hints guy."),
]
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 []
for name, help_text in valid_completion_items:
if name.startswith(incomplete) and name not in names:
yield (name, 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"],
):
for n in name:
print(f"Hello {n}")
if __name__ == "__main__":
app()
Tip
Prefer to use the Annotated
version if possible.
from typing import List
import typer
from rich.console import Console
valid_completion_items = [
("Camila", "The reader of books."),
("Carlos", "The writer of scripts."),
("Sebastian", "The type hints guy."),
]
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 []
for name, help_text in valid_completion_items:
if name.startswith(incomplete) and name not in names:
yield (name, 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
),
):
for n in name:
print(f"Hello {n}")
if __name__ == "__main__":
app()
Check it:
$ typer ./main.py run --name [TAB][TAB]
// First we see the raw CLI parameters
['./main.py', 'run', '--name']
// And then we see the actual completion
Camila -- The reader of books.
Carlos -- The writer of scripts.
Sebastian -- The type hints guy.
$ typer ./main.py run --name Sebastian --name Ca[TAB][TAB]
// Again, we see the raw CLI parameters
['./main.py', 'run', '--name', 'Sebastian', '--name']
// And then we see the rest of the valid completion items
Camila -- The reader of books.
Carlos -- The writer of scripts.
Types, types everywhere¶
Typer uses the type declarations to detect what it has to provide to your autocompletion
function.
You can declare function parameters of these types:
str
: for the incomplete value.typer.Context
: for the current context.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" ✨