hyperpyyaml.core 模块

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

Authors

彼得·普兰廷加 2020
阿库·柔赫 2020
李建晨 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 中位置的 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标签，然后被解释为一个元组。

Parameters:

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 等。

Returns:

hparams – 反映了 yaml_stream 的结构。

Return type:

dict

Example

>>> 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的类

Parameters:: ref_str (str) – 包含yaml键的字符串，使用表示法

Example

参见 dump_hyperpyyaml

yaml_tag = '!ref'

classmethod to_yaml(representer, node)[source]

class hyperpyyaml.core.Placeholder[source]

基础类：object

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

Example

参见 dump_hyperpyyaml

yaml_tag = '!PLACEHOLDER'

classmethod to_yaml(representer, node)[source]

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

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

Parameters:

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

Example

>>> 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的一个组件。

Parameters:

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

Returns:

一个yaml格式的流，所有引用和覆盖都已解析。

Return type:

流

Example

>>> 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]

查找点符号中引用所指向的值

Parameters:

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

Returns:

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

Return type:

节点

Example

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

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

解析对值的引用，遵循链式引用

Parameters:

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

Returns:

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

Return type:

标量

Example

>>> 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

Parameters:: reference_string (str) – 一个包含引用和可能的算术操作的字符串。
Returns:: 解析并应用算术的结果。
Return type:: str

Example

>>> 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}}

Parameters:

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

Example

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