`typer` 命令¶

typer 命令为您的小型脚本在终端中提供 ✨ 完成 ✨ 功能。即使它们在内部没有使用 Typer。当然，如果您在脚本中使用 **Typer**，它会更好地工作。

如果您有一个使用 **Typer** 的小型自定义 Python 脚本（也许是某个项目的一部分），用于一些小型任务，并且它没有复杂/重要到足以创建一个完整的可安装 Python 包（可以用 pip 安装的东西），那么它可能最有用。

在这种情况下，您可以在终端中使用 typer 命令运行您的程序，它将为您的脚本提供完成功能。

typer 命令还具有为您的 Typer 程序生成 Markdown 文档的功能 📝。

安装¶

当您使用以下命令安装 Typer 时

pip install typer

...它包含 typer 命令。

如果您不想使用 typer 命令，可以改为安装

pip install typer-slim

您仍然可以通过将 Typer 库作为模块调用来使用它

python -m typer

安装完成¶

然后，您可以使用以下命令为 typer 命令安装完成

$ typer --install-completion

bash completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.

示例脚本¶

假设您有一个在 my_custom_script.py 中使用 Typer 的脚本

from typing import Optional

import typer

app = typer.Typer()


@app.command()
def hello(name: Optional[str] = None):
    if name:
        typer.echo(f"Hello {name}")
    else:
        typer.echo("Hello World!")


@app.command()
def bye(name: Optional[str] = None):
    if name:
        typer.echo(f"Bye {name}")
    else:
        typer.echo("Goodbye!")


if __name__ == "__main__":
    app()

为了使其正常工作，您还需要安装 Typer

$ python -m pip install typer
---> 100%
Successfully installed typer

使用 Python 运行¶

然后，您可以使用普通的 Python 运行您的脚本

$ python my_custom_script.py hello

Hello World!

$ python my_custom_script.py hello --name Camila

Hello Camila!

$ python my_custom_script.py bye --name Camila

Bye Camila

直接使用 Python 运行它没有问题。事实上，如果其他代码或程序使用您的脚本，这可能是最好的方法。

⛔️ 但是，在您的终端中，当您按下 TAB 键时，您将不会获得任何子命令或选项的完成，例如 hello、bye 和 --name。

使用 `typer` 命令运行¶

您也可以使用 typer 命令运行相同的脚本

$ typer my_custom_script.py run hello

Hello World!

$ typer my_custom_script.py run hello --name Camila

Hello Camila!

$ typer my_custom_script.py run bye --name Camila

Bye Camila

您不需要直接使用 python，而是使用 typer 命令。
在文件名之后，添加子命令 run。

✔️ 如果您按照上述方法为 typer 命令安装了完成，那么当您按下 TAB 键时，您将获得 ✨ 所有内容的完成 ✨，包括脚本的所有子命令和选项，例如 hello、bye 和 --name 🚀。

如果主函数¶

因为 typer 命令不会使用带有以下内容的代码块

if __name__ == "__main__":
    app()

...如果您只使用 typer 命令调用该脚本，也可以将其删除。

运行其他文件¶

typer 命令可以运行任何使用 **Typer** 的脚本，但脚本甚至不需要使用 **Typer**。

您甚至可以运行一个包含可以使用 typer.run() 的函数的文件，即使脚本没有使用 typer.run() 或其他任何东西。

例如，像这样的 main.py 文件仍然可以工作

def main(name: str = "World"):
    """
    Say hi to someone, by default to the World.
    """
    print(f"Hello {name}")

然后你可以用它来调用

$ typer main.py run --help
Usage: typer run [OPTIONS]

  Say hi to someone, by default to the World.

Options:
  --name TEXT
  --help       Show this message and exit.

$ typer main.py run --name Camila

Hello Camila

它还将为 --name *CLI 选项* 等提供自动补全功能。

运行包或模块¶

您可以传递一个模块（可能在包中）来导入，而不是文件路径。

例如

$ typer my_package.main run --help
Usage: typer run [OPTIONS]

Options:
  --name TEXT
  --help       Show this message and exit.

$ typer my_package.main run --name Camila

Hello Camila

选项¶

您可以指定以下 **CLI 选项** 之一

--app：包含 Typer() 对象的变量名称，作为主应用程序运行。
--func：包含将与 typer.run() 一起使用的函数的变量名称。

默认值¶

当您使用 typer 命令运行脚本时，它将使用以下优先级的应用程序

来自 --app *CLI 选项* 的应用程序对象。
从 --func *CLI 选项* 转换为 **Typer** 应用程序的函数（就像使用 typer.run() 时一样）。
名称为 app、cli 或 main 的变量中的 **Typer** 应用程序。
文件中第一个可用的 **Typer** 应用程序，无论名称如何。
名称为 main、cli 或 app 的变量中的函数。
文件中第一个函数，无论名称如何。

生成文档¶

您还可以使用 typer 命令为您的 **Typer** 应用程序生成 Markdown 文档。

带有文档的示例脚本¶

例如，您可以有一个像这样的脚本

import typer

app = typer.Typer(help="Awesome CLI user manager.")


@app.command()
def create(username: str):
    """
    Create a new user with USERNAME.
    """
    print(f"Creating user: {username}")


@app.command()
def delete(
    username: str,
    force: bool = typer.Option(
        ...,
        prompt="Are you sure you want to delete the user?",
        help="Force deletion without confirmation.",
    ),
):
    """
    Delete a user with USERNAME.

    If --force is not used, will ask for confirmation.
    """
    if force:
        print(f"Deleting user: {username}")
    else:
        print("Operation cancelled")


@app.command()
def delete_all(
    force: bool = typer.Option(
        ...,
        prompt="Are you sure you want to delete ALL users?",
        help="Force deletion without confirmation.",
    ),
):
    """
    Delete ALL users in the database.

    If --force is not used, will ask for confirmation.
    """
    if force:
        print("Deleting all users")
    else:
        print("Operation cancelled")


@app.command()
def init():
    """
    Initialize the users database.
    """
    print("Initializing user database")


if __name__ == "__main__":
    app()

使用 `typer` 命令生成文档¶

然后，您可以使用 typer 命令为其生成文档。

您可以使用子命令 utils。

然后是子命令 docs。

$ typer some_script.py utils docs

提示

如果你只安装了typer-slim，并且没有typer命令，你仍然可以使用以下命令生成文档：

$ python -m typer some_script.py utils docs

选项:

--name TEXT: 在文档中使用的 CLI 程序名称。
--output FILE: 用于写入文档的输出文件，例如 README.md。
--title TEXT: 在文档中使用的标题，默认情况下为命令的名称。

例如

$ typer my_package.main utils docs --name awesome-cli --output README.md

Docs saved to: README.md

示例文档输出¶

例如，对于前面的脚本，生成的文档将如下所示：

`awesome-cli`¶

很棒的 CLI 用户管理器。

用法:

$ awesome-cli [OPTIONS] COMMAND [ARGS]...

选项:

--install-completion: 为当前 shell 安装补全。
--show-completion: 显示当前 shell 的补全，以便复制或自定义安装。
--help: 显示此消息并退出。

命令:

create: 使用 USERNAME 创建新用户。
delete: 使用 USERNAME 删除用户。
delete-all: 删除数据库中的所有用户。
init: 初始化用户数据库。

`awesome-cli create`¶

使用 USERNAME 创建新用户。

用法:

$ awesome-cli create [OPTIONS] USERNAME

选项:

--help: 显示此消息并退出。

`awesome-cli delete`¶

使用 USERNAME 删除用户。

如果未使用 --force，将要求确认。

用法:

$ awesome-cli delete [OPTIONS] USERNAME

选项:

--force / --no-force: 强制删除，无需确认。[必需]
--help: 显示此消息并退出。

`awesome-cli delete-all`¶

删除数据库中的所有用户。

如果未使用 --force，将要求确认。

用法:

$ awesome-cli delete-all [OPTIONS]

选项:

--force / --no-force: 强制删除，无需确认。[必需]
--help: 显示此消息并退出。

`awesome-cli init`¶

初始化用户数据库。

用法:

$ awesome-cli init [OPTIONS]

选项:

--help: 显示此消息并退出。

typer 命令¶

安装¶