脚本参数解析器

该库旨在提供一种在更复杂的场景中使用脚本参数的简单方法，而无需编写太多代码。

为什么还有更多？

在 Python 中，有很多方法可以使用 cli 参数，从内置解析器开始，在 docopt 等库中完成。但不幸的是，在我的冒险过程中，我遇到了一些仅使用其中一个无法解决的问题。这些问题很少：

• 从多个来源获取值：cli、配置文件、环境变量、默认值；
• 根据参数定义转换给定变量；
• 在一处定义的所有参数信息（cli 选项、回退环境变量、转换类型、默认值等）；
• 定义写在代码之外，所以脚本保持简洁；
• 内置更复杂的转换类型。

主要特点

• 在代码之外以人类和计算机可读格式定义的参数，在一个地方
• 转换为给定格式的参数值（预定义或自定义）
• 配置文件回退
• 环境变量回退
• 默认值
• 人类可读错误

用法

该库的目标之一是尽量减少代码量。因此整个用法如下所示：

from script_args_parser import ArgumentsParser

args = ArgumentsParser.from_files('example-parameters.toml', yaml_config='example-config.yaml')
print(args.name)
print(args.age)

上面的脚本将从中读取参数定义example-parameters.toml并尝试按以下顺序读取它们的值：

1. 从 cli 选项，
2. 从配置文件（example-config.yaml例如），
3. 从环境变量，
4. 默认值。

如果任何参数没有定义值，它将为无，除非它是必需的，因此它将引发异常。

当所有值都建立后，解析器会将它们转换为指定的类型。

参数定义

脚本参数列表在 toml 文件中提供。示例参数可能如下所示：

[name]
description = "Some fancy description"  # required
type = "str"   # required
cli_arg = "--cli-opt"  # required
env_var = "ENV_VAR_NAME"
required = false
default_value = "I got you"

说明（必填）

参数的人类可读描述。

类型（必填）

解析器将使用此字段将参数的值从字符串转换为指定的值。

一些更复杂的类型也在改变 cli 选项的解析方式。

有关可能值及其含义的详细说明，请参阅类型部分。

cli_arg （强制）

可以设置值的 cli 选项的名称。

环境变量

如果 CLI 或配置文件未指定，将用于读取值的环境变量的名称。

有关更复杂类型使用的格式，请参阅类型部分。

必需的

默认为假。如果设置为 true，如果在任何地方都找不到值，解析器将引发错误。

可以指定为布尔值（true、false）或字符串（'true'、'false'、'yes'、'no'、'1'、'0'）。

默认值

如果 CLI、配置文件或环境变量未指定将使用的值。

有关更复杂类型使用的格式，请参阅类型部分。

类型

这是支持的内置类型的列表。

细绳

类型字段值：str

不执行特殊操作。

整数

类型字段值：int

值将被解析为整数，如果不可能，将引发异常。

后期操作

post_operations可以使用附加参数。它存储将在读取值后评估的表达式。评估结果将用作值。表达式中的{value}标记将替换为用户提供的值。

例如，当程序需要以秒为单位的值，但用户总是希望指定分钟时，post_operations可以："{value} * 60".

布尔值

类型字段值：bool

一些字符串已定义为与特定值匹配（不区分大小写）：

• True 可以指定为：true, yes, 1；
• False可以指定为：false，no，0；

所有其他值将使用 Python 规则转换为 bool。

转变

类型字段值：switch

行为方式与bool其他 cli 选项相同，但可以不带参数传递，并将被视为 True。

小路

类型字段值：path

将转换为pathlib.Path对象。值得注意的是空字符串将等同于当前目录。

父路径

parent_path可以使用附加参数。它应包含另一个路径参数的名称。当前路径将以 的值作为前缀parent_path。

picture_name对于给定的 toml 文件，默认值为'images/beautiful.jpg'.

[pictures_folder]
description = "Path to folder with pictures"
type = "path"
cli_arg = "--pictures-folder"
default = "./images"

[picture_name]
description = "Name of a picture file"
type = "path"
cli_arg = "--picture-name"
parent_path = "pictures_folder"
default = "beautiful.jpg"

可以创建路径的层次结构，但请记住，对参数进行评估是为了在 toml 文件中定义它们，因此对于下面的 toml 文件picture_name，'the_best_user\beautiful.jpg'即使user_folder是pictures_folder\user_folder.

[pictures_folder]
description = "Path to folder with pictures"
type = "path"
cli_arg = "--pictures-folder"
default = "./images"

[picture_name]
description = "Name of a picture file"
type = "path"
cli_arg = "--picture-name"
parent_path = "user_folder"
default = "beautiful.jpg"

[user_folder]
description = "Name of a user folder file"
type = "path"
cli_arg = "--user-folder"
parent_path = "pictures_folder"
default = "the_best_user"

列表

类型字段值：list[<simple type>]

将生成具有给定简单类型（上述任何类型）的元素列表。

指定此类型时，应使用多个 cli 选项来传递列表元素：

script.py --child-name John --child-name David

在默认值或环境变量中使用分号来拆分值：

default_value = "John; David; 'Some;Very;Strange;Name'"

元组

类型字段值：tuple[<simple type>, <optional simple type>, ...]

示例类型字段值：tuple[str], tuple[int, str, bool].

将生成一个包含给定数量的简单类型元素值的列表。

指定此类型时，cli 选项应使用一次但具有多个值。为了 tuple[str, str, str]

script.py --all-my-names John Maria "De'naban"

在默认值或环境变量中用空格分隔值：

default_value = "John Maria "De'naban"

元组列表

类型字段值：list[tuple[<simple type>, <optional simple type>, ...]]

组合列表和元组类型。将产生一个列表列表。

对于 cli 使用：

script.py --child John 16 --child David 18 --child Maria 21

对于默认值和环境变量，请使用：

default_value = "John 16; David 18; Maria 21"

上面的例子list[tuple[str, int]]将产生：

[['John', 16], ['David', 18], ['Maria', 21]]

数据类参数

类型字段值：<name of the dataclass>

将列表或字典解析为用户定义的数据类。

为了使用数据类，它必须用script_args_parser.decorators.dataclass_argument.

使用给定的 Python 代码和 toml 定义：

@dataclass_argument
@dataclass
class MyDataClass:
    value_1: str
    value_2: str

[two_values]
description = "Some two string values"
type = "MyDataClass"
cli_arg = "--two-values"

可以使用以下 yaml 输入文件

two_values:
  - first_value
  - second value

或者

two_values:
  value_1: first_value
  value_2: second value

该类型也可以用作列表类型参数，例如：

[two_values]
description = "Some two string values"
type = "list[MyDataClass]"
cli_arg = "--two-values"

注意：目前此类型不支持 cli 或 env 值。

计划工作

v1.0之前还需要做的工作

• 列表的默认值和环境
• 元组的默认值和环境
• 元组列表的默认值和环境
• 添加更多元组测试列表
• 添加路径类型（带测试）
• 从路径创建
• 支持配置文件
• 记录可能的类型
• 添加对数据类类型的 env 和 cli 值的支持
• 编写一些复杂的测试用例
• 允许非 cli 参数
• 添加日志记录
• 允许自定义参数类型
• 产生使用量
• 错误处理
• TOML 文件验证
• CI/CD

贡献

现在我想完成我自己的计划并发布1.0版本。如果您有任何建议或发现错误，请随时提交问题，我会尽快查看。

发展

开发文档可以在这里找到