hyperpyyaml.core 模块

该库收集了用于加载 hyperpyyaml 的实用工具

作者

Peter Plantinga 2020
Aku Rouhe 2020
Jianchen Li 2022

摘要

类

`Placeholder`	用于将 !PLACEHOLDER 标签转储到 yaml 的类
`RefTag`	用于将 !ref 标签转储到 yaml 的类

函数

`deref`	查找点表示法中引用所指向的值
`dump_hyperpyyaml`	转储包含占位符和引用标签的 yaml。
`load_hyperpyyaml`	此函数实现了 HyperPyYAML 语法
`parse_arithmetic`	解析引用中的简单算术操作
`recursive_resolve`	解析引用以获取值，遵循引用链
`recursive_update`	类似于 `dict.update` 的函数，但用于嵌套的 `dict`。
`resolve_references`	解析文档间引用，这是 HyperPyYAML 的一个组成部分。

参考

hyperpyyaml.core.load_hyperpyyaml(yaml_stream, overrides=None, overrides_must_match=True, loader=<class 'ruamel.yaml.loader.Loader'>)[source]

此函数实现了 HyperPyYAML 语法

此语法旨在实现紧凑、结构化的超参数和函数定义。此函数实现了对 yaml 语法的一些扩展，如下所示。

PyYAML 复杂标签快捷方式

我们清晰结构化超参数接口的一部分是能够轻松干净地指定 python 对象。使用原生 YAML 通过以下语法可以实现这一点

alignment_saver: !!python/object/new:speechbrain.data_io.TensorSaver
    kwargs: {save_dir: results/asr/ali}

然而，由于在 speechbrain yaml 文件中的广泛使用，我们为此添加了一个快捷方式，其语法如下

alignment_saver: !new:speechbrain.data_io.TensorSaver
    save_dir: results/asr/ali

在此示例中，alignment_saver 将是 TensorSaver 类的一个实例，其中 'exp/asr/ali' 作为关键字参数传递给 __init__() 方法。这等同于

import speechbrain.data_io.data_io
alignment_saver = speechbrain.data_io.TensorSaver(
    save_dir='exp/asr/ali'
)

我们还实现了一些其他快捷方式：

!!python/name: => !name:
!!python/module: => !module:
!!python/object/apply: => !apply:

引用和复制

允许对文件中的任何节点进行内部引用。任何带有 !ref 标签的节点都将创建对 yaml 中 <key.subkey> 位置的 yaml 对象的对象引用，并遵循引用链。

output_folder: results/asr
alignment_saver: !new:speechbrain.data_io.TensorSaver
    save_dir: !ref <output_folder>

字符串值被特殊处理：引用会被替换，但字符串的其余部分会保留，以便轻松扩展文件路径

output_folder: results/asr
alignment_saver: !new:speechbrain.data_io.TensorSaver
    save_dir: !ref <output_folder>/ali  # results/asr/ali

一个更复杂的示例，用于演示

key1: {a: !new:object {arg1: 1}}
key2: !ref <key1[a]>

在这里，key2 将包含对 a 对象的引用，因此更改 a.arg1 也会更改 key2.arg1。如果您需要对象的深层复制而不是浅层引用，可以使用带有 !copy 标签的类似语法。例如

key1: {a: !new:object {arg1: 1}}
key2: !copy <key1[a]>

这些还将实现非常基本的算术，所以

key1: 1
key2: !ref <key1> + 3  # this is 4

元组

最后一个小改进是隐式元组解析器。传递字符串值 (3, 4) 将被赋予 !tuple 标签，然后被解释为元组。

参数:

yaml_stream (stream) – 用于读取的文件类对象或字符串。
overrides (mapping 或 str) – 用于覆盖从流中读取的值的集合。由于 yaml 实现了嵌套结构，覆盖也一样。参见 speechbrain.utils.data_utils.recursive_update
overrides_must_match (bool) – 当覆盖项与 yaml_stream 中的对应键不匹配时是否抛出错误。
return_dict (bool) – 是否返回字典而不是默认命名空间。
loader (Loader) – 用于解析 yaml_stream，可以是 ruamel.yaml.Loader, yaml.Loader 等。

返回:

hparams – 反映 yaml_stream 的结构。

返回类型:

dict

示例

>>> yaml_string = """
... a: 3
... thing: !new:collections.Counter
...     b: !ref <a>
... """
>>> params = load_hyperpyyaml(yaml_string)
>>> params["thing"]
Counter({'b': 3})

class hyperpyyaml.core.RefTag(ref_str)[source]

基类: object

用于将 !ref 标签转储到 yaml 的类

参数:: ref_str (str) – 包含以 <key> 表示法表示的 yaml 键的字符串

示例

参见 dump_hyperpyyaml

yaml_tag = '!ref'

classmethod to_yaml(representer, node)[source]

class hyperpyyaml.core.Placeholder[source]

基类: object

用于将 !PLACEHOLDER 标签转储到 yaml 的类

示例

参见 dump_hyperpyyaml

yaml_tag = '!PLACEHOLDER'

classmethod to_yaml(representer, node)[source]

hyperpyyaml.core.dump_hyperpyyaml(yaml_tree, output_stream, *args, **kwargs)[source]

转储包含占位符和引用标签的 yaml。

参数:

yaml_tree (dict) – 要转储的对象
output_stream (stream) – 用于放置 yaml 的文件流
*args – 传递给 ruamel.yaml.YAML().dump() 的参数
**kwargs – 传递给 ruamel.yaml.YAML().dump() 的参数

示例

>>> to_yaml = {'a': Placeholder(), 'b': RefTag('<a>')}
>>> stringio = StringIO()
>>> dump_hyperpyyaml(to_yaml, stringio)
>>> stringio.getvalue()
'a: !PLACEHOLDER\nb: !ref <a>\n'

hyperpyyaml.core.resolve_references(yaml_stream, overrides=None, overrides_must_match=False)[source]

解析文档间引用，这是 HyperPyYAML 的一个组成部分。

参数:

yaml_stream (stream) – 包含使用 HyperPyYAML 语法编写的 yaml 文件内容的类似文件的对象或字符串。
overrides (mapping 或 str) – 替换值，可以是 yaml 格式的字符串或 dict。
overrides_must_match (bool) – 当覆盖项与 yaml_stream 中的对应键不匹配时是否抛出错误。这与 load_hyperpyyaml 的默认设置相反，因为 resolve_references 默认不需要那么严格。

返回:

一个解析了所有引用和覆盖项的 yaml 格式流。

返回类型:

stream

示例

>>> yaml_string = """
... constants:
...     a: 3
...     b: !ref <constants[a]>
... """
>>> overrides = {'constants': {'a': 4}}
>>> resolve_references(yaml_string, overrides).getvalue()
'constants:\n  a: 4\n  b: 4\n'

hyperpyyaml.core.deref(ref, full_tree, copy_mode=False)[source]

查找点表示法中引用所指向的值

参数:

ref (str) – 请求值的位置，例如 ‘constants.param’
full_tree (dict) – 用于查找值的字典
copy_mode (bool) – 是否在解除引用之前复制节点。

返回:

full_tree 字典中由 ref 引用的节点。

返回类型:

节点

示例

>>> deref('constants[a][b]', {'constants': {'a': {'b': 'c'}}})
'c'

hyperpyyaml.core.recursive_resolve(reference, reference_list, full_tree, copy_mode=False)[source]

解析引用以获取值，遵循引用链

参数:

reference (str) – 包含 ‘<x[y]>’ 的字符串，其中 x[y] 指代文件中的标量节点。
reference_list (list) – 引用链中的先前引用列表，用于捕获循环引用。
full_tree (dict) – 用于查找所有引用及其值的字典。
copy_mode (bool) – 是否对引用的节点执行深层复制，而不是对同一对象的浅层引用。

返回:

解除引用的值，可能包含字符串插值和算术解析。

返回类型:

标量

示例

>>> tree = {'a': 3, 'b': 'x', 'c': '<a>', 'd': '<c>/<c>', 'e': '<b>/<b>'}
>>> recursive_resolve('<d>', [], tree)
1.0
>>> recursive_resolve('<e>', [], tree)
'x/x'

hyperpyyaml.core.parse_arithmetic(reference_string)[source]

解析引用中的简单算术操作

改编自 https://stackoverflow.com/a/9558001/1761970

参数:: reference_string (str) – 包含引用和可能的算术操作的字符串。
返回:: 解析和应用算术的结果。
返回类型:: str

示例

>>> parse_arithmetic('2 * 6')
12

hyperpyyaml.core.recursive_update(d, u, must_match=False)[source]

类似于 dict.update 的函数，但用于嵌套的 dict。

来源：https://stackoverflow.com/a/3233356

如果您有一个嵌套映射结构，例如

{“a”: 1, “b”: {“c”: 2}}

假设您想用以下内容更新上述结构

{“b”: {“d”: 3}}

此函数将生成

{“a”: 1, “b”: {“c”: 2, “d”: 3}}

而不是

{“a”: 1, “b”: {“d”: 3}}

参数:

d (dict) – 要更新的映射
u (dict) – 用于更新的映射
must_match (bool) – 如果 u 中的键在 d 中不存在，是否抛出错误。

示例

>>> d = {'a': 1, 'b': {'c': 2}}
>>> recursive_update(d, {'b': {'d': 3}})
>>> d
{'a': 1, 'b': {'c': 2, 'd': 3}}