Cock

Cock代表“configuration file with click”。它是一个配置聚合器，基于光鲜的click库。

原因

没有与平坦配置文件配合使用的click模块，该文件将模仿实际的click选项。有click-config和click-config-file，但它们针对不同的目标。

功能

• 将配置文件和cli选项聚合到平坦的配置对象中。
• 尊重所有click检查和转换（禁止required属性，因为它会破坏内部逻辑）。
• 类似于dict的平坦、排序、点访问配置对象。
• 入口点构建器。

许可

cock根据MIT许可提供。

要求

• python 3.7+

用法

from cock import build_entrypoint, Config, Option


def main(config: Config):
    print(config)


options = [
    Option("a_b_c", default="foo"),
    Option("b_c_d", default="bar"),
]
entrypoint = build_entrypoint(main, options, auto_envvar_prefix="EXAMPLE", show_default=True)

if __name__ == "__main__":
    entrypoint(prog_name="example")

这是一个几乎纯click设置

$ python example.py --help
Usage: example [OPTIONS] [CONFIGURATION_FILE]

Options:
  --a-b-c TEXT  [default: foo]
  --b-c-d TEXT  [default: bar]
  --help        Show this message and exit.  [default: False]

但是有一个CONFIGURATION_FILE参数。让我们看看用例。

所有默认值

$ python example.py
{'configuration_file': None, 'a_b_c': 'foo', 'b_c_d': 'bar'}

从环境变量

$ EXAMPLE_A_B_C=foo-env python example.py
{'configuration_file': None, 'a_b_c': 'foo-env', 'b_c_d': 'bar'}

从cli参数

$ EXAMPLE_A_B_C=foo-env python example.py --a-b-c foo-cli
{'a_b_c': 'foo-cli', 'configuration_file': None, 'b_c_d': 'bar'}

从配置yaml文件

a-b-c: foo-file

$ EXAMPLE_A_B_C=foo-env python example.py --a-b-c foo-cli config-example.yml
{'a_b_c': 'foo-file', 'configuration_file': '/absolute/path/to/config-example.yml', 'b_c_d': 'bar'}

优先级很明显： 文件 > cli参数 > 环境变量

注意：对于文件a-b-c与a_b_c或a-b_c相同。使用您喜欢的任何一种。

如功能段落所述，配置在链式与click选项之前会先被扁平化。所以下面列出的所有配置文件都是相等的

a_b_c: foo-file

a:
  b:
    c: foo-file

a-b:
  c: foo-file

如果提供的文件有键冲突

a-b_c: foo-file1
a:
  b-c: foo-file2

则将引发RuntimeError。

cock使用pyyaml库来加载配置，因此支持yaml和json格式，但如果有需要更多配置文件类型的用户，这可以在以后得到改进。

配置也可以定义为字典

from cock import build_entrypoint, Option, Config


def main(config: Config):
    print(config)


options = {
    "a": {
        "b": {
            "c": Option(default="foo"),
        },
    },
    "a-b_d": Option(default="bar"),
}
entrypoint = build_entrypoint(main, options, auto_envvar_prefix="EXAMPLE", show_default=True)

if __name__ == "__main__":
    entrypoint(prog_name="example")

注意：对于字典，您可以使用与文件相同的命名和结构规则。

配置可以定义为多个来源

from cock import build_entrypoint, Option, Config


def main(config: Config):
    print(config)


dict_options = {"a-b-c": Option(default="foo")}
list_options = [Option("b_c-d", default="bar")]
entrypoint = build_entrypoint(main, dict_options, list_options,
                              auto_envvar_prefix="EXAMPLE", show_default=True)

if __name__ == "__main__":
    entrypoint(prog_name="example")

您还可以将所有默认值聚合为Config

from cock import get_options_defaults, Option

options = {
    "a": {
        "b": {
            "c": Option(default="foo"),
        },
    },
}
config = get_options_defaults(options)
assert config == {"a_b_c": "foo"}
assert config.a_b_c == "foo"

Config 是 sortedcontainers.SortedDict 的扩展版本（支持点访问）。

>>> from cock import Config
>>> c = Config(b=1, a=2)
Config({'a': 2, 'b': 1})
>>> c["a"], c.b
(2, 1)
>>> c.z
...
KeyError: 'z'
>>> c.items()
SortedItemsView(Config({'a': 2, 'b': 1}))
>>> c["0"] = 0
>>> c
Config({'0': 0, 'a': 2, 'b': 1})

API

def build_entrypoint(
    main: Callable[[Config], Any],
    *options_stack: Union[dict, List[Union[Option, click.option]]],
    **context_settings
) -> Callable[..., Any]:

• main 是一个用户空间函数，接受一个参数，即点访问配置包装器。
• *options_stack 是一系列上面描述的字典和/或列表。
• **context_settings 传递给 click.command 装饰器。

def get_options_defaults(
    *options_stack: Union[dict, List[Union[Option, click.option]]]
) -> Config:

• *options_stack 是一系列上面描述的字典和/或列表。

class Option(
    name: Optional[str] = None,
    **attributes)

• name 是结果 Config 对象中的一个名称，该名称传递给 main。
  • name 只能设置一次，进一步设置将导致异常。
  • name 字段将被转换为“下划线”视图（例如，内部将 a-b_c 转换为 a_b_c）。
• **attributes 传递给 click.option 装饰器。
  • 禁止 required 属性，因为它会破坏内部逻辑。

弃用和移除

0.11.0

弃用

• 将 click.option 作为选项使用。
• build_options_from_dict 函数，因为它在新 API 中已过时。