本教程将指导你如何使用 Typer 来构建一个命令行界面（CLI）。Typer 是一个 Python 库，它可以帮助你快速简单地创建 CLI，并充分利用 Python 的类型提示（type hints）。

我们将以构建一个日程追踪工具为例，具体步骤包括：

• 安装并配置 Typer
• 添加命令
• 正确处理任务（task）、时间（time）和优先级（priority）的输入与数据类型

现在我们正式开始吧！

第一步：安装 Typer

首先，我们安装 Typer：

$ pip3 install typer

安装 Typer 时会自动安装所需的全部依赖项，以支持 CLI 功能。建议你在项目的虚拟环境中安装 Typer。

你也可以访问这个示例项目的 GitHub 仓库。

第二步：创建基本的 CLI 工具

我们先创建一个简单的 CLI，能够添加带有正确时间格式的任务。

新建一个名为 schedule_tracker.py 的 Python 文件。

引入必要的库和模块，并实例化一个 typer.Typer() 对象（app），用于管理 CLI 命令。

import typer
from datetime import datetime
import json
from typing import List

app = typer.Typer()

我们定义一些辅助函数，用于从 JSON 文件加载和保存日程数据：

SCHEDULE_FILE = "schedule.json"

def load_schedule() -> List[dict]:
    try:
        with open(SCHEDULE_FILE, "r") as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError):
        return []

def save_schedule(schedule: List[dict]):
    with open(SCHEDULE_FILE, "w") as f:
        json.dump(schedule, f, default=str, indent=4)

因为每个任务都有相关的时间，我们创建一个辅助函数，将字符串解析为合法的时间对象：

def parse_time(t: str) -> datetime.time:
    try:
        return datetime.strptime(t, "%H:%M").time()
    except ValueError:
        typer.echo("无效的时间格式，请使用 HH:MM 格式。")
        raise typer.Exit()

创建基本的 add_task 命令。每个任务项目包括任务描述、时间和优先级：

@app.command()
def add_task(
    task: str,
    time: str = typer.Option(..., help="任务时间，格式为 HH:MM"),
    priority: int = typer.Option(1, help="任务优先级")
):
    schedule = load_schedule()
    task_time = parse_time(time)
    schedule.append({"task": task, "time": task_time.strftime("%H:%M"), "priority": priority})
    save_schedule(schedule)
    typer.echo(f"任务 '{task}' 已添加，时间为 {task_time.strftime('%H:%M')}，优先级为 {priority}")

if __name__ == "__main__":
    app()

第三步：运行 CLI 工具

现在运行 schedule_tracker.py，添加一个任务：

$ python3 schedule_tracker.py add-task "团队会议" --time "14:00" --priority 2

输出如下：

任务 '团队会议' 已添加，时间为 14:00，优先级为 2

现在你就拥有了一个可以接收任务、时间和优先级的 CLI 工具。

第四步：添加更多命令功能

我们再给日程管理工具添加更多功能，比如查看任务列表和删除任务。

首先，增加一个按时间排序查看任务的命令：

@app.command()
def list_tasks():
    """列出所有已安排的任务"""
    schedule = load_schedule()
    if not schedule:
        typer.echo("未找到任何任务。")
        return
    for i, task in enumerate(sorted(schedule, key=lambda x: x["time"]), start=1):
        print(f"任务 {i}: {task['task']}")
        print(f"  时间: {task['time']}")
        print(f"  优先级: {task['priority']}")
        print("-" * 40)  # 添加分隔线提高可读性

你也可以根据需要修改函数，以按优先级排序任务。

再增加一个通过任务编号删除任务的命令：

@app.command()
def remove_task(task_number: int):
    """通过编号删除任务"""
    schedule = load_schedule()
    if 0 < task_number <= len(schedule):
        removed_task = schedule.pop(task_number - 1)
        save_schedule(schedule)  # 保存更新后的日程
        typer.echo(f"已删除任务 '{removed_task['task']}', 原定时间为 {removed_task['time']}") 
    else: 
        typer.echo(f"无效的任务编号，请选择介于 1 和 {len(schedule)} 之间的数字。")

第五步：测试改进版 CLI 工具

现在测试一下我们刚添加的新命令。

添加多个任务：

$ python3 schedule_tracker.py add-task "代码审查" --time "10:30" --priority 1
$ python3 schedule_tracker.py add-task "客户会议" --time "12:00" --priority 3

输出：

任务 '代码审查' 已添加，时间为 10:30，优先级为 1
任务 '客户会议' 已添加，时间为 12:00，优先级为 3

查看所有任务：

$ python3 schedule_tracker.py list-tasks

输出：

任务 1: 代码审查
  时间: 10:30
  优先级: 1
----------------------------------------
任务 2: 客户会议
  时间: 12:00
  优先级: 3
----------------------------------------
任务 3: 团队会议
  时间: 14:00
  优先级: 2
----------------------------------------

删除任务：

$ python3 schedule_tracker.py remove-task 3

输出：

已删除任务 '团队会议', 原定时间为 14:00

再次查看更新后的任务列表：

$ python3 schedule_tracker.py list-tasks

输出为：

任务 1: 代码审查
  时间: 10:30
  优先级: 1
----------------------------------------
任务 2: 客户会议
  时间: 12:00
  优先级: 3
----------------------------------------

总结与后续扩展

本教程到此结束。通过本教程的介绍，你已看到使用 Typer 可以在几分钟内轻松地构建简单而实用的 CLI 工具。本次我们构建了一个日程管理工具，能够高效地处理任务和时间输入验证。

你可以继续优化我们本次构建的版本，扩展添加更多功能，比如循环任务、提醒通知、日程导出等。你也可以尝试构建其他类似的 CLI 工具，比如费用追踪器。

祝你编程顺利！