跳至内容

Typer

Typer

Typer，构建出色的 CLI。易于编码。基于 Python 类型提示。

Test Publish Coverage Package version

文档: https://typer.fastapi.org.cn

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

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

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

主要功能包括

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

CLI 的 FastAPI

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

安装

$ pip install typer
---> 100%
Successfully installed typer rich shellingham

示例

绝对最小值

  • 使用以下内容创建一个文件 main.py
def main(name: str):
    print(f"Hello {name}")

此脚本甚至在内部不使用 Typer。但你可以使用 typer 命令将其作为 CLI 应用程序运行。

运行它

使用 typer 命令运行你的应用程序

// Run your application
$ typer main.py run

// You get a nice error, you are missing NAME
Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME
Try 'typer [PATH_OR_MODULE] run --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'.                          │
╰───────────────────────────────────────────────────╯


// You get a --help for free
$ 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.       │
╰───────────────────────────────────────────────────╯

// Now pass the NAME argument
$ typer main.py run Camila

Hello Camila

// It works! 🎉

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

// Run your application
$ python main.py

// You get a nice error, you are missing NAME
Usage: main.py [OPTIONS] NAME
Try 'main.py --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'.                          │
╰───────────────────────────────────────────────────╯


// You get a --help for free
$ python main.py --help

Usage: main.py [OPTIONS] NAME

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

// Now pass the NAME argument
$ python main.py Camila

Hello Camila

// It works! 🎉

注意：你也可以使用 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]...

╭─ 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 ────────────────────────────────────────╮
│ goodbye                                           │
│ hello                                             │
╰───────────────────────────────────────────────────╯

// When you create a package you get ✨ auto-completion ✨ for free, installed with --install-completion

// You have 2 subcommands (the 2 functions): goodbye and hello

现在查看 hello 命令的帮助

$ python main.py hello --help

 Usage: main.py hello [OPTIONS] NAME

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

现在查看 goodbye 命令的帮助

$ python main.py goodbye --help

 Usage: main.py goodbye [OPTIONS] NAME

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

// Automatic --formal and --no-formal for the bool option 🎉

现在你可以尝试新的命令行应用程序

// Use it with the hello command

$ python main.py hello Camila

Hello Camila

// And with the goodbye command

$ python main.py goodbye Camila

Bye Camila!

// And with --formal

$ python main.py goodbye --formal Camila

Goodbye Ms. Camila. Have a good day.

回顾

总之，你一次性声明参数类型（CLI 参数和CLI 选项）作为函数参数。

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

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

只需要标准的 Python。

例如，对于 int

total: int

或对于 bool 标志

force: bool

对于文件、路径、枚举（选择）等也是类似的。并且有工具可以创建子命令组、添加元数据、额外的验证等。

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

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

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

依赖项

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

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

  • rich：自动显示格式良好的错误。
  • shellingham：在安装补全时自动检测当前 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 许可证条款获得许可。