SubCommand Name and Help¶
When adding a Typer app to another we have seen how to set the name to use for the command.
For example to set the command to users:
app.add_typer(users.app, name="users")
Add a help text¶
We can also set the help while adding a Typer:
import typer
app = typer.Typer()
users_app = typer.Typer()
app.add_typer(users_app, name="users", help="Manage users in the app.")
@users_app.command()
def create(name: str):
print(f"Creating user: {name}")
if __name__ == "__main__":
app()
And then we get that help text for that command in the CLI program:
// Check the main help
$ python main.py --help
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
--help Show this message and exit.
Commands:
users Manage users in the app.
// Check the help for the users command
$ python main.py users --help
Usage: main.py users [OPTIONS] COMMAND [ARGS]...
Manage users in the app.
Options:
--help Show this message and exit.
Commands:
create
We can set the name and help in several places, each one taking precedence over the other, overriding the previous value.
Let's see those locations.
Tip
There are other attributes that can be set in that same way in the same places we'll see next.
But those are documented later in another section.
Inferring name and help from callback¶
Inferring a command's name and help¶
When you create a command with @app.command(), by default, it generates the name from the function name.
And by default, the help text is extracted from the function's docstring.
For example:
@app.command()
def create(item: str):
"""
Create an item.
"""
typer.echo(f"Creating item: {item}")
...will create a command create with a help text of Create an item.
Inferring name and help from @app.callback()¶
The same way, if you define a callback in a typer.Typer(), the help text is extracted from the callback function's docstring.
And if that Typer app is added to another Typer app, the default name of the command is generated from the name of the callback function.
Here's an example:
import typer
app = typer.Typer()
users_app = typer.Typer()
app.add_typer(users_app)
@users_app.callback()
def users():
"""
Manage users in the app.
"""
@users_app.command()
def create(name: str):
print(f"Creating user: {name}")
if __name__ == "__main__":
app()
Notice that now we added the sub-Typer without specifying a name nor a help.
They are now inferred from the callback function.
The command name will be the same callback function's name: users.
And the help text for that users command will be the callback function's docstring: Manage users in the app..
Check it:
// Check the main help
$ python main.py --help
// Notice the command name "users" and the help text "Manage users in the app."
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
--help Show this message and exit.
Commands:
users Manage users in the app.
// Check the help for the users command
$ python main.py users --help
// Notice the main description: "Manage users in the app."
Usage: main.py users [OPTIONS] COMMAND [ARGS]...
Manage users in the app.
Options:
--help Show this message and exit.
Commands:
create
Name and help from callback parameter in typer.Typer()¶
If you pass a callback parameter while creating a typer.Typer(callback=some_function) it will be used to infer the name and help text.
This has the lowest priority, we'll see later what has a higher priority and can override it.
Check the code:
import typer
app = typer.Typer()
def users():
"""
Manage users in the app.
"""
users_app = typer.Typer(callback=users)
app.add_typer(users_app)
@users_app.command()
def create(name: str):
print(f"Creating user: {name}")
if __name__ == "__main__":
app()
This achieves exactly the same as the previous example.
Check it:
// Check the main help
$ python main.py --help
// Notice the command name "users" and the help text "Manage users in the app."
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
--help Show this message and exit.
Commands:
users Manage users in the app.
// Check the help for the users command
$ python main.py users --help
// Notice the main description: "Manage users in the app."
Usage: main.py users [OPTIONS] COMMAND [ARGS]...
Manage users in the app.
Options:
--help Show this message and exit.
Commands:
create
Override a callback set in typer.Typer() with @app.callback()¶
The same as with normal Typer apps, if you pass a callback to typer.Typer(callback=some_function) and then override it with @app.callback(), the name and help text will be inferred from the new callback:
import typer
app = typer.Typer()
def old_callback():
"""
Old callback help.
"""
users_app = typer.Typer(callback=old_callback)
app.add_typer(users_app)
@users_app.callback()
def users():
"""
Manage users in the app.
"""
@users_app.command()
def create(name: str):
print(f"Creating user: {name}")
if __name__ == "__main__":
app()
Now the name of the command will be users instead of old-callback, and the help text will be Manage users in the app. instead of Old callback help..
Check it:
// Check the main help
$ python main.py --help
// Notice the command name "users" and the help text "Manage users in the app."
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
--help Show this message and exit.
Commands:
users Manage users in the app.
// Check the help for the users command
$ python main.py users --help
// Notice the main description: "Manage users in the app."
Usage: main.py users [OPTIONS] COMMAND [ARGS]...
Manage users in the app.
Options:
--help Show this message and exit.
Commands:
create
Infer name and help from callback in app.add_typer()¶
If you override the callback in app.add_typer() when including a sub-app, the name and help will be inferred from this callback function.
This takes precedence over inferring the name and help from a callback set in @sub_app.callback() and typer.Typer(callback=sub_app_callback).
Check the code:
import typer
app = typer.Typer()
def old_callback():
"""
Old callback help.
"""
users_app = typer.Typer(callback=old_callback)
def new_users():
"""
I have the highland! Create some users.
"""
app.add_typer(users_app, callback=new_users)
@users_app.callback()
def users():
"""
Manage users in the app.
"""
@users_app.command()
def create(name: str):
print(f"Creating user: {name}")
if __name__ == "__main__":
app()
Now the command will be new-users instead of users. And the help text will be I have the highland! Create some users. instead of the previous ones.
Check it:
// Check the main help
$ python main.py --help
// Check the command new-users and its help text
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
--help Show this message and exit.
Commands:
new-users I have the highland! Create some users.
// Now check the help for the new-users command
$ python main.py new-users --help
// Notice the help text
Usage: main.py new-users [OPTIONS] COMMAND [ARGS]...
I have the highland! Create some users.
Options:
--help Show this message and exit.
Commands:
create
Enough inferring¶
So, when inferring a name and help text, the precedence order from lowest priority to highest is:
sub_app = typer.Typer(callback=some_function)@sub_app.callback()app.add_typer(sub_app, callback=new_function)
That's for inferring the name and help text from functions.
But if you set the name and help text explicitly, that has a higher priority than these.
Set the name and help¶
Let's now see the places where you can set the command name and help text, from lowest priority to highest.
Tip
Setting the name and help text explicitly always has a higher precedence than inferring from a callback function.
Name and help in typer.Typer()¶
You could have all the callbacks and overrides we defined before, but the name and help text was inferred from the function name and docstring.
If you set it explicitly, that takes precedence over inferring.
You can set it when creating a new typer.Typer():
import typer
app = typer.Typer()
def old_callback():
"""
Old callback help.
"""
users_app = typer.Typer(callback=old_callback, name="exp-users", help="Explicit help.")
def new_users():
"""
I have the highland! Create some users.
"""
app.add_typer(users_app, callback=new_users)
@users_app.callback()
def users():
"""
Manage users in the app.
"""
@users_app.command()
def create(name: str):
print(f"Creating user: {name}")
if __name__ == "__main__":
app()
Info
The rest of the callbacks and overrides are there only to show you that they don't affect the name and help text when you set it explicitly.
We set an explicit name exp-users, and an explicit help Explicit help..
So that will take precedence now.
Check it:
// Check the main help
$ python main.py --help
// Notice the command name is exp-users and the help text is "Explicit help."
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
--help Show this message and exit.
Commands:
exp-users Explicit help.
// Check the help for the exp-users command
$ python main.py exp-users --help
// Notice the main help text
Usage: main.py exp-users [OPTIONS] COMMAND [ARGS]...
Explicit help.
Options:
--help Show this message and exit.
Commands:
create
Name and help in @app.callback()¶
Any parameter that you use when creating a typer.Typer() app can be overridden in the parameters of @app.callback().
Continuing with the previous example, we now override the values in @user_app.callback():
import typer
app = typer.Typer()
def old_callback():
"""
Old callback help.
"""
users_app = typer.Typer(callback=old_callback, name="exp-users", help="Explicit help.")
def new_users():
"""
I have the highland! Create some users.
"""
app.add_typer(users_app, callback=new_users)
@users_app.callback("call-users", help="Help from callback for users.")
def users():
"""
Manage users in the app.
"""
@users_app.command()
def create(name: str):
print(f"Creating user: {name}")
if __name__ == "__main__":
app()
And now the command name will be call-users and the help text will be Help from callback for users..
Check it:
// Check the help
$ python main.py --help
// The command name now is call-users and the help text is "Help from callback for users.".
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
--help Show this message and exit.
Commands:
call-users Help from callback for users.
// Check the call-users command help
$ python main.py call-users --help
// Notice the main help text
Usage: main.py call-users [OPTIONS] COMMAND [ARGS]...
Help from callback for users.
Options:
--help Show this message and exit.
Commands:
create
Name and help in app.add_typer()¶
And finally, with the highest priority, you can override all that by explicitly setting the name and help in app.add_typer(), just like we did on the first example above:
import typer
app = typer.Typer()
def old_callback():
"""
Old callback help.
"""
users_app = typer.Typer(callback=old_callback, name="exp-users", help="Explicit help.")
def new_users():
"""
I have the highland! Create some users.
"""
app.add_typer(
users_app,
callback=new_users,
name="cake-sith-users",
help="Unlimited powder! Eh, users.",
)
@users_app.callback("call-users", help="Help from callback for users.")
def users():
"""
Manage users in the app.
"""
@users_app.command()
def create(name: str):
print(f"Creating user: {name}")
if __name__ == "__main__":
app()
And now, with the highest priorities of them all, the command name will now be cake-sith-users and the help text will be Unlimited powder! Eh, users..
Check it:
// Check the help
$ python main.py --help
// Notice the command name cake-sith-users and the new help text "Unlimited powder! Eh, users."
Usage: main.py [OPTIONS] COMMAND [ARGS]...
Options:
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
--help Show this message and exit.
Commands:
cake-sith-users Unlimited powder! Eh, users.
// And check the help for the command cake-sith-users
$ python main.py cake-sith-users --help
// Notice the main help text
Usage: main.py cake-sith-users [OPTIONS] COMMAND [ARGS]...
Unlimited powder! Eh, users.
Options:
--help Show this message and exit.
Commands:
create
Recap¶
The precedence to generate a command's name and help, from lowest priority to highest, is:
- Implicitly inferred from
sub_app = typer.Typer(callback=some_function) - Implicitly inferred from the callback function under
@sub_app.callback() - Implicitly inferred from
app.add_typer(sub_app, callback=some_function) - Explicitly set on
sub_app = typer.Typer(name="some-name", help="Some help.") - Explicitly set on
@sub_app.callback("some-name", help="Some help.") - Explicitly set on
app.add_typer(sub_app, name="some-name", help="Some help.")
So, app.add_typer(sub_app, name="some-name", help="Some help.") always wins.