typer - Python类型提示驱动的直观命令行界面框架

Typer，构建优秀的命令行界面。易于编码。基于Python类型提示。

文档: https://typer.tiangolo.com

源代码: https://github.com/fastapi/typer

Typer是一个用于构建CLI应用程序的库，用户将喜欢使用，开发人员将喜欢创建。基于Python类型提示。

它也是一个命令行工具，用于运行脚本，自动将它们转换为CLI应用程序。

主要特点是：

直观编写：出色的编辑器支持。所有地方都有补全。减少调试时间。设计易于使用和学习。减少阅读文档的时间。
易于使用：对最终用户来说很容易使用。自动帮助，以及所有shell的自动补全。
简洁：最小化代码重复。每个参数声明都具有多个功能。更少的bug。
简单开始：最简单的示例只需要在您的应用程序中添加2行代码：1个导入，1个函数调用。
可扩展：根据需要增加复杂性，创建任意复杂的命令树和子命令组，带有选项和参数。
运行脚本：Typer包含一个typer命令/程序，您可以用它来运行脚本，自动将它们转换为CLI，即使它们内部没有使用Typer。

CLI的FastAPI

Typer是FastAPI的小兄弟，它是CLI的FastAPI。

安装

$ pip install typer
---> 100%
成功安装typer rich shellingham

示例

最简单的示例

创建一个main.py文件，内容如下：

def main(name: str):
    print(f"Hello {name}")

这个脚本内部甚至没有使用Typer。但您可以使用typer命令将其作为CLI应用程序运行。

运行它

使用typer命令运行您的应用程序：

// 运行您的应用程序
$ typer main.py run

// 您得到一个友好的错误，缺少NAME参数
Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME
Try 'typer [PATH_OR_MODULE] run --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'.                          │
╰───────────────────────────────────────────────────╯


// 您可以免费获得--help
$ typer main.py run --help

Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME

Run the provided Typer app.

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help          Show this message and exit.       │
╰───────────────────────────────────────────────────╯

// 现在传入NAME参数
$ typer main.py run Camila

Hello Camila

// 成功了！🎉

这是最简单的用例，甚至内部没有使用Typer，但对于简单的脚本来说已经很有用了。

注意：当您创建Python包并使用--install-completion运行它或使用typer命令时，自动补全功能才能生效。

在您的代码中使用Typer

现在让我们开始在您自己的代码中使用Typer，更新main.py为：

import typer


def main(name: str):
    print(f"Hello {name}")


if __name__ == "__main__":
    typer.run(main)

现在您可以直接用Python运行它：

// 运行您的应用程序
$ python main.py

// 您得到一个友好的错误，缺少NAME参数
Usage: main.py [OPTIONS] NAME
Try 'main.py --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'.                          │
╰───────────────────────────────────────────────────╯


// 您可以免费获得--help
$ python main.py --help

Usage: main.py [OPTIONS] NAME

╭─ Arguments ───────────────────────────────────────╮
│ *    name      TEXT  [default: None] [required]   |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help          Show this message and exit.       │
╰───────────────────────────────────────────────────╯

// 现在传入NAME参数
$ python main.py Camila

Hello Camila

// 成功了！🎉

注意：您也可以用typer命令调用这个相同的脚本，但您不需要这样做。

示例升级

这是最简单的示例。

现在让我们看一个稍微复杂一点的。

一个带有两个子命令的示例

修改main.py文件。

创建一个typer.Typer()应用，并创建两个带参数的子命令。

import typer

app = typer.Typer()


@app.command()
def hello(name: str):
    print(f"Hello {name}")


@app.command()
def goodbye(name: str, formal: bool = False):
    if formal:
        print(f"Goodbye Ms. {name}. Have a good day.")
    else:
        print(f"Bye {name}!")


if __name__ == "__main__":
    app()

这将：

显式创建一个typer.Typer应用。
- 之前的typer.run实际上隐式地为您创建了一个。
用@app.command()添加两个子命令。
执行app()本身，就像它是一个函数一样（而不是typer.run）。

运行升级后的示例

查看新的帮助：

$ python main.py --help

 Usage: main.py [OPTIONS] COMMAND [ARGS]...
╭─ 选项 ─────────────────────────────────────────╮
│ --install-completion          为当前shell安装   │
│                               自动补全功能      │
│ --show-completion             显示当前shell的   │
│                               自动补全内容，    │
│                               以便复制或自定义  │
│                               安装              │
│ --help                        显示此消息并退出  │
╰───────────────────────────────────────────────────╯
╭─ 命令 ────────────────────────────────────────────╮
│ goodbye                                           │
│ hello                                             │
╰───────────────────────────────────────────────────╯

// 当你创建一个包时，你可以免费获得 ✨ 自动补全 ✨ 功能，通过 --install-completion 安装

// 你有两个子命令（两个函数）：goodbye 和 hello

现在检查 hello 命令的帮助信息：

$ python main.py hello --help

 用法: main.py hello [选项] 名称

╭─ 参数 ─────────────────────────────────────────────╮
│ *    名称      文本  [默认: 无] [必填]             │
╰───────────────────────────────────────────────────╯
╭─ 选项 ─────────────────────────────────────────────╮
│ --help          显示此消息并退出                   │
╰───────────────────────────────────────────────────╯

现在检查 goodbye 命令的帮助信息：

$ python main.py goodbye --help

 用法: main.py goodbye [选项] 名称

╭─ 参数 ─────────────────────────────────────────────╮
│ *    名称      文本  [默认: 无] [必填]             │
╰───────────────────────────────────────────────────╯
╭─ 选项 ─────────────────────────────────────────────╮
│ --formal    --no-formal      [默认: no-formal]     │
│ --help                       显示此消息并退出      │
╰───────────────────────────────────────────────────╯

// 布尔选项自动生成 --formal 和 --no-formal 🎉

现在你可以尝试使用这个新的命令行应用：

// 使用 hello 命令

$ python main.py hello Camila

Hello Camila

// 使用 goodbye 命令

$ python main.py goodbye Camila

Bye Camila!

// 使用 --formal 选项

$ python main.py goodbye --formal Camila

Goodbye Ms. Camila. Have a good day.

回顾

总之，你只需要通过函数参数声明一次参数类型（CLI 参数和 CLI 选项）。

你可以使用标准的现代 Python 类型来实现这一点。

你不需要学习新的语法、特定库的方法或类等。

只需使用标准的 Python。

例如，对于 int 类型：

total: int

或者对于 bool 标志：

force: bool

类似地，还可以用于文件、路径、枚举（选项）等。还有工具可以创建 子命令组，添加元数据，额外的验证等。

你获得：出色的编辑器支持，包括全面的 自动补全 和 类型检查。

你的用户获得：自动生成的 --help，当他们安装你的包或使用 typer 命令时，可在终端（Bash、Zsh、Fish、PowerShell）中使用 自动补全。

有关更完整的示例，包括更多功能，请参阅教程 - 用户指南。

依赖项

Typer 站在巨人的肩膀上。它唯一的内部必需依赖是 Click。

默认情况下，它还带有额外的标准依赖项：

rich：用于自动显示格式良好的错误。
shellingham：用于在安装自动补全时自动检测当前 shell。
- 使用 shellingham 时，你可以直接使用 --install-completion。
- 不使用 shellingham 时，你需要指定要安装自动补全的 shell 名称，例如 --install-completion bash。