子命令名称和帮助

当将 Typer 应用程序添加到另一个应用程序时，我们已经了解了如何设置用于命令的 name。

例如，要将命令设置为 users

app.add_typer(users.app, name="users")

添加帮助文本

我们也可以在添加 Typer 时设置 help

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()

然后，我们在 CLI 程序 中获得该命令的帮助文本

// 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

我们可以在多个地方设置 name 和 help，每个地方都优先于另一个，覆盖之前的值。

让我们看看这些位置。

提示

在接下来我们将看到的相同位置，还可以以相同的方式设置其他属性。

但这些将在另一节中进行介绍。

从回调中推断名称和帮助

推断命令的名称和帮助

当使用 @app.command() 创建命令时，默认情况下，它会从函数名生成名称。

默认情况下，帮助文本是从函数的文档字符串中提取的。

例如

@app.command()
def create(item: str):
    """
    Create an item.
    """
    typer.echo(f"Creating item: {item}")

...将创建一个名为 create 的命令，其帮助文本为 Create an item。

从 @app.callback() 推断名称和帮助

同样，如果在 typer.Typer() 中定义回调，则帮助文本将从回调函数的文档字符串中提取。

如果将 Typer 应用程序添加到另一个 Typer 应用程序中，则命令的默认名称将从回调函数的名称生成。

以下是一个示例

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()

请注意，现在我们添加了子 Typer，但没有指定 name 或 help。

它们现在从回调函数中推断出来。

命令名称将与回调函数的名称相同：users。

该 users 命令的帮助文本将是回调函数的文档字符串：Manage users in the app.。

检查一下

// 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

来自 typer.Typer() 中回调参数的名称和帮助

如果您在创建 typer.Typer(callback=some_function) 时传递 callback 参数，它将用于推断名称和帮助文本。

这具有最低优先级，我们将在后面看到哪些具有更高的优先级并可以覆盖它。

检查代码

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()

这与前面的示例完全相同。

检查一下

// 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

使用 @app.callback() 覆盖 typer.Typer() 中设置的回调

与普通的 Typer 应用程序一样，如果您将 callback 传递给 typer.Typer(callback=some_function)，然后使用 @app.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()

现在命令的名称将是 users 而不是 old-callback，帮助文本将是 Manage users in the app. 而不是 Old callback help.。

检查一下

// 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

从 app.add_typer() 中的回调推断名称和帮助

如果您在包含子应用程序时在 app.add_typer() 中覆盖回调，则名称和帮助将从该回调函数中推断出来。

这优先于从 @sub_app.callback() 和 typer.Typer(callback=sub_app_callback) 中设置的回调推断名称和帮助。

检查代码

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()

现在命令将是 new-users 而不是 users。帮助文本将是 I have the highland! Create some users. 而不是之前的文本。

检查一下

// 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

推断足够了

因此，在推断名称和帮助文本时，优先级顺序从最低优先级到最高优先级为

• sub_app = typer.Typer(callback=some_function)
• @sub_app.callback()
• app.add_typer(sub_app, callback=new_function)

这是从函数推断名称和帮助文本。

但是，如果您显式设置名称和帮助文本，则它比这些具有更高的优先级。

设置名称和帮助

现在让我们看看你可以设置命令名称和帮助文本的地方，从最低优先级到最高优先级。

提示

显式设置名称和帮助文本始终优先于从回调函数推断。

在 typer.Typer() 中设置名称和帮助

你可以拥有之前定义的所有回调和覆盖，但名称和帮助文本是从函数名称和文档字符串推断出来的。

如果你显式设置它，它将优先于推断。

你可以在创建新的 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()

信息

其余的回调和覆盖只是为了向你展示，当你显式设置名称和帮助文本时，它们不会影响名称和帮助文本。

我们设置了一个显式名称 exp-users，以及一个显式帮助 Explicit help.。

所以现在它将优先于其他设置。

检查一下

// 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

在 @app.callback() 中设置名称和帮助

在创建 typer.Typer() 应用程序时使用的任何参数都可以在 @app.callback() 的参数中被覆盖。

继续前面的示例，我们现在在 @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()

现在命令名称将是 call-users，帮助文本将是 Help from callback for users.。

检查一下

// 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

在 app.add_typer() 中设置名称和帮助

最后，具有最高优先级的是，你可以通过在 app.add_typer() 中显式设置 name 和 help 来覆盖所有这些设置，就像我们在上面的第一个示例中所做的那样

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()

现在，具有最高优先级的是，命令名称将是 cake-sith-users，帮助文本将是 Unlimited powder! Eh, users.。

检查一下

// 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

回顾

生成命令名称和帮助的优先级，从最低优先级到最高优先级，是

• 从 sub_app = typer.Typer(callback=some_function) 中隐式推断
• 从 @sub_app.callback() 下的回调函数中隐式推断
• 从 app.add_typer(sub_app, callback=some_function) 中隐式推断
• 在 sub_app = typer.Typer(name="some-name", help="Some help.") 上显式设置
• 在 @sub_app.callback("some-name", help="Some help.") 上显式设置
• 在 app.add_typer(sub_app, name="some-name", help="Some help.") 上显式设置

所以，app.add_typer(sub_app, name="some-name", help="Some help.") 始终获胜。