typer

<p align="center"> <a href="https://typer.tiangolo.com"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg#only-light" alt="Typer"></a> </p> <p align="center"> <em>Typer，构建优秀的命令行界面。易于编码。基于Python类型提示。</em> </p> <p align="center"> <a href="https://github.com/fastapi/typer/actions?query=workflow%3ATest" target="_blank"> <img src="https://yellow-cdn.veclightyear.com/ab5030c0/885f4f7b-a24f-4785-867b-2182dc7cfc0c.svg" alt="测试"> </a> <a href="https://github.com/fastapi/typer/actions?query=workflow%3APublish" target="_blank"> <img src="https://yellow-cdn.veclightyear.com/ab5030c0/96507f3d-d500-4744-bd0c-a1366d1eb60b.svg" alt="发布"> </a> <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/fastapi/typer" target="_blank"> <img src="https://coverage-badge.samuelcolvin.workers.dev/fastapi/typer.svg" alt="覆盖率"> <a href="https://pypi.org/project/typer" target="_blank"> <img src="https://img.shields.io/pypi/v/typer?color=%2334D058&label=pypi%20package" alt="包版本"> </a> </p>

---

文档: <a href="https://typer.tiangolo.com" target="_blank">https://typer.tiangolo.com</a>

源代码: <a href="https://github.com/fastapi/typer" target="_blank">https://github.com/fastapi/typer</a>

---

Typer是一个用于构建<abbr title="命令行界面，从终端执行的程序">CLI</abbr>应用程序的库，用户将喜欢使用，开发人员将喜欢创建。基于Python类型提示。

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

主要特点是：

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

CLI的FastAPI

Typer是<a href="https://fastapi.tiangolo.com" class="external-link" target="_blank">FastAPI</a>的小兄弟，它是CLI的FastAPI。

安装

<div class="termy">

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

</div>

示例

最简单的示例

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

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

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

运行它

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

<div class="termy">

// 运行您的应用程序
$ 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

// 成功了！🎉

</div>

这是最简单的用例，甚至内部没有使用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运行它：

<div class="termy">

// 运行您的应用程序
$ 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

// 成功了！🎉

</div>

注意：您也可以用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）。

运行升级后的示例

查看新的帮助：

<div class="termy">

$ python main.py --help

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

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

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

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

<div class="termy">

$ python main.py hello --help

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

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

</div>

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

<div class="termy">

$ python main.py goodbye --help

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

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

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

</div>

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

<div class="termy">

// 使用 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.

</div>

回顾

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

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

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

只需使用标准的 Python。

例如，对于 int 类型：

total: int

或者对于 bool 标志：

force: bool

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

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

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

有关更完整的示例，包括更多功能，请参阅 <a href="https://typer.tiangolo.com/tutorial/">教程 - 用户指南</a>。

依赖项

Typer 站在巨人的肩膀上。它唯一的内部必需依赖是 <a href="https://click.palletsprojects.com/" class="external-link" target="_blank">Click</a>。

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

• <a href="https://rich.readthedocs.io/en/stable/index.html" class="external-link" target="_blank"><code>rich</code></a>：用于自动显示格式良好的错误。
• <a href="https://github.com/sarugaku/shellingham" class="external-link" target="_blank"><code>shellingham</code></a>：用于在安装自动补全时自动检测当前 shell。
  • 使用 shellingham 时，你可以直接使用 --install-completion。
  • 不使用 shellingham 时，你需要指定要安装自动补全的 shell 名称，例如 --install-completion bash。

typer-slim

如果你不想要额外的标准可选依赖项，可以安装 typer-slim。

当你使用以下命令安装时：

pip install typer

...它包含的代码和依赖项与以下命令相同：

pip install "typer-slim[standard]"

standard 额外依赖项是 rich 和 shellingham。

注意：typer 命令仅包含在 typer 包中。

许可证

本项目根据 MIT 许可证的条款进行许可。