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.

SubCommand Name and Help

Add a help text¶

Inferring name and help from callback¶

Inferring a command's name and help¶

Inferring name and help from @app.callback()¶

Name and help from callback parameter in typer.Typer()¶

Override a callback set in typer.Typer() with @app.callback()¶

Infer name and help from callback in app.add_typer()¶

Enough inferring¶

Set the name and help¶

Name and help in typer.Typer()¶

Name and help in @app.callback()¶

Name and help in app.add_typer()¶

Recap¶

Inferring name and help from `@app.callback()`¶

Name and help from callback parameter in `typer.Typer()`¶

Override a callback set in `typer.Typer()` with `@app.callback()`¶

Infer name and help from callback in `app.add_typer()`¶

Name and help in `typer.Typer()`¶

Name and help in `@app.callback()`¶

Name and help in `app.add_typer()`¶