msrc-appconfig

Python中的类型安全可组合配置管理

该软件包从多个来源编排应用程序配置：内置应用程序默认值；.ini、JSON和YAML配置文件；shell环境变量；命令行参数。

所有配置值都会进行检查并转换为适当的类型，从而允许在应用程序代码中更安全地使用。

该模块允许轻松设置配置为全局共享配置对象，从而可以从应用程序代码的不同部分轻松访问。

配置对象还可以在本地和云中序列化和跨进程共享。

入门

使用pip install msrc-appconfig安装软件包。

配置架构是一个具有类型属性和内置默认值的类定义。

import typing

class AppConfig(typing.NamedTuple):
    app_name: str = "Sample"
    repeat: int = 1

使用gather_config函数从该架构编译配置对象。

from msrc.appconfig import gather_config

def main(app_config: AppConfig):
    for i in range(app_config.repeat):
        print("Hello from", app_config.app_name)


if __name__ == '__main__':
    app_config = gather_config(AppConfig, arg_aliases=dict(n='app_name'))
    main(app_config)

如果上述代码位于名为getting_started.py的文件中，则可以运行它

>python getting_started.py 
INFO:msrc.appconfig:logging level set to INFO.
Hello from Sample

现在尝试以下命令

>python sample.py -h
usage: getting_started.py [-h [OPTION]] [-l LEVEL|FILE]
                          [-c CONF_FILE [CONF_FILE ...]] [-e PREFIX]

optional arguments:
  -h [OPTION], --help [OPTION]
                        Prints this help message and optionally description of an     
                        option.
  -l LEVEL|FILE         Either logging level or a path to a logging configuration     
                        file.
  -c CONF_FILE [CONF_FILE ...]
                        Additional configuration files. Allowed formats are JSON or   
                        YAML.
  -e PREFIX             Prefix for shell variables to look at. If environment
                        contains <PREFIX>_<ELEMENT_NAME>=VALUE the VALUE
                        overrides corresponding configuration element. The
                        default prefix is GETTING_STARTED_. A prefix of sole
                        dash disables the environment lookup.
Additionally, you may specify the following options. Use '--help OPTION_NO_DASHES' to 
get help on an option marked (*).
-n STR, --app_name STR, --app-name STR
--repeat INT

>GETTING_STARTED_REPEAT=3 python getting_started.py -l debug -n "another example"
INFO:msrc.appconfig:logging level set to DEBUG.
DEBUG:msrc.appconfig:Examining shell variables starting with GETTING_STARTED_.
DEBUG:msrc.appconfig:Shell variable GETTING_STARTED_repeat=3.
DEBUG:msrc.appconfig:discovered app_name = 'another example' from argv
INFO:msrc.appconfig:final repeat = 3 from env > GETTING_STARTED_repeat
INFO:msrc.appconfig:final app_name = 'another example' from argv
Hello from another example
Hello from another example
Hello from another example

最后一条命令表明您可以使用环境变量来设置配置值。在Windows上，应该使用两条命令运行示例。首先，使用SET GETTING_STARTED_REPEAT=3设置环境变量，然后按照所示运行Python脚本。

您还可以将配置值放在文件中，并在代码或命令行中指定这些文件名。例如，创建一个名为sample.yaml的文件。

app_name: getting started
repeat: 2

然后继续命令行会话（在Windows上，首先使用SET GETTING_STARTED_REPEAT=取消设置环境变量）。

>python getting_started.py -l warn -c sample.yaml
Hello from getting started
Hello from getting started

注意，使用-l参数可以控制记录的详细程度。可选的功能参数gather_config(log_level=logging.WARN,...)具有类似的效果。

配置模式

模式是一个类定义，用作应用程序配置的模板。该包使用自省来构建配置模式元素列表，然后从不同的源读取配置数据。

默认情况下，该包接受使用typing.NamedTuple创建的配置模式。上面的示例显示，对于每个元素，配置模式包含一个名称、一个类型和一个默认值。默认值是可选的，尽管您应该谨慎地混合带有和没有默认值的元素。对于命名元组，所有没有默认值的元素都必须在具有默认值的元素之前。如果一个元素没有默认值，其值必须在配置源之一中存在。否则，gather_config()将停止运行脚本。

该包仅接受以下类型的元素

• 简单类型：str、int、float、bool，任何枚举。
• 简单类型的统一元组。这些使用typing.Tuple泛型类型进行注解。例如，Tuple[int, int]是一对整数，Tuple[str, ...]是任何长度的字符串元组，包括空元组。
• 其他应用程序配置模式类。这允许组合模式。

所有其他类型在调用gather_config()和其他需要自省的包函数时将引发错误。

可选元数据

可用的插件

Appconfig插件允许使用命名元组之外的机制声明应用程序配置模式。

数据类

msrc.appconfig.dataclasses适用于Python 3.7及以上版本。它允许使用@dataclass装饰器进行更灵活的配置声明。与命名元组相比，这种方法允许构建应用程序配置的继承树。将应用程序配置声明为“冻结”对象是一种良好的做法。这可以防止在应用程序运行过程中意外更改配置值。以下是一个使用dataclasses声明appconfig模式的示例。

from dataclasses import dataclass, field

@dataclass(frozen=True)
class AppConfig:
    no_default: str
    with_default: repeat = 3
    with_help: bool = field(default=False, metadata=dict(help="description of the flag"))
    secret_password: str = attr.id(repr=False)

要使用dataclasses模式，在安装msrc.appconfig时指定额外内容。

>pip install msrc-appconfig[dataclasses]

或者，作为单独的包安装msrc-appconfig-dataclasses。

属性

msrc.appconfig.attrs在attrs上增加了额外的外部依赖。

该包是dataclasses的前身。它适用于所有Python版本，并且更加灵活。以下是如何使用attrs声明appconfig模式的示例。

import attrs

@attr.s(frozen=True, kw_only=True, auto_attribs=True)
class AppConfig:
    no_default: str
    with_default: repeat = 3
    with_help: bool = attr.ib(default=False, metadata=dict(help="description of the flag"))
    secret_password: str = attr.id(repr=False)

要使用attrs模式，在安装msrc.appconfig时指定额外内容。

>pip install msrc-appconfig[attrs]

或者，作为单独的包安装msrc-appconfig-attrs。

参数

msrc.appconfig.param在param包上增加了额外的外部依赖。应用程序配置类必须从param.Parameterized继承。对于固定大小的元组，param包仅支持float类型（ParamNumeric()）。未绑定大小的元组编码为ParamList(class_=<type>)。

要使用 param 架构，在安装 msrc.appconfig 时指定额外参数。

>pip install msrc-appconfig[param]

或者，作为单独的包安装 msrc-appconfig-param。

配置来源

默认配置来源是架构本身，您在其中定义默认值。值将按以下顺序覆盖

• gather_config() 参数中的 override_defaults 字典；
• 配置文件；
• shell 变量，也称为环境变量；
• 命令行参数。

文件

该模块读取 configparser（.ini），JSON（.json）和 YAML（.yaml，.yml）文件。

可以使用 config_files 可选参数指定要读取的文件列表：gather_config(config_files=[...], ...)，以及使用 -c 命令行选项，它接受一个或多个文件路径。注意，相对路径对于 config_files= 是相对于主脚本目录解析的，对于 -c 是相对于当前工作目录。

您可以使用实用函数启用默认配置文件：gather_config(config_files=script_config_file(), ...)。如果您现在运行 python sample.py，默认配置文件可以是同一目录中的 sample.yaml（或 .json、.ini、.yml）。如果您运行 python -m msrc.example，文件可以是当前目录中的 example.json（或 .yaml、.ini）。

另一个实用函数使得使用层次配置变得简单。如果您启动一个脚本 /foo/bar/script.py，并且该脚本调用 gather_config(config_files=config_files_in_parents('config.json'), ...)，那么该函数将查找 /config.json、/foo/config.json、/foo/bar/config.json，如果它们存在，则按此顺序读取这些文件。

在任何配置文件中，您还可以使用 _include 元素引用其他配置文件。此元素的值是读取的路径或路径列表。相对路径相对于包含文件的位置解析。包含的文件在处理父文件其余部分之前被读取，即文件中的其他元素可以覆盖 _include 中提到的值。

shell 变量

具有类似于 <prefix><element> = <value> 名称的 shell 变量覆盖配置元素 <element> 的值。如果您运行 python sample.py，则默认前缀是 SAMPLE_。如果您运行 python -m msrc.example，则前缀是 EXAMPLE_。您还可以使用 env_var_prefix= 函数参数或 -e 命令行选项指定另一个前缀。单个短横线有一个特殊含义，它禁用了环境变量的使用。

对于元组，shell 变量值应包含由空格分隔的所有元组值。例如，对于脚本 script.py，要指定名为 limits 的配置元素的值为一对数字，环境变量可能看起来像 script_limits=-1.5 2.56。如果元组类型为 str，并且字符串值中必须包含空格，则将值放在双引号内，双引号本身用 '\"' 引用，反斜杠用 '\\' 引用，例如 script_paths=C:\Windows "\"C:\\Program Files\""

命令行参数

对于浮点值，任何有效的正数都可以正常工作，以及特殊值 nan 和 inf。负数以负号开头，argparse 将其视为选项而不是值。一种解决方案是在值前面放置空格，例如 python script.py --interval " -1.5" 2.5。

对于枚举，您可以提供枚举名称或其值，优先考虑名称。

对于元组，选项期望多个参数。

默认值为 False 的布尔元素可以用作标志，例如，如果选项存在但没有参数，则元素的值被设置为 True。在任何情况下，您也可以提供一个参数。任何以 't' 或 'y' 开头的字符串都被解释为 True，例如 'true' 或 'Yes'。任何以 'f' 或 'n' 开头的字符串都被解释为 False，例如 'F' 或 'no'。