Typer_Python CLI新标准

你还在用Click或argparse写命令行工具吗？

说实话，我第一次看到Typer的代码时愣了几秒。之前用Click写CLI，光定义参数就要写一大坨代码，还要手动处理类型转换、验证逻辑。Typer直接用类型注解声明参数，代码看起来就像普通Python函数一样清爽。

这就是今天要介绍的——Typer，Python CLI应用的新标准。

 01. 

一、为什么命令行工具值得认真对待

很多人觉得命令行工具是"小玩意儿"，随便写写就行。

但实际上，CLI工具的质量直接影响开发体验。我们团队的部署脚本原来是用bash写的，每次新人接手都要花半天理解逻辑。后来我用Typer重写了一下，加上了类型验证和清晰的帮助文档，培训时间直接降到半小时。

命令行工具的可维护性，决定了团队的协作效率。

 02. 

二、Typer是什么

Typer是一个用于构建CLI应用的Python库，底层基于Click，但用完全不同的方式声明参数。你不需要写一堆装饰器配置参数，只需要在函数签名中使用Python的类型注解。

PYTHONimport typerapp = typer.Typer()@app.command()def hello(name: str, age: int = 30):    print(f"Hello {name}, you are {age} years old!")if __name__ == "__main__":    app()

运行效果：

BASH$ python main.py hello WorldHello World, you are 30 years old!$ python main.py hello Alice --age 25Hello Alice, you are 25 years old!$ python main.py hello --helpUsage: main.py hello [OPTIONS] NAME  Say hello to NAMEOptions:  --age INTEGER  [default: 30]  --help         Show this message and exit.

看，帮助文档是自动生成的。参数类型、默认值、用法说明，全都有了。

 03. 

三、快速上手：第一个CLI应用

安装Typer只需要一行命令：

BASHpip install typer

3.1 基本结构

一个最小的Typer应用长这样：

PYTHONimport typerapp = typer.Typer()@app.command()def main(name: str):    typer.echo(f"你好，{name}！")if __name__ == "__main__":    app()

执行 python main.py 小明，输出"你好，小明！"。这就是全部代码量。

3.2 添加选项参数

如果参数不是必须的，用 Optional 配合默认值：

PYTHONimport typerfrom typing import Optionalapp = typer.Typer()@app.command()def greet(    name: str,    greeting: Optional[str] = "你好",    excited: bool = False):    message = f"{greeting}，{name}"    if excited:        message += "！"    typer.echo(message)if __name__ == "__main__":    app()

BASH$ python main.py greet Alice你好，Alice$ python main.py greet Bob --greeting "早上好" --excited早上好，Bob！

注意：布尔参数 --excited 会自动转换为flag，带上它就是 True，不带就是 False。

 04. 

四、参数声明的细节

4.1 位置参数 vs 选项参数

Typer会根据参数名自动决定是位置参数还是选项参数。规则很简单：

• 位置参数：参数名不带前缀，看起来像普通函数参数

• 选项参数：参数名带 -- 前缀，或者有默认值

PYTHON@app.command()def process(    filename: str,              # 位置参数：python main.py process data.csv    output: str = "out.txt",    # 选项参数：python main.py process data.csv --output result.txt    verbose: bool = False,      # flag：python main.py process data.csv --verbose):    pass

4.2 必填选项参数

默认有默认值的参数是可选的。如果想让它必填，有两种方式：

PYTHON# 方式一：不设置默认值@app.command()def copy(src: str, dst: str):  # 两个都是必填    pass# 方式二：用 None 作为默认值，明确表示需要提供@app.command()def fetch(url: str, timeout: int = None):    pass

4.3 带提示的交互输入

有时候需要从用户获取输入，但不想硬编码在命令行里。用 typer.prompt()：

PYTHON@app.command()def create_project(name: str):    author = typer.prompt("作者名称", default="Anonymous")    typer.echo(f"创建项目 {name}，作者：{author}")

BASH$ python main.py create-project myapp作者名称 [Anonymous]: John创建项目 myapp，作者：John

踩坑提示：我之前不知道这个功能，自己写了个 input() 来处理。后来看到官方示例才一拍大腿——Typer的 prompt 支持默认值和类型验证，比裸 input() 好用多了。

 05. 

五、类型验证与自定义验证

5.1 自动类型检查

Typer会根据类型注解自动验证输入：

PYTHON@app.command()def calculate(a: int, b: int):    typer.echo(f"{a} + {b} = {a + b}")

BASH$ python main.py calculate 3 53 + 5 = 8$ python main.py calculate hello 5Error: Invalid value for 'A': 'hello' is not a valid integer

字符串 "hello" 被自动拒绝，因为参数声明了 int 类型。

5.2 使用Enum限制选项

如果某个参数只能取特定值，用 Enum：

PYTHONfrom enum import Enumimport typerclass Color(str, Enum):    RED = "red"    GREEN = "green"    BLUE = "blue"app = typer.Typer()@app.command()def set_color(color: Color):    typer.echo(f"设置颜色为 {color.value}")if __name__ == "__main__":    app()

BASH$ python main.py set-color red设置颜色为 red$ python main.py set-color yellowError: Invalid value for 'COLOR': 'yellow' is not a valid value. Choose from: red, green, blue

5.3 自定义验证函数

复杂的验证逻辑，可以用 typer.Argument 或 typer.Option 的 callback 参数：

PYTHONimport typerfrom typing import Annotatedapp = typer.Typer()def validate_positive(value: int):    if value <= 0:        raise typer.BadParameter("必须大于0")    return value@app.command()def calculate_square(value: Annotated[int, typer.Option(callback=validate_positive)]):    typer.echo(f"平方：{value ** 2}")if __name__ == "__main__":    app()

BASH$ python main.py calculate-square --value -5Error: Invalid value for '--value': 必须大于0

 06. 

六、命令分组：构建多命令应用

当CLI工具需要支持多个子命令时，用 app.command() 分组：

PYTHONimport typerapp = typer.Typer()@app.command()def init(name: str):    """初始化新项目"""    typer.echo(f"初始化项目 {name}...")@app.command()def build():    """构建项目"""    typer.echo("构建中...")@app.command()def deploy(env: str):    """部署到指定环境"""    typer.echo(f"部署到 {env}...")if __name__ == "__main__":    app()

BASH$ python main.py --helpUsage: main.py [OPTIONS] COMMAND [ARGS]...Options:  --help  Show this message and exit.Commands:  build   构建项目  deploy  部署到指定环境  init    初始化新项目$ python main.py deploy production部署到 production...

项目脚手架的标配：这种多命令结构是现代CLI工具的标配，比如 git、docker、npm 都是这个模式。

 07. 

七、实战案例：文件处理工具

一个实际可用的文件处理CLI：

PYTHONimport typerfrom pathlib import Pathfrom typing import Optionalapp = typer.Typer()@app.command()def stats(    path: Path = typer.Argument(..., help="文件或目录路径"),    recursive: bool = typer.Option(False, "--recursive", "-r", help="递归处理子目录"),):    """统计文件信息"""    if path.is_file():        typer.echo(f"文件：{path.name}")        typer.echo(f"大小：{path.stat().st_size} 字节")    elif path.is_dir():        files = list(path.rglob("*")) if recursive else list(path.glob("*"))        total = sum(f.stat().st_size for f in files if f.is_file())        typer.echo(f"目录：{path.name}")        typer.echo(f"文件数：{len([f for f in files if f.is_file()])}")        typer.echo(f"总大小：{total} 字节")    else:        typer.echo(f"路径不存在：{path}", err=True)@app.command()def copy_file(    src: Path = typer.Argument(..., help="源文件路径"),    dst: Path = typer.Argument(..., help="目标路径"),):    """复制文件"""    import shutil    if not src.exists():        typer.echo(f"源文件不存在：{src}", err=True)        raise typer.Exit(code=1)    shutil.copy2(src, dst)    typer.echo(f"已复制：{src} -> {dst}")if __name__ == "__main__":    app()

BASH$ python fileutil.py stats ./data目录：data文件数：42总大小：1048576 字节$ python fileutil.py copy-file input.txt backup/已复制：input.txt -> backup/

 08. 

八、高级特性

8.1 彩色输出

搭配Rich库，让输出更美观：

BASHpip install rich

PYTHONfrom rich.console import Consolefrom rich.table import Tableimport typerapp = typer.Typer()console = Console()@app.command()def list_packages():    table = Table(title="已安装的包")    table.add_column("名称", style="cyan")    table.add_column("版本", style="green")    table.add_row("requests", "2.28.0")    table.add_row("typer", "0.9.0")    table.add_row("rich", "13.0.0")    console.print(table)if __name__ == "__main__":    app()

8.2 进度显示

处理耗时任务时，用Progress显示进度：

PYTHONfrom rich.progress import Progressimport typerapp = typer.Typer()@app.command()def process_files(files: list[str]):    with Progress() as progress:        task = progress.add_task("[green]处理中...", total=len(files))        for f in files:            # 模拟处理            import time            time.sleep(0.1)            progress.update(task, advance=1)if __name__ == "__main__":    app()

8.3 异步支持

Typer原生支持异步函数：

PYTHONimport asyncioimport typerapp = typer.Typer()@app.command()async def fetch_all(urls: list[str]):    import aiohttp    async with aiohttp.ClientSession() as session:        for url in urls:            async with session.get(url) as response:                content = await response.text()                typer.echo(f"{url}: {len(content)} bytes")if __name__ == "__main__":    asyncio.run(app())

 09. 

九、最佳实践

9.1 项目结构建议

一个完整的Typer项目通常这样组织：

TEXTmycli/├── pyproject.toml├── src/│   └── mycli/│       ├── __init__.py│       ├── __main__.py│       └── cli.py└── README.md

__main__.py 让项目可以直接运行：

PYTHON# src/mycli/__main__.pyfrom mycli.cli import appif __name__ == "__main__":    app()

TOML# pyproject.toml[project.scripts]mycli = "mycli.cli:app"

安装后就可以全局使用 mycli 命令。

9.2 测试策略

用 TyperTester 简化测试：

PYTHONfrom typer.testing import CliRunnerfrom mycli.cli import apprunner = CliRunner()def test_greet():    result = runner.invoke(app, ["greet", "Alice"])    assert result.exit_code == 0    assert "Alice" in result.stdout

9.3 命令行补全

Typer支持shell自动补全，让用户按Tab键就能补全参数：

PYTHON@app.command()def main():    """主命令"""    passif __name__ == "__main__":    app()

安装方式根据shell不同而不同：

BASH# Basheval "$(python main.py --install-completion bash)"# Zsheval "$(python main.py --install-completion zsh)"# Fishpython main.py --install-completion fish | source

 10. 

十、总结

Typer的核心优势就两点：代码即文档，类型即验证。

用Python类型注解声明参数，你的代码读起来就像普通函数，但运行时就变成了功能完整的命令行工具。自动生成的帮助文档、参数验证、类型检查——这些原本需要手动配置的东西，Typer都帮你搞定了。

我之前用Click写过一个200多行的CLI，后来用Typer重写，只用了80行。维护成本降了一大截，新功能加上去也快多了。

命令行工具值得认真对待。 一套好的CLI工具，能让团队的协作效率提升好几个档次。

📌 更多Python技术干货，关注"Python与AI智能研习社"~