typer

Typer 知识

通过为 Python 函数添加注解，使用 Typer 构建 CLI 应用。Typer 会将类型注解转换为经过验证的 CLI 参数，并自动生成帮助文本。

Typer 版本： !python -c "import typer; print(typer.__version__)" 2>/dev/null || echo "not found in PATH"

范围

共享规则（架构、类型、测试、CLI 规则）请参阅 python-engineering:standards-for-python-development。

触发条件：用户询问如何使用 Typer 构建 CLI、定义 CLI 参数或选项、组合子命令、测试 CLI 应用，或使用提示词、枚举、进度条、自动补全等 Typer 功能时，激活本知识。

涵盖内容：

• 使用 typer.Typer() 和 typer.run() 创建应用
• CLI 参数（typer.Argument()）和选项（typer.Option()）
• 参数类型——枚举、路径、数字、日期、UUID、自定义类型
• 使用 app.add_typer() 组合子命令
• 使用 typer.testing.CliRunner 进行测试
• 输出、颜色、进度条、回调和自动补全

不涵盖：

• Typer 未公开的 Click 内部实现
• 超出 typer.echo / typer.style 范围的 Rich 库
• FastAPI 或其他 Web 框架

工作流

flowchart TD
    Start([Task received]) --> Q1{Task type?}
    Q1 -->|Create app or add commands| AppCmd[Load reference — app-and-commands.md]
    Q1 -->|Define arguments or options| Params[Load reference — parameters.md]
    Q1 -->|Use enum, path, date, UUID| Types[Load reference — parameter-types.md]
    Q1 -->|Add subcommands or sub-apps| Sub[Load reference — subcommands.md]
    Q1 -->|Write tests| Test[Load reference — testing.md]
    Q1 -->|Callbacks, output, progress, packaging| Adv[Load reference — advanced-patterns.md]

参考文件

应用和命令

创建 Typer 应用、使用 @app.command() 注册命令、配置多命令应用，以及控制命令名称和帮助文本的核心模式。 创建新应用、添加命令或配置应用级行为时加载。

../python3-cli/references/typer-app-and-commands.md

参数

CLI 参数和 CLI 选项的完整参考——typer.Argument()、typer.Option()、默认值、必需与可选参数、帮助文本、提示词、密码输入、选项名称、环境变量绑定、多个值、布尔标志和版本选项。 定义任何 CLI 参数或控制输入接收方式时加载。

../python3-cli/references/typer-parameters.md

参数类型

Typer 可识别的类型注解——str、int、float、bool、enum.Enum、Literal、pathlib.Path、文件对象、datetime、UUID 和自定义 Click ParamType 子类。 需要将参数值限制在某个集合内、验证路径、解析日期或实现自定义类型时加载。

../python3-cli/references/typer-parameter-types.md

子命令

使用 app.add_typer() 组合多个 typer.Typer() 实例，以创建嵌套命令层级。涵盖单文件和多文件模式、命名、帮助文本以及回调覆盖。 添加子应用、创建命令组或构建类似 git 的多级命令树时加载。

../python3-cli/references/typer-subcommands.md

测试

使用 pytest 和 typer.testing.CliRunner 测试 Typer 应用。涵盖在测试中调用应用、检查退出代码和输出、模拟提示输入，以及测试裸函数。 为任何 Typer CLI 编写测试时加载。

../python3-cli/references/typer-testing.md

高级模式

上下文（typer.Context）、急切回调、typer.echo / typer.secho / typer.style、进度条、typer.Exit / typer.Abort、typer.confirm、自动补全配置、使用 pyproject.toml 打包，以及 typer.launch。 实现版本标志、彩色输出、进度报告、Shell 补全，或将 CLI 打包为可分发工具时加载。

../python3-cli/references/typer-advanced-patterns.md

快速参考

import typer
from typing import Annotated

app = typer.Typer()


@app.command()
def main(
    name: str,  # required argument
    count: Annotated[int, typer.Option()] = 1,  # optional option
    formal: bool = False,  # --formal / --no-formal
):
    """Greet NAME."""
    for _ in range(count):
        greeting = f"Good day, {name}." if formal else f"Hello {name}"
        typer.echo(greeting)


if __name__ == "__main__":
    app()

$ python main.py Alice --count 2 --formal
Good day, Alice.
Good day, Alice.