Python Typer布尔选项怎样设置正反开关

Python Typer 里的布尔选项本质上是 flag：命令行中出现它就改变一个布尔值，不需要再写 true 或 false。最常见的写法是让 Typer 自动生成一对 --force/--no-force；如果业务词不适合“no-”，则在 typer.Option() 中用斜杠显式写出两侧名称。

官方地址：https://typer.tiangolo.com/tutorial/parameter-types/bool/

先让 bool 参数生成标准正反开关

如果参数名是 force，默认值是 False，Typer 会把它作为一个开关处理。没有传参数时函数收到 False，传入 --force 时收到 True，同时帮助信息通常会展示对应的 --no-force 反向入口。

from typing import Annotated

import typer

app = typer.Typer()


@app.command()
def deploy(
    force: Annotated[
        bool,
        typer.Option(help="跳过可选检查并继续部署"),
    ] = False,
):
    # flag 出现时为 True，未出现时保留默认 False。
    if force:
        print("执行强制部署")
    else:
        print("执行常规部署")


if __name__ == "__main__":
    app()

这里的关键不是把命令行文本解析成字符串，而是让 Typer 根据 Python 类型创建 flag。调用时应写 python main.py --force，不要写成 --force true。如果希望默认打开，则把 Python 默认值改成 True，再根据帮助输出确认反向开关的含义。

用斜杠把开关名称改成业务语义

“启用/禁用”只是技术上的正反，很多命令更适合使用“接受/拒绝”“发布/草稿”这样的领域词。把两个长选项用一个字符串和斜杠分隔，就能让它们写入同一个参数：

from typing import Annotated

import typer

app = typer.Typer()


@app.command()
def review(
    accept: Annotated[
        bool | None,
        typer.Option("--accept/--reject", help="选择审核结果"),
    ] = None,
):
    # None 表示尚未选择，True/False 分别对应两侧业务动作。
    if accept is None:
        print("尚未选择审核结果")
    elif accept:
        print("进入通过流程")
    else:
        print("进入驳回流程")


if __name__ == "__main__":
    app()

帮助信息会呈现 --accept / --reject。用户传 --accept 得到 True，传 --reject 得到 False；两者都不传时仍是 None。这里使用三态类型是有意的：审核命令可能要求用户明确选择，而不是把“没传参数”悄悄当作“拒绝”。

只保留一侧，或同时提供短选项

有些命令只需要一个启用入口，例如默认关闭的 --force。把名称显式写成单个选项后，帮助信息里就不会再提供自动的 --no-force。反过来，如果默认值为 True，想只提供关闭入口，可以使用带空格的 " /--demo" 形式；这个空格是 Typer 语法的一部分，不能省略。

成对开关还可以分别配置短名称：

from typing import Annotated

import typer

app = typer.Typer()


@app.command()
def sync(
    force: Annotated[
        bool,
        typer.Option("--force/--no-force", "-f/-F", help="是否跳过可选检查"),
    ] = False,
):
    # 两个短名称分别映射到 True 和 False，避免把含义交给位置猜测。
    print("强制模式" if force else "普通模式")


if __name__ == "__main__":
    app()

此时 -f 表示 True，-F 表示 False。短选项适合高频命令，但大小写相反容易被误读，生产命令最好同时保留长名称，并在 help 中写出效果。

用检查清单确认默认值和三态边界

最后用 --help 看实际名称，用三种调用方式检查：不传、传正向名称、传反向名称。注意不要在同一次调用中同时传互相冲突的两个 flag，也不要给 flag 追加字符串值；如果命令需要显式接收 true/false 文本，那应设计成字符串或其他值型选项，而不是布尔 flag。

常见问题

Typer 的 bool 选项为什么会出现 --no-xxx？

因为 Typer 将 bool 参数识别为开关，并用正反两侧表达 True 和 False。需要不同命名时，用 --accept/--reject 显式覆盖。

--force 后面需要写 true 吗？

不需要。它是 flag，出现即代表 True；给它追加值会让解析器把后续文本当作多余参数或产生错误。

什么时候应该用 bool | None？

当“未选择”与“明确关闭”会触发不同业务流程时使用，例如审核、发布策略或配置覆盖。普通开关只需 True/False 即可。