Python Typer可重复参数怎样收集为列表

平时用Typer写Python命令行工具时，想要把重复传入的同个参数收集为列表，直接给对应参数标注列表类型就可以实现，大部分场景下Typer会自动完成解析处理。

在 Typer 里，如果一个选项可能出现多次，不要把它声明成单个字符串再自行拆分，而是直接把参数类型写成 list[str] 或 list[float]。这样，同一个选项每出现一次就贡献一个列表元素，函数收到的已经是可遍历的 Python 列表。

官方地址：https://typer.tiangolo.com/

先用基线确认重复选项的目标形态

先把输入规模固定成三个小场景：不传 --user 时列表为空或为 None；传一次时长度为 1；连续传三次时长度为 3。这个基线比“看起来能跑”更容易排查，因为选项出现次数和函数收到的列表长度应保持一致。

用 list 声明可重复的 CLI 选项

Python 3.10 及以上可以用 Annotated 明确把 Typer 的选项元数据和列表类型放在一起。下面的示例使用 None 作为默认值，因此可以把“调用者没有提供用户”作为一个独立分支处理。

from typing import Annotated

import typer

app = typer.Typer()


@app.command()
def main(user: Annotated[list[str] | None, typer.Option()] = None):
    # None 表示调用者没有提供 --user，先给出明确的输入提示。
    if not user:
        print(f"No provided users (raw input = {user})")
        raise typer.Abort()

    # 同一个 --user 出现多次时，Typer 已经按出现顺序收集成列表。
    for current_user in user:
        print(f"Processing user: {current_user}")


if __name__ == "__main__":
    # 交给 Typer 解析命令行参数并调用 main。
    app()

调用时不要写成一个逗号分隔的长字符串，而是重复同一个选项：

# 每个 --user 对应列表中的一个元素，顺序保持不变。
uv run python main.py --user Camila --user Rick --user Morty

把重复参数收集成具体类型

如果选项代表数值，直接声明为 list[float]。Typer 会按元素类型处理输入，业务层拿到的是浮点数列表，可以直接求和或继续计算。默认值为 [] 时，未传参也能直接进入聚合逻辑。

from typing import Annotated

import typer

app = typer.Typer()


@app.command()
def main(number: Annotated[list[float], typer.Option()] = []):
    # Typer 将每个 --number 转换为 float，业务层不再手动调用 float。
    total = sum(number)
    # 输出聚合结果，实际项目也可以在这里交给后续业务函数。
    print(f"The sum is {total}")


if __name__ == "__main__":
    # 启动命令行应用。
    app()

# 三个选项对应三个浮点数元素，结果应为 9.5。
uv run python main.py --number 2 --number 3 --number 4.5

这里的关键不是把字符串拆成列表，而是让“一个选项出现一次”成为输入协议的一部分。若用户传入无法转换为浮点数的值，Typer 会在参数解析阶段报错，业务函数不会收到半成品列表。

默认值和版本写法怎么选

需要判断“用户是否传过参数”时，选择 list[str] | None = None，这样 None 有明确语义；如果未传参也应当被当作“空集合”处理，可以选择 list[float] = []。两种写法都围绕同一个重复选项机制，差异在默认值的业务含义。

如果项目还没有使用 Annotated，也可以把 typer.Option 写在默认值位置，例如 user: list[str] = typer.Option([])。新代码优先采用 Annotated 写法，阅读者能同时看到元素类型、可空性和 Typer 元数据。

不要把多个值写成 --user Camila,Rick,Morty 后再自行 split，除非你明确需要逗号协议。自行拆分会带来空格、转义、逗号出现在真实值中的额外规则，而 Typer 的重复 option 已经提供了更清楚的命令行边界。

常见问题

为什么函数参数不是单个字符串？

因为类型声明是列表，Typer 会为每次出现的选项保留一个元素。业务代码应遍历这个列表，而不是再次按逗号切分。

不传参数时应该用 None 还是空列表？

要区分“用户没有提供”就用 None；未传参和空集合在业务上等价时，用空列表更直接。关键是让默认值表达真实业务语义。

总结来说，Python Typer 收集可重复参数的最小做法就是把 option 类型声明为 list[T]，再根据是否需要区分未传参选择 None 或空列表。先用 0、1、3 次出现次数做基线，能快速确认列表长度、顺序和元素类型都符合预期。