confection

糖果：Python的最甜的配置系统

confection ？是一个轻巧的库，提供配置系统，可让您方便地描述对象的任意树。

对于机器学习代码，配置是一个巨大的挑战，因为您可能需要将任何功能的任何细节视为超参数。您要公开的设置可能任意地在您的呼叫堆栈中，因此它可能需要通过任何数量的中间功能一直通过CLI或REST API传递，从而影响了沿途所有事物的接口。然后，一旦添加了这些设置，它们就会很难删除。默认值也很难在不向后兼容的情况下更改。

为了解决此问题， confection提供了一个配置系统，可让您轻松地描述对象的任意树。可以通过函数调用您使用简单的装饰器语法进行注册。您甚至可以版本创建的功能，从而可以进行改进而不向后兼容。我们知道的最相似的配置系统是使用类似语法的Gin，还允许您使用装饰器将配置系统链接到代码中的功能。 confection的配置系统更简单，并通过杜松子酒功能的子集强调了不同的工作流程。

⏳安装

PIP安装糖果

conda安装-c conda -forge糖果

用法

配置系统.cfg

 [训练]耐心= 10Dropout = 0.2USE_VECTORS = false [triaghting.logging] level =“ info” [nlp]＃这使用训练的值

并将其解析为一个Dict ：

 {“训练”：{“耐心”：10，“辍学”：0.2，“ use_vectors”：false，“登录”：{“ level”：“ info”}
  }，“ nlp”：{“ use_vectors”：false，“ lang”：“ en”
  }
}

该配置分为各节，并在方括号中使用截面名称，例如[training] 。在各节中，可以使用=将配置值分配给密钥。还可以使用点表示法和占位符以美元符号和卷发括号指示的占位符从其他部分中引用值。例如， ${training.use_vectors}将在培训块中接收use_vectors的值。这对于跨组件共享的设置很有用。

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

1. JSON形式的值。 confection通过json.loads负载通过所有值来解释它们。您可以使用字符串，浮点，整数或布尔值等原子值，也可以使用列表或地图之类的复杂对象。

2. 结构化部分。 confection使用点符号来构建嵌套部分。如果您有一个名为[section.subsection]的部分， confection将将其分解为嵌套结构，将小节放置在章节中。

3. 参考注册表功能。如果密钥以@开头， confection将其值解释为函数注册表的名称，请加载为该名称注册的函数，然后将其作为参数中的其余部分传递。如果类型提示在函数上可用，则将对其进行验证参数值（以及函数的返回值）。这使您可以表达复杂的配置，例如训练管道，该管道将batch_size由产生浮子的函数填充。

您没有必须遵循预定义的计划；您如何设置顶级部分取决于您。最后，您将收到一个具有脚本中可以使用的值的字典 - 无论是完整的初始化函数还是基本的设置。

例如，假设您要定义一个新的优化器。您会在config.cfg中定义其参数：

 [优化器] @optimizers =“ my_cool_optimizer.v1” learn_rate = 0.001gamma = 1e-8

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

从输入导入联合，iToshimport catalogue frof catalogue intum incort注册表，config＃创建新的registry.registry.optimizers = catalogue.create（“糖果”，“优化_points”，entry_points = false）＃定义一个dummy optimizer类。 mycooloptimizer：Learn_rate：floatgamma： [email protected]（“ my_cool_optimizer.v1”）def make_my_optimizer（Learn_rate：union [float，itoble [float]]，gamma：float：float）：return mycooloptimizer（return mycooloptimizer（learn _rate）它并获取实例化的优化对象.config = config（）。from_disk（“ ./ config.cfg”）resolved = gubistry.resolve（config）optimizer = nesolved [“ optimizer”]＃myCoolOptimizer（learn_rate = 0.001，gamma = 1e-08）

配x注意：类型检查器（例如mypy将标记以这种方式向registry中添加新属性-IE registry.new_attr = ...作为错误。这是因为初始化后，将新属性添加到类中。如果您使用的是Typecheckers，则可以忽略此（例如使用# type: ignore mypy ）或使用typeafe替代方案：而不是registry.new_attr = ... ，使用setattr(registry, "new_attr", ...) 。

在引擎盖下， confection将在“优化器”注册表中查找"my_cool_optimizer.v1"函数，然后用参数learn_rate和gamma调用它。如果该函数具有类型注释，则还将验证输入。例如，如果将learn_rate注释为浮点，并且配置定义了字符串， confection将引起错误。

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

• 递归块

• 定义可变位置参数

• 使用插值

• 使用自定义注册表

• pydantic的高级类型注释

• 使用基本模式

• 用默认值填充配置

API

类Config

该类具有模型和训练配置，可以从/到字符串，文件或字节加载并保存INI风格的配置格式。 Config类是dict的一个子类，并在引擎盖下使用Python的ConfigParser 。

^{方法Config.__init__}

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

来自糖果import import configconfig = config（{“训练”：{“耐心”：10，“ dropot”：0.2}}）

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

^{方法Config.from_str}

从字符串加载配置。

从糖果导入confimconconfig_str =“”“” [训练] patience = 10dropout = 0.2“” config = config（）。from_str（config_str）print（config [config [“ triaght'triaght']）＃{'耐心'：10，'droppout'： 0.2}}}

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

^{方法Config.to_str}

从字符串加载配置。

来自糖果import import configconfig = config（{“ triagh”：{“耐心”：10，“ dropout”：0.2}}）print（config.to_to str（））＃'[triending] npatience = 10nnDropout = 0.2'

争论	类型	描述
interpolate	bool	是否要插入${section.key}之类的变量。默认为True 。
返回	str	字符串配置。

^{方法Config.to_bytes}

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

来自糖果import import configconfig = config（{“培训”：{“耐心”：10，“ dropt”：0.2}}）config_bytes = config.to_to_bytes（）print（config_bytes）＃b'[triaght triending]

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

^{方法Config.from_bytes}

从字节字符串加载配置。

来自糖果import import configconfig = config（{“培训”：{“耐心”：10，“ dropout”：0.2}}）config_bytes = config.to_bytes（）new_config = config（）。

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

^{方法Config.to_disk}

将配置序列化为文件。

来自糖果import import configconfig = config（{“训练”：{“耐心”：10，“ dropot”：0.2}}）config.to_disk（“ ./ config.cfg”）

争论	类型	描述
path	Union[Path, str]	文件路径。
interpolate	bool	是否要插入${section.key}之类的变量。默认为True 。

^{方法Config.from_disk}

从文件加载配置。

来自糖果import import configconfig = config（{“培训”：{“耐心”：10，“ dropt”：0.2}}）config.to_disk（“ ./ config.cfg”）new_config = config（）。 config.cfg”）

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

^{方法Config.copy}

深拷贝配置。

争论	类型	描述
返回	Config	复制的配置。

^{方法Config.interpolate}

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

从糖果导入confimconconfig_str =“”“ [hyper_params]辍学= 0.2 [训练]辍学= $ {hyper_params.dropout}“”“ config = config（）。config（）。 ）＃{'dropout'：'$ {hyper_params.dropout}'}} config = = config.interpaly（）print（config [“训练”]）＃{'dropfout'：0.2}}}

争论	类型	描述
返回	Config	带有插值值的配置副本。

^{方法Config.merge}

Deep-Merge两个配置对象，使用当前配置作为默认值。仅合并部分和词典，而不是其他值等值。更新中提供的值在基本配置中被覆盖，并添加任何新值或部分。如果配置值是一个变量，例如${section.key} （例如，如果配置加载了interpolate=False) ，则首选该变量，即使更新提供了不同的值。这样可以确保变量引用不会被合并破坏。

配x请注意，仅当使用@语法引用注册函数的块仅在提到相同功能时才合并。否则，合并很容易产生无效的配置，因为不同的功能可以采用不同的参数。如果一个块是指其他功能，则覆盖它。

来自糖果导入import confimbase_config_str =“”“ [训练]耐心= 10dropout = 0.2“”“ update_config_str =”“” [训练] droppout = 0.1max_epochs = 2000“ base_config = config（）。 ）.from_str（update_config_str）合并= config（base_config）.merge（update_config）print（合并[“训练”]）＃{'耐心'：10，'droppout'：0.1，'max_epochs'：2000}

争论	类型	描述
overrides	Union[Dict[str, Any], Config]	合并到配置中的更新。
返回	Config	一个包含合并配置的新配置实例。

配置属性

争论	类型	描述
is_interpolated	bool	配置值是否已插值。默认为True ，并设置为False如果配置加载了interpolate=False ，例如使用Config.from_str 。