Typer 命令行工具开发入门指南

宋韵庚

于 2025-06-02 09:03:53 发布

阅读量302

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00089/article/details/148375389

Typer 命令行工具开发入门指南

typer Typer是一款基于Python类型提示构建的库，用于轻松编写高质量命令行接口（CLI）程序。项目地址: https://gitcode.com/gh_mirrors/ty/typer

什么是 Typer

Typer 是一个基于 Python 类型提示(Type Hints)的现代命令行界面(CLI)开发框架。它让开发者能够快速构建强大且用户友好的命令行工具，同时保持代码简洁明了。

最简单的 Typer 示例

让我们从一个最简单的 Typer 程序开始：

def main():
    print("Hello World")

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

将上述代码保存为 main.py 并运行：

python main.py

程序会输出 "Hello World"。虽然这个程序功能简单，但它展示了 Typer 的基本结构。

理解 CLI 参数与选项

在开发命令行工具时，我们需要区分两种主要的输入方式：

CLI 参数(Arguments)

CLI 参数是按特定顺序传递给程序的参数。例如：

ls ./myproject

这里 ./myproject 就是一个 CLI 参数，它表示要列出内容的目录路径。参数的特点是：

默认情况下是必需的
顺序很重要
没有前缀标识符

CLI 选项(Options)

CLI 选项是通过特定名称传递的参数。例如：

ls --size ./myproject

这里 --size 就是一个 CLI 选项，它告诉 ls 命令显示文件大小。选项的特点是：

默认情况下是可选的
顺序不重要
通常以 -- 或 - 开头

添加 CLI 参数

让我们扩展我们的程序，添加一个名字参数：

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

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

现在运行程序时需要提供名字参数：

python main.py Camila

如果忘记提供参数，Typer 会自动显示友好的错误提示。

添加多个 CLI 参数

我们可以添加更多参数，例如名字和姓氏：

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

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

使用时必须按顺序提供两个参数：

python main.py Camila Gutiérrez

添加 CLI 选项

现在让我们添加一个 --formal 选项来控制问候语的正式程度：

def main(name: str, lastname: str, formal: bool = False):
    if formal:
        print(f"Good day Ms. {name} {lastname}.")
    else:
        print(f"Hello {name} {lastname}")

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

由于 formal 是布尔类型，Typer 会自动生成 --formal 和 --no-formal 两个选项：

python main.py Camila Gutiérrez --formal

将参数转换为选项

我们可以将姓氏参数改为选项，使其变为可选：

def main(name: str, lastname: str = ""):
    if lastname:
        print(f"Hello {name} {lastname}")
    else:
        print(f"Hello {name}")

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

现在 lastname 变成了可选选项 --lastname：

python main.py Camila --lastname Gutiérrez

添加文档说明

良好的文档是 CLI 工具的重要组成部分。我们可以通过函数文档字符串(docstring)为程序添加帮助信息：

def main(name: str, lastname: str = "", formal: bool = False):
    """
    Say hi to NAME, optionally with a --lastname.
    If --formal is used, say hi very formally.
    """
    if formal:
        print(f"Good day Ms. {name} {lastname}." if lastname else f"Good day Ms. {name}.")
    else:
        print(f"Hello {name} {lastname}" if lastname else f"Hello {name}")

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

现在运行 --help 会显示我们添加的文档：