Confection: Python 最甜蜜的配置系统

confection :candy: 是一个轻量级库，提供了一个配置系统，让你可以方便地描述任意对象树。

配置对于机器学习代码来说是一个巨大的挑战，因为你可能想要将任何函数的几乎所有细节作为超参数暴露出来。你想要暴露的设置可能在调用栈的任意深处，所以它可能需要从 CLI 或 REST API 一直传递下去，通过任意数量的中间函数，影响沿途的所有接口。一旦添加了这些设置，以后就很难删除。默认值也变得难以更改而不破坏向后兼容性。

为了解决这个问题，confection 提供了一个配置系统，让你可以轻松描述任意对象树。可以通过使用简单的装饰器语法注册的函数调用来创建对象。你甚至可以对创建的函数进行版本控制，允许你在不破坏向后兼容性的情况下进行改进。我们所知的最相似的配置系统是 Gin，它使用类似的语法，也允许你使用装饰器将配置系统链接到代码中的函数。confection 的配置系统更简单，通过 Gin 功能的一个子集强调了不同的工作流程。

⏳ 安装

pip install confection

conda install -c conda-forge confection

👩‍💻 使用方法

配置系统解析一个类似这样的 .cfg 文件：

[training]
patience = 10
dropout = 0.2
use_vectors = false

[training.logging]
level = "INFO"

[nlp]
# 这里使用 training.use_vectors 的值
use_vectors = ${training.use_vectors}
lang = "en"

并将其解析为一个 Dict：

{
  "training": {
    "patience": 10,
    "dropout": 0.2,
    "use_vectors": false,
    "logging": {
      "level": "INFO"
    }
  },
  "nlp": {
    "use_vectors": false,
    "lang": "en"
  }
}

配置被分为多个部分，部分名称用方括号括起来 - 例如，[training]。在各个部分内，可以使用 = 将配置值分配给键。也可以使用点号表示法和由美元符号和大括号指示的占位符从其他部分引用值。例如，${training.use_vectors} 将接收 training 块中 use_vectors 的值。这对于在组件之间共享的设置很有用。

配置格式与 Python 内置的 configparser 有三个主要区别：

JSON 格式的值。confection 将所有值通过 json.loads 传递以解释它们。你可以使用原子值，如字符串、浮点数、整数或布尔值，也可以使用复杂对象，如列表或映射。
结构化部分。confection 使用点号表示法来构建嵌套部分。如果你有一个名为 [section.subsection] 的部分，confection 将把它解析成一个嵌套结构，将 subsection 放在 section 内。
对注册函数的引用。如果一个键以 @ 开头，confection 会将其值解释为函数注册表的名称，加载为该名称注册的函数，并将块的其余部分作为参数传入。如果函数有类型提示，参数值（和函数的返回值）将根据这些提示进行验证。这让你可以表达复杂的配置，比如一个训练流水线，其中 batch_size 由一个产生浮点数的函数填充。

没有预定义的方案你必须遵循；如何设置顶级部分由你决定。最后，你将收到一个包含这些值的字典，你可以在脚本中使用 - 无论是完全初始化的函数，还是只是基本设置。

例如，假设你想定义一个新的优化器。你可以在 config.cfg 中这样定义它的参数：

[optimizer]
@optimizers = "my_cool_optimizer.v1"
learn_rate = 0.001
gamma = 1e-8

要使用 catalogue 注册表加载和解析这个配置（需要单独安装 catalogue）：

import dataclasses
from typing import Union, Iterable
import catalogue
from confection import registry, Config

# 创建一个新的注册表
registry.optimizers = catalogue.create("confection", "optimizers", entry_points=False)


# 定义一个虚拟优化器类
@dataclasses.dataclass
class MyCoolOptimizer:
    learn_rate: float
    gamma: float


@registry.optimizers.register("my_cool_optimizer.v1")
def make_my_optimizer(learn_rate: Union[float, Iterable[float]], gamma: float):
    return MyCoolOptimizer(learn_rate, gamma)


# 从磁盘加载配置文件，解析它并获取实例化的优化器对象
config = Config().from_disk("./config.cfg")
resolved = registry.resolve(config)
optimizer = resolved["optimizer"]  # MyCoolOptimizer(learn_rate=0.001, gamma=1e-08)

⚠️ 注意：类型检查器（如 mypy）会将以这种方式向 registry 添加新属性（即 registry.new_attr = ...）标记为错误。这是因为在初始化后向类添加了新属性。如果你使用类型检查器，你可以忽略这个错误（例如，对于 mypy 使用 # type: ignore），或者使用类型安全的替代方法：不使用 registry.new_attr = ...，而使用 setattr(registry, "new_attr", ...)。

在内部，confection 将在 "optimizers" 注册表中查找 "my_cool_optimizer.v1" 函数，然后用参数 learn_rate 和 gamma 调用它。如果函数有类型注解，它还会验证输入。例如，如果 learn_rate 被注解为 float，而配置定义了一个字符串，confection 将引发一个错误。

Thinc 文档提供了有关配置系统的更多信息：

🎛 API

<kbd>class</kbd> `Config`

这个类保存模型和训练配置，可以从/到字符串、文件或字节加载和保存 INI 风格的配置格式。Config 类是 dict 的子类，内部使用 Python 的 ConfigParser。

<kbd>method</kbd> `Config.init`

用可选数据初始化一个新的 Config 对象。

from confection import Config
config = Config({"training": {"patience": 10, "dropout": 0.2}})

参数	类型	描述
`data`	`Optional[Union[Dict[str, Any], Config]]`	用于初始化配置的可选数据。
`section_order`	`Optional[List[str]]`	按顺序排列的顶级部分名称，用于排序保存和加载的配置。所有其他部分将按字母顺序排序。
`is_interpolated`	`Optional[bool]`	配置是否已插值或是否包含变量。如果 `data` 是 `Config` 实例，则从中读取，否则默认为 `True`。

<kbd>method</kbd> `Config.from_str`

从字符串加载配置。

from confection import Config

config_str = """
[training]
patience = 10
dropout = 0.2
"""
config = Config().from_str(config_str)
print(config["training"])  # {'patience': 10, 'dropout': 0.2}}

参数	类型	描述
`text`	`str`	要加载的字符串配置。
`interpolate`	`bool`	是否插值类似 `${section.key}` 的变量。默认为 `True`。
`overrides`	`Dict[str, Any]`	值和部分的覆盖。键以点号表示法提供，例如 `"training.dropout"` 映射到值。
返回	`Config`	加载的配置。

<kbd>method</kbd> `Config.to_str`

将配置加载为字符串。

from confection import Config

config = Config({"training": {"patience": 10, "dropout": 0.2}})
print(config.to_str()) # '[training]\npatience = 10\n\ndropout = 0.2'

参数	类型	描述
`interpolate`	`bool`	是否插值类似 `${section.key}` 的变量。默认为 `True`。
返回	`str`	字符串配置。

<kbd>method</kbd> `Config.to_bytes`

将配置序列化为字节字符串。

from confection import Config

config = Config({"training": {"patience": 10, "dropout": 0.2}})
config_bytes = config.to_bytes()
print(config_bytes)  # b'[training]\npatience = 10\n\ndropout = 0.2'

参数	类型	描述
`interpolate`	`bool`	是否插值类似 `${section.key}` 的变量。默认为 `True`。
`overrides`	`Dict[str, Any]`	值和部分的覆盖。键以点号表示法提供，例如 `"training.dropout"` 映射到值。
返回	`str`	序列化的配置。

<kbd>方法</kbd> `Config.from_bytes`

从字节字符串加载配置。

from confection import Config

config = Config({"training": {"patience": 10, "dropout": 0.2}})
config_bytes = config.to_bytes()
new_config = Config().from_bytes(config_bytes)

参数	类型	描述
`bytes_data`	`bool`	要加载的数据。
`interpolate`	`bool`	是否插值如 `${section.key}` 的变量。默认为 `True`。
返回值	`Config`	加载的配置。

<kbd>方法</kbd> `Config.to_disk`

将配置序列化到文件。

from confection import Config

config = Config({"training": {"patience": 10, "dropout": 0.2}})
config.to_disk("./config.cfg")

参数	类型	描述
`path`	`Union[Path, str]`	文件路径。
`interpolate`	`bool`	是否插值如 `${section.key}` 的变量。默认为 `True`。

<kbd>方法</kbd> `Config.from_disk`

从文件加载配置。

from confection import Config

config = Config({"training": {"patience": 10, "dropout": 0.2}})
config.to_disk("./config.cfg")
new_config = Config().from_disk("./config.cfg")

参数	类型	描述
`path`	`Union[Path, str]`	文件路径。
`interpolate`	`bool`	是否插值如 `${section.key}` 的变量。默认为 `True`。
`overrides`	`Dict[str, Any]`	值和部分的覆盖。键以点号表示法提供，例如 `"training.dropout"` 映射到相应的值。
返回值	`Config`	加载的配置。

<kbd>方法</kbd> `Config.copy`

深度复制配置。

参数	类型	描述
返回值	`Config`	复制的配置。

<kbd>方法</kbd> `Config.interpolate`

插值如 ${section.value} 或 ${section.subsection} 的变量，并返回带有插值后值的配置副本。可用于以 interpolate=False 加载的配置，例如通过 Config.from_str。

from confection import Config

config_str = """
[hyper_params]
dropout = 0.2

[training]
dropout = ${hyper_params.dropout}
"""
config = Config().from_str(config_str, interpolate=False)
print(config["training"])  # {'dropout': '${hyper_params.dropout}'}}
config = config.interpolate()
print(config["training"])  # {'dropout': 0.2}}

参数	类型	描述
返回值	`Config`	带有插值后值的配置副本。

<kbd>方法</kbd> `Config.merge`

深度合并两个配置对象，使用当前配置作为默认值。只合并部分和字典，不合并其他值如列表。更新中提供的值会覆盖基础配置中的值，任何新的值或部分都会被添加。如果配置值是一个变量，如 ${section.key}（例如，如果配置以 interpolate=False 加载），变量会被优先保留，即使更新提供了不同的值。这确保变量引用不会被合并破坏。

:warning: 注意，使用 @ 语法引用注册函数的块只有在它们引用相同函数时才会被合并。否则，合并可能会轻易产生无效配置，因为不同的函数可能接受不同的参数。如果一个块引用了不同的函数，它会被覆盖。

from confection import Config

base_config_str = """
[training]
patience = 10
dropout = 0.2
"""
update_config_str = """
[training]
dropout = 0.1
max_epochs = 2000
"""

base_config = Config().from_str(base_config_str)
update_config = Config().from_str(update_config_str)
merged = Config(base_config).merge(update_config)
print(merged["training"])  # {'patience': 10, 'dropout': 0.1, 'max_epochs': 2000}

参数	类型	描述
`overrides`	`Union[Dict[str, Any], Config]`	要合并到配置中的更新。
返回值	`Config`	包含合并后配置的新配置实例。

配置属性

参数	类型	描述
`is_interpolated`	`bool`	配置值是否已经被插值。默认为 `True`，如果配置以 `interpolate=False` 加载（例如使用 `Config.from_str`），则设置为 `False`。