Typer 多值 CLI Option 实战用 tuple 类型声明固定数量、混合类型的多个值【免费下载链接】typerTyper, build great CLIs. Easy to code. Based on Python type hints.项目地址: https://gitcode.com/GitHub_Trending/ty/typer导读在命令行应用中有时一个CLI option选项需要一次性接收多个值例如--user Camila 50 yes中同时包含用户名、金币数和布尔标志。Typer 利用 Python 标准类型提示type hints中的tuple让开发者只需声明一个带固定数量和混合类型的元组就能让单个选项自动接收固定个数的多个值并完成逐项类型转换。读完本文你将掌握tuple[str, int, bool]这类多值选项的声明方式、默认值写法、命令行运行效果、类型转换与参数数量校验的底层原理以及对应的自动化测试用例。本文对应的官方教程原文位于 docs/tutorial/multiple-values/options-with-multiple-values.md完整示例代码可在 docs_src/multiple_values/options_with_multiple_values/ 目录下找到。一、多值 Option 与多值 Argument 的整体定位Typer 在“多值Multiple Values”这一节将相关能力划分为三个主题对应的官方文档分别位于arguments-with-multiple-values.mdCLI argument位置参数接收多个值multiple-options.md同一个option可以多次出现、每次接收一个值options-with-multiple-values.md单个option一次接收固定数量的多个值即本文主题。三者的区别在于“多个值”的组织方式--user a --user b是同一个选项重复出现multiple options而--user a b c是单个选项一次吃进三个值multiple values。本文聚焦最后一种场景其声明的数量与类型可以任意组合但必须是一个固定的数量fixed number of values不能是可变长度的。二、用 tuple 声明多值 Option声明多值option的方式非常简单使用标准 Python 的tuple类型作为参数注解元组内部的每一个类型都定义了对应位置上的值类型。2.1 基于Annotated的推荐写法Python 3.10项目官方示例采用Annotated语法见 docs_src/multiple_values/options_with_multiple_values/tutorial001_an_py310.pyfrom typing import Annotated import typer app typer.Typer() app.command() def main(user: Annotated[tuple[str, int, bool], typer.Option()] (None, None, None)): username, coins, is_wizard user if not username: print(No user provided) raise typer.Abort() print(fThe username {username} has {coins} coins) if is_wizard: print(And this user is a wizard!) if __name__ __main__: app()2.2 等价的直接赋值写法如果不使用Annotated也可以把typer.Option()直接作为默认值见同目录下的 tutorial001_py310.pyimport typer app typer.Typer() app.command() def main(user: tuple[str, int, bool] typer.Option((None, None, None))): username, coins, is_wizard user if not username: print(No user provided) raise typer.Abort() print(fThe username {username} has {coins} coins) if is_wizard: print(And this user is a wizard!) if __name__ __main__: app()两种写法在 Typer 中的行为完全一致选择哪一种取决于团队风格。2.3 类型注解的语义注解user: tuple[str, int, bool]的含义是参数user是一个恰好包含 3 个值的元组第 1 个值是str字符串如用户名第 2 个值是int整数如金币数第 3 个值是bool布尔值如“是否为巫师”。也就是说元组内部的每个类型逐一定义了每个位置的值的类型数量固定、顺序固定、类型也固定。2.4 元组解包函数体内使用了元组解包tuple unpackingusername, coins, is_wizard user它等价于按索引逐个赋值username user[0] coins user[1] is_wizard user[2]即把user元组的三个值依次赋给新变量username、coins、is_wizard之后就能用可读性更好的名字引用它们。三、命令行运行效果将示例保存为main.py后用uv run python main.py运行也可以直接用python main.py取决于你的环境。3.1 查看帮助$ uv run python main.py --help // Notice the str int boolean Usage: main.py [OPTIONS] Options: --user str int boolean... --help Show this message and exit.注意帮助信息中--user后面显示的str int boolean它正是 Typer 根据元组内各类型生成的参数元信息metavar直观地向用户宣告这个选项需要依次提供字符串、整数、布尔值三个参数。3.2 正常传值$ uv run python main.py --user Camila 50 yes The username Camila has 50 coins And this user is a wizard!yes被解析为布尔值True因此额外打印了 “And this user is a wizard!”。3.3 布尔值为否的情况$ uv run python main.py --user Morty 3 no The username Morty has 3 coinsno被解析为False因此不打印巫师提示。3.4 传值数量不足时报错$ uv run python main.py --user Camila 50 Error: Option --user requires 3 arguments只给了 2 个值Typer 会在参数解析阶段直接拒绝并给出清晰的错误信息Option --user requires 3 arguments。这正是“固定数量”约束在运行时的体现。四、源码级原理剖析4.1 元组类型的分派逻辑在 typer/main.py 的get_click_param中Typer 会先取得注解的 origin泛型原始类型若 origin 是list则提取元素类型并标记is_list True若 origin 是tuple则遍历元组的每一个内部类型逐个调用get_click_type生成对应的 Click 参数类型str→STRING、int→INT、bool→BOOL等并组合成一个元组类型的 Click 参数类型同时标记is_tuple True。可见元组中“每个位置一种类型”的能力正是由这段循环逐类型构建 Click 类型元组实现的。值得注意的是源码中还带有断言assert明确说明“当前不支持带复杂子类型的元组/列表类型”即元组内部各元素本身应是str、int、bool、Path等基础可解析类型不能嵌套其他泛型。4.2 固定数量与数量校验在 typer/_click/core.py 中当nargs未显式指定时Click 会取self.type.arity作为默认nargs。对于由多个类型组合成的元组类型其 arity 正好等于元素个数因此--user的nargs被设为 3。后续类型转换阶段Click 校验收到的值数量if len(value) ! self.nargs: # 抛出 Takes X values but Y given 之类的错误这从底层解释了为什么少传一个值会得到Error: Option --user requires 3 arguments。4.3 逐值类型转换器在 typer/main.py 中generate_tuple_convertor(types)会为元组内每个类型生成一个独立的转换器然后用zip把命令行传入的每个原始字符串与对应的转换器一一配对逐个转换后再组装成新的元组return tuple( convertor(arg) if convertor else arg for (convertor, arg) in zip(convertors, param_args, strictFalse) )也就是说50会走int转换器变成50yes/no会走 Typer 的布尔类型转换器变成True/False。默认值(None, None, None)本身不会被转换直接原样使用。4.4 默认值与None的处理示例中默认值是(None, None, None)用户不传--user时user即为这个三元组username为None于是if not username:成立程序打印 “No user provided” 并raise typer.Abort()中止执行。这一模式非常适用于“该选项可选、但必须显式提供有效值”的场景。五、配套测试验证仓库为该示例提供了完整的自动化测试tests/test_tutorial/test_multiple_values/test_options_with_multiple_values/test_tutorial001.py。测试通过pytest参数化同时覆盖了tutorial001_py310与tutorial001_an_py310两种写法主要用例包括test_main不带参数直接运行断言输出包含No user provided与Aborted且退出码非 0test_user_1--user Camila 50 yes断言输出The username Camila has 50 coins与And this user is a wizard!test_user_2--user Morty 3 no断言不出现巫师提示test_invalid_user--user Camila 50少一个值断言输出Option --user requires 3 argumentstest_script以子进程方式运行--help断言输出包含Usage并额外验证默认值(None, None, None)不会以[default: None, None, None]的形式显示在帮助信息中。这些测试既是对示例行为的回归保护也精确对应了上文第 3 节中的每一段终端输出。六、扩展Option 与 Argument 的多值对比如果你希望同样的“固定数量、多种类型”能力用在CLI argument位置参数上可参考同节的 arguments-with-multiple-values.md如果希望一个选项可以被重复传入多个值则参考 multiple-options.md。三者的使用场景互补共同构成了 Typer 处理“多个值”的完整方案。小结在 Typer 中声明多值CLI option只需三步用tuple[T1, T2, ...]注解参数、通过typer.Option()配合Annotated声明为选项、给出一个等长的元组默认值。Typer 会自动完成数量校验与逐类型转换并在帮助信息中展示str int boolean式的参数提示。其底层实现位于 typer/main.py 的元组分派与转换器生成逻辑以及 typer/_click/core.py 的nargs数量校验读者可直接阅读源码进一步深挖。【免费下载链接】typerTyper, build great CLIs. Easy to code. Based on Python type hints.项目地址: https://gitcode.com/GitHub_Trending/ty/typer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Typer 多值 CLI Option 实战：用 tuple 类型声明固定数量、混合类型的多个值
Typer 多值 CLI Option 实战用 tuple 类型声明固定数量、混合类型的多个值【免费下载链接】typerTyper, build great CLIs. Easy to code. Based on Python type hints.项目地址: https://gitcode.com/GitHub_Trending/ty/typer导读在命令行应用中有时一个CLI option选项需要一次性接收多个值例如--user Camila 50 yes中同时包含用户名、金币数和布尔标志。Typer 利用 Python 标准类型提示type hints中的tuple让开发者只需声明一个带固定数量和混合类型的元组就能让单个选项自动接收固定个数的多个值并完成逐项类型转换。读完本文你将掌握tuple[str, int, bool]这类多值选项的声明方式、默认值写法、命令行运行效果、类型转换与参数数量校验的底层原理以及对应的自动化测试用例。本文对应的官方教程原文位于 docs/tutorial/multiple-values/options-with-multiple-values.md完整示例代码可在 docs_src/multiple_values/options_with_multiple_values/ 目录下找到。一、多值 Option 与多值 Argument 的整体定位Typer 在“多值Multiple Values”这一节将相关能力划分为三个主题对应的官方文档分别位于arguments-with-multiple-values.mdCLI argument位置参数接收多个值multiple-options.md同一个option可以多次出现、每次接收一个值options-with-multiple-values.md单个option一次接收固定数量的多个值即本文主题。三者的区别在于“多个值”的组织方式--user a --user b是同一个选项重复出现multiple options而--user a b c是单个选项一次吃进三个值multiple values。本文聚焦最后一种场景其声明的数量与类型可以任意组合但必须是一个固定的数量fixed number of values不能是可变长度的。二、用 tuple 声明多值 Option声明多值option的方式非常简单使用标准 Python 的tuple类型作为参数注解元组内部的每一个类型都定义了对应位置上的值类型。2.1 基于Annotated的推荐写法Python 3.10项目官方示例采用Annotated语法见 docs_src/multiple_values/options_with_multiple_values/tutorial001_an_py310.pyfrom typing import Annotated import typer app typer.Typer() app.command() def main(user: Annotated[tuple[str, int, bool], typer.Option()] (None, None, None)): username, coins, is_wizard user if not username: print(No user provided) raise typer.Abort() print(fThe username {username} has {coins} coins) if is_wizard: print(And this user is a wizard!) if __name__ __main__: app()2.2 等价的直接赋值写法如果不使用Annotated也可以把typer.Option()直接作为默认值见同目录下的 tutorial001_py310.pyimport typer app typer.Typer() app.command() def main(user: tuple[str, int, bool] typer.Option((None, None, None))): username, coins, is_wizard user if not username: print(No user provided) raise typer.Abort() print(fThe username {username} has {coins} coins) if is_wizard: print(And this user is a wizard!) if __name__ __main__: app()两种写法在 Typer 中的行为完全一致选择哪一种取决于团队风格。2.3 类型注解的语义注解user: tuple[str, int, bool]的含义是参数user是一个恰好包含 3 个值的元组第 1 个值是str字符串如用户名第 2 个值是int整数如金币数第 3 个值是bool布尔值如“是否为巫师”。也就是说元组内部的每个类型逐一定义了每个位置的值的类型数量固定、顺序固定、类型也固定。2.4 元组解包函数体内使用了元组解包tuple unpackingusername, coins, is_wizard user它等价于按索引逐个赋值username user[0] coins user[1] is_wizard user[2]即把user元组的三个值依次赋给新变量username、coins、is_wizard之后就能用可读性更好的名字引用它们。三、命令行运行效果将示例保存为main.py后用uv run python main.py运行也可以直接用python main.py取决于你的环境。3.1 查看帮助$ uv run python main.py --help // Notice the str int boolean Usage: main.py [OPTIONS] Options: --user str int boolean... --help Show this message and exit.注意帮助信息中--user后面显示的str int boolean它正是 Typer 根据元组内各类型生成的参数元信息metavar直观地向用户宣告这个选项需要依次提供字符串、整数、布尔值三个参数。3.2 正常传值$ uv run python main.py --user Camila 50 yes The username Camila has 50 coins And this user is a wizard!yes被解析为布尔值True因此额外打印了 “And this user is a wizard!”。3.3 布尔值为否的情况$ uv run python main.py --user Morty 3 no The username Morty has 3 coinsno被解析为False因此不打印巫师提示。3.4 传值数量不足时报错$ uv run python main.py --user Camila 50 Error: Option --user requires 3 arguments只给了 2 个值Typer 会在参数解析阶段直接拒绝并给出清晰的错误信息Option --user requires 3 arguments。这正是“固定数量”约束在运行时的体现。四、源码级原理剖析4.1 元组类型的分派逻辑在 typer/main.py 的get_click_param中Typer 会先取得注解的 origin泛型原始类型若 origin 是list则提取元素类型并标记is_list True若 origin 是tuple则遍历元组的每一个内部类型逐个调用get_click_type生成对应的 Click 参数类型str→STRING、int→INT、bool→BOOL等并组合成一个元组类型的 Click 参数类型同时标记is_tuple True。可见元组中“每个位置一种类型”的能力正是由这段循环逐类型构建 Click 类型元组实现的。值得注意的是源码中还带有断言assert明确说明“当前不支持带复杂子类型的元组/列表类型”即元组内部各元素本身应是str、int、bool、Path等基础可解析类型不能嵌套其他泛型。4.2 固定数量与数量校验在 typer/_click/core.py 中当nargs未显式指定时Click 会取self.type.arity作为默认nargs。对于由多个类型组合成的元组类型其 arity 正好等于元素个数因此--user的nargs被设为 3。后续类型转换阶段Click 校验收到的值数量if len(value) ! self.nargs: # 抛出 Takes X values but Y given 之类的错误这从底层解释了为什么少传一个值会得到Error: Option --user requires 3 arguments。4.3 逐值类型转换器在 typer/main.py 中generate_tuple_convertor(types)会为元组内每个类型生成一个独立的转换器然后用zip把命令行传入的每个原始字符串与对应的转换器一一配对逐个转换后再组装成新的元组return tuple( convertor(arg) if convertor else arg for (convertor, arg) in zip(convertors, param_args, strictFalse) )也就是说50会走int转换器变成50yes/no会走 Typer 的布尔类型转换器变成True/False。默认值(None, None, None)本身不会被转换直接原样使用。4.4 默认值与None的处理示例中默认值是(None, None, None)用户不传--user时user即为这个三元组username为None于是if not username:成立程序打印 “No user provided” 并raise typer.Abort()中止执行。这一模式非常适用于“该选项可选、但必须显式提供有效值”的场景。五、配套测试验证仓库为该示例提供了完整的自动化测试tests/test_tutorial/test_multiple_values/test_options_with_multiple_values/test_tutorial001.py。测试通过pytest参数化同时覆盖了tutorial001_py310与tutorial001_an_py310两种写法主要用例包括test_main不带参数直接运行断言输出包含No user provided与Aborted且退出码非 0test_user_1--user Camila 50 yes断言输出The username Camila has 50 coins与And this user is a wizard!test_user_2--user Morty 3 no断言不出现巫师提示test_invalid_user--user Camila 50少一个值断言输出Option --user requires 3 argumentstest_script以子进程方式运行--help断言输出包含Usage并额外验证默认值(None, None, None)不会以[default: None, None, None]的形式显示在帮助信息中。这些测试既是对示例行为的回归保护也精确对应了上文第 3 节中的每一段终端输出。六、扩展Option 与 Argument 的多值对比如果你希望同样的“固定数量、多种类型”能力用在CLI argument位置参数上可参考同节的 arguments-with-multiple-values.md如果希望一个选项可以被重复传入多个值则参考 multiple-options.md。三者的使用场景互补共同构成了 Typer 处理“多个值”的完整方案。小结在 Typer 中声明多值CLI option只需三步用tuple[T1, T2, ...]注解参数、通过typer.Option()配合Annotated声明为选项、给出一个等长的元组默认值。Typer 会自动完成数量校验与逐类型转换并在帮助信息中展示str int boolean式的参数提示。其底层实现位于 typer/main.py 的元组分派与转换器生成逻辑以及 typer/_click/core.py 的nargs数量校验读者可直接阅读源码进一步深挖。【免费下载链接】typerTyper, build great CLIs. Easy to code. Based on Python type hints.项目地址: https://gitcode.com/GitHub_Trending/ty/typer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
