HyperPyYAML

https://github.com/speechbrain/hyperpyyaml
Admin
HyperPyYAML is an extension to YAML that simplifies hyperparameter specification for data-analysis...
Tokens:31,125
Snippets:208
Trust Score:8.5
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Custom loader example

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/load_hyperpyyaml.md

Shows how to pass a custom YAML loader (e.g., yaml.Loader) to load_hyperpyyaml. The example loads a simple reference and accesses the result.

```python
import yaml
from hyperpyyaml import load_hyperpyyaml

params = load_hyperpyyaml("a: 1\nb: !ref <a>", loader=yaml.Loader)
params["b"]                   # 1
```

--------------------------------

### recursive_resolve usage examples with doctest

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/core-internals.md

Interactive Python examples showing how recursive_resolve handles chained references and string interpolation. The first example resolves '<d>' to 1.0, and the second resolves '<e>' to 'x/x'.

```python
>>> 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'
```

--------------------------------

### deref import and error handling example

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/core-internals.md

Example showing how to import and use deref from hyperpyyaml.core. It demonstrates successful dereferencing and the ValueError raised when a path component does not exist.

```python
from hyperpyyaml.core import deref

tree = {"model": {"hidden_size": 128}, "name": "asr"}
deref("model[hidden_size]", tree)   # 128

try:
    deref("model[missing]", tree)
except ValueError as err:
    print(err)                      # The reference "model[missing]" is not valid
```

--------------------------------

### resolve_references usage example

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/resolve_references.md

An example demonstrating how to use resolve_references with a YAML string and overrides to resolve references.

```python
>>> 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'
```

--------------------------------

### parse_arithmetic usage examples

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/core-internals.md

Usage examples demonstrating arithmetic evaluation and error handling: integer division, exponentiation, and cases where evaluation fails and the input is returned unchanged.

```python
from hyperpyyaml.core import parse_arithmetic

parse_arithmetic("10 // 3 + 1")   # 4
parse_arithmetic("3.0 ** 2")      # 9.0
parse_arithmetic("1 / b")         # '1 / b'  (SyntaxError caught — returned unchanged)
parse_arithmetic("-1")            # '-1'     (KeyError caught — unary minus does not evaluate)
```

--------------------------------

### !apply:sum with sequence child

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/yaml-tags.md

Calls the callable immediately at load time, passing sequence children as positional arguments. The example sums the list [1, 2] to get 3.

```yaml
a: !apply:sum [[1, 2]]                      # 3
```

--------------------------------

### !ref and !copy reference resolution examples

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/yaml-tags.md

Shows full-match dereference and interpolation with !ref, including arithmetic and attribute references. !ref shares objects shallowly; !copy deep-copies. Interpolation replaces <key> with str(deref(...)) and re-resolves.

```yaml
folder1: abc/def
folder2: ghi/jkl
folder3: !ref <folder1>/<folder2>     # 'abc/def/ghi/jkl'

block_index: 1
cnn1:
  out_channels: !ref <block_index> * 64     # 64
  kernel_size: (3, 3)
cnn2:
  out_channels: !ref <cnn1[out_channels]>   # 64 (shared reference)
  kernel_size: (3, 3)
```

--------------------------------

### parse_arithmetic example with doctest

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/core-internals.md

Example showing the result of parse_arithmetic('2 * 6') as 12.

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

--------------------------------

### Docstring example of dump_hyperpyyaml

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/dump_hyperpyyaml.md

Verbatim example from the docstring. Shows dumping a dict with a Placeholder and a RefTag to a StringIO, producing 'a: !PLACEHOLDER\nb: !ref <a>\n'.

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

--------------------------------

### recursive_update usage example with must_match

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/core-internals.md

Example showing recursive_update merging nested dictionaries and raising KeyError when must_match=True and a key is missing.

```python
from hyperpyyaml.core import recursive_update

params = {"model": {"hidden": 128, "lr": 1e-3}, "epochs": 10}
recursive_update(params, {"model": {"hidden": 256}}, must_match=True)
params["model"]          # {'hidden': 256, 'lr': 0.001}  (merged, not replaced)

try:
    recursive_update({"a": 1}, {"b": 2}, must_match=True)
except KeyError as err:
    print(err)           # "Override 'b' not found in: ['a']"
```

--------------------------------

### YAML Scalar Node Examples

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Demonstrates the basic scalar node types supported in YAML, including strings, integers, floats, booleans, and null values.

```yaml
string: abcd  # No quotes needed
integer: 1
float: 1.3
bool: True
none: null
```

--------------------------------

### Catch FileNotFoundError for missing include file

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/errors.md

Shows catching FileNotFoundError when an include file is missing. The example uses a nonexistent path.

```python
from hyperpyyaml import load_hyperpyyaml

try:
    load_hyperpyyaml("a: !include:/definitely/missing.yaml")
except FileNotFoundError:
    print("include target missing")
```

--------------------------------

### recursive_update docstring example

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/core-internals.md

Example from the docstring showing recursive_update merging nested dictionaries.

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

--------------------------------

### deref usage example

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/core-internals.md

Example usage of deref in a Python interactive session. It shows how to retrieve a nested value using bracket notation.

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

--------------------------------

### Basic usage of load_hyperpyyaml

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/load_hyperpyyaml.md

Loads a YAML string with references (!ref), object construction (!new:), and implicit tuple conversion. The example shows how to access the resulting parameters.

```python
from hyperpyyaml import load_hyperpyyaml

yaml_string = """
batch_size: 32
lr: !ref <batch_size> * 0.001
model: !new:collections.Counter
  a: 2
  b: 1
kernel: (3, 3)
"""

params = load_hyperpyyaml(yaml_string)

params["batch_size"]          # 32
params["lr"]                  # 0.032  (reference + arithmetic)
params["model"]               # Counter({'a': 2, 'b': 1})
params["kernel"]              # (3, 3)  (implicit tuple)
```

--------------------------------

### Error handling examples

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/load_hyperpyyaml.md

Demonstrates the error types raised by load_hyperpyyaml: ValueError for invalid references, ImportError for nonexistent targets, TypeError for wrong constructor arguments, and RepresenterError for object-producing !applyref.

```python
from hyperpyyaml import load_hyperpyyaml

# Reference to a nonexistent key -> ValueError
try:
    load_hyperpyyaml("a: 1\nb: !ref <missing>")
except ValueError as err:
    print(err)                # The reference "missing" is not valid

# Nonexistent target -> ImportError
try:
    load_hyperpyyaml("a: !new:no.such.module.Class")
except ImportError as err:
    print(err)                # There is no such class as no.such.module.Class

# Wrong constructor arguments -> TypeError with prefixed message
try:
    load_hyperpyyaml("a: !new:collections.Counter\n  not_a_counter_arg: 1")
except TypeError as err:
    print(err)                # ('Invalid argument to class collections.Counter', ...)

# Object-producing !applyref -> RepresenterError with hint
try:
    load_hyperpyyaml("a: !applyref:collections.Counter\n  x: 1")
except Exception as err:
    print(type(err).__name__, err.args[0])
```

--------------------------------

### Handling resolve_references errors

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/resolve_references.md

Examples of common exceptions raised by resolve_references, including structure mismatches, non-representable nodes, and missing include files.

```python
from hyperpyyaml import resolve_references

# Overrides that are not a mapping (structure mismatch) -> ValueError
try:
    resolve_references("a: 1\nb: 2", overrides=[1, 2, 3])
except ValueError as err:
    print(err)      # "The structure of the overrides doesn't match the structure of the document: ", [1, 2, 3]

# Non-representable node (an object returned by !applyref:) -> RepresenterError with hint
try:
    resolve_references("a: !applyref:collections.Counter\n  x: 1")
except Exception as err:
    print(type(err).__name__)                       # RepresenterError
    print(err.args[0].endswith("Please use the !apply tag instead."))  # True

# Missing file for !include: -> FileNotFoundError (propagates from open())
try:
    resolve_references("a: !include:does/not/exist.yaml")
except FileNotFoundError as err:
    print(err)
```

--------------------------------

### recursive_resolve usage with circular reference handling

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/core-internals.md

Example showing how to use recursive_resolve with a tree containing chained references and how to catch a circular reference error. The first call resolves '<b>' to 3, and the second raises a ValueError with the reference list.

```python
from hyperpyyaml.core import recursive_resolve

tree = {"a": 3, "b": "!ref <a>"}
recursive_resolve("<b>", [], tree)   # 3  (chained, type-preserving)

circular = {"a": "<b>", "b": "<a>"}
try:
    recursive_resolve("<a>", [], circular)
except ValueError as err:
    print(err)                        # ('Circular reference detected: ', ['<a>', '<b>', '<a>'])
```

--------------------------------

### Emitting a config template with Placeholder

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/Placeholder.md

Shows how to build a tree with a `Placeholder` for `data_folder` and dump it. The output is shown as commented lines: `data_folder: !PLACEHOLDER` and `batch_size: 32`.

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, Placeholder

tree = {
    "data_folder": Placeholder(),
    "batch_size": 32,
}

buf = StringIO()
dump_hyperpyyaml(tree, buf)
print(buf.getvalue())
# data_folder: !PLACEHOLDER
# batch_size: 32
```

--------------------------------

### Basic use: writing a template with placeholders

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/dump_hyperpyyaml.md

Creates a tree with a Placeholder and a RefTag, dumps it to a StringIO, and prints the resulting YAML. The output shows !PLACEHOLDER and !ref tags.

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, RefTag, Placeholder

tree = {
    "data_folder": Placeholder(),
    "examples": {"ex1": RefTag("<data_folder>/ex1.wav")},
}

out = StringIO()
dump_hyperpyyaml(tree, out)

print(out.getvalue())
# data_folder: !PLACEHOLDER
# examples:
#   ex1: !ref <data_folder>/ex1.wav
```

--------------------------------

### HyperPyYAML Object Instantiation

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Demonstrates using the !new: tag to construct an instance of a class.

```yaml
model: !new:collections.Counter
```

--------------------------------

### YAML Sequence Syntax

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Demonstrates the two ways to define sequences (lists) in YAML.

```yaml
- foo
- bar
- baz
```

```yaml
[foo, bar, baz]
```

--------------------------------

### Object References and Copies

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Demonstrates shallow copying with !ref versus deep copying with !copy for object nodes.

```python
yaml_string = """
foo: !new:collections.Counter
  a: 4
bar: !ref <foo>
baz: !copy <foo>
"""
loaded_yaml = load_hyperpyyaml(yaml_string)
loaded_yaml["foo"].update({"b": 10})
print(loaded_yaml["bar"])
print(loaded_yaml["baz"])
```

```text
Counter({'b': 10, 'a': 4})
Counter({'a': 4})
```

--------------------------------

### Filling the placeholder before loading

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/Placeholder.md

Dumps a config with a `Placeholder` and then loads it with `overrides` to replace the placeholder. The result `hparams["data_folder"]` is `'data/speech'`.

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, load_hyperpyyaml, Placeholder

buf = StringIO()
dump_hyperpyyaml({"data_folder": Placeholder(), "batch_size": 32}, buf)

# Placeholders must be replaced via overrides:
hparams = load_hyperpyyaml(buf.getvalue(), overrides={"data_folder": "data/speech"})
hparams["data_folder"]      # 'data/speech'
```

--------------------------------

### Round trip with load_hyperpyyaml

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/dump_hyperpyyaml.md

Dumps a tree with a placeholder and a reference, then loads it back with load_hyperpyyaml using overrides to fill the placeholder. Demonstrates that the loaded values resolve correctly.

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, load_hyperpyyaml, RefTag, Placeholder

tree = {
    "data_folder": Placeholder(),
    "preprocessed": RefTag("<data_folder>/preprocessed"),
}

buf = StringIO()
dump_hyperpyyaml(tree, buf)

# Fill in the missing value via overrides, then load normally:
loaded = load_hyperpyyaml(buf.getvalue(), overrides={"data_folder": "data/speech"})
loaded["data_folder"]   # 'data/speech'
loaded["preprocessed"]  # 'data/speech/preprocessed'
```

--------------------------------

### HyperPyYAML Positional and Keyword Arguments

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Shows how to pass positional arguments using a list and keyword arguments using a mapping when using the !new: tag.

```yaml
foo: !new:collections.Counter
  - abracadabra
bar: !new: collections.Counter
  a: 2
  b: 1
  c: 5
```

--------------------------------

### load_hyperpyyaml(yaml_stream, overrides=None, overrides_must_match=True, loader=ruamel.yaml.Loader)

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/load_hyperpyyaml.md

Loads a YAML stream written in the HyperPyYAML dialect and returns a Python structure with all extensions applied. This is the single main entry point of the library.

```APIDOC
## load_hyperpyyaml(yaml_stream, overrides=None, overrides_must_match=True, loader=ruamel.yaml.Loader)

### Description
Loads a YAML stream written in the HyperPyYAML dialect and returns a Python structure with all extensions applied. This is the single main entry point of the library.

### Signature
```python
def load_hyperpyyaml(
    yaml_stream, overrides=None, overrides_must_match=True, loader=ruamel.yaml.Loader
):
```

### Parameters
- **yaml_stream** (stream) - Required - A file-like object or string from which to read (forwarded to `resolve_references`, then to `yaml.load`).
- **overrides** (mapping or str) - Optional - Default: `None` - A set of overrides for the values read from the stream. As YAML implements a nested structure, so can the overrides (a dict of nested dicts, or a YAML-formatted string which is itself loaded with ruamel.yaml). Overrides are merged via `recursive_update`, so a nested override merges into the existing sub-mapping instead of replacing it.
- **overrides_must_match** (bool) - Optional - Default: `True` - Whether an error is thrown when an override key does not match a corresponding key in the yaml_stream (`KeyError` from `recursive_update`).
- **loader** (Loader class) - Optional - Default: `ruamel.yaml.Loader` - Use to parse the yaml_stream; could be `ruamel.yaml.Loader`, `yaml.Loader`, etc. (per docstring). The loader must support `add_constructor`, `add_implicit_resolver` and `add_multi_constructor`; the `!tuple` resolver and the `!new:`/`!name:`/`!module:`/`!apply:` constructors are registered on it on every call.

### Returns
- **dict** - The function always returns a dictionary. (Note: the docstring mentions a `return_dict` argument, but no such parameter exists in the function signature.)

### Source
- `hyperpyyaml/core.py`, line 27 (function definition; docstring through line 113).
- Imported from: `hyperpyyaml/__init__.py` (`from .core import load_hyperpyyaml`).
```

--------------------------------

### Basic use of RefTag with dump_hyperpyyaml

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/RefTag.md

Shows how to create a RefTag instance and dump it to YAML, producing a !ref scalar.

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, RefTag

tree = {
    "output_folder": "results/asr",
    "model_path": RefTag("<output_folder>/model.ckpt"),
}

buf = StringIO()
dump_hyperpyyaml(tree, buf)
print(buf.getvalue())
# output_folder: results/asr
# model_path: !ref <output_folder>/model.ckpt
```

--------------------------------

### HyperPyYAML Function Execution

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Shows how to load a HyperPyYAML string and execute a stored function.

```python
>>> loaded_yaml = load_hyperpyyaml("add: !name:operator.add")
>>> loaded_yaml["add"](2, 4)
6
```

--------------------------------

### Placeholder() Constructor

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/Placeholder.md

Constructor for the Placeholder class. Takes no arguments and stores no state.

```APIDOC
## Placeholder()

### Description
Constructor for the Placeholder class. Takes no arguments and stores no state.

### Parameters
None

### Returns
A new Placeholder instance.

### Example
```python
from hyperpyyaml import Placeholder
placeholder = Placeholder()
```
```

--------------------------------

### Overrides with dict and YAML string

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/load_hyperpyyaml.md

Shows how to pass overrides as a dictionary or as a YAML string. Nested overrides merge, and strict override matching is on by default, raising KeyError for unknown keys.

```python
from hyperpyyaml import load_hyperpyyaml

base = """
n_layers: 4
out_folder: results/exp1
model:
  hidden: !ref <n_layers> * 100
"""

params = load_hyperpyyaml(
    base,
    overrides={"n_layers": 6, "out_folder": "results/exp2"},
)
params["model"]["hidden"]     # 600

# Overrides may also be given as a YAML string; nested overrides merge:
params = load_hyperpyyaml(base, overrides="n_layers: 6\nmodel: {hidden: 700}")
params["model"]               # {'hidden': 700}

# Strict override matching is on by default:
try:
    load_hyperpyyaml("a: 1", overrides={"nope": 2})
except KeyError as err:
    print(err)                # Override 'nope' not found in: ['a']
```

--------------------------------

### YAML Mapping Syntax

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Shows the JSON-like syntax for defining a mapping in YAML.

```yaml
{foo: 1, bar: 2.5, baz: "abc"}
```

--------------------------------

### !new:collections.Counter with keyword arguments

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/yaml-tags.md

Constructs an instance, passing mapping children as keyword arguments. Here it creates a Counter with the given counts.

```yaml
bar: !new:collections.Counter              # Counter({'a': 2, 'b': 1, 'c': 5})
  a: 2
  b: 1
  c: 5
```

--------------------------------

### Round trip through load_hyperpyyaml

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/RefTag.md

Demonstrates dumping a RefTag and then loading it back, resolving the reference to a plain string.

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, load_hyperpyyaml, RefTag

tree = {
    "output_folder": "results/asr",
    "model_path": RefTag("<output_folder>/model.ckpt"),
}
buf = StringIO()
dump_hyperpyyaml(tree, buf)

loaded = load_hyperpyyaml(buf.getvalue())
loaded["model_path"]        # 'results/asr/model.ckpt'
```

--------------------------------

### !apply:hyperpyyaml.TestThing.from_keys with args and kwargs

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/yaml-tags.md

Calls the callable immediately, passing mapping children as keyword arguments and sequence children as positional. Here it invokes the from_keys classmethod with positional args and a !ref to common_kwargs.

```yaml
c: !apply:hyperpyyaml.TestThing.from_keys
  args: [1, 2]
  kwargs: !ref <common_kwargs>
```

--------------------------------

### Forwarding dump arguments

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/dump_hyperpyyaml.md

Shows calling dump_hyperpyyaml with a tree containing a Placeholder and a plain integer, writing to a StringIO. Demonstrates that extra arguments can be forwarded to ruamel.yaml's dump.

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, Placeholder

buf = StringIO()
dump_hyperpyyaml({"a": Placeholder(), "b": 3}, buf)
```

--------------------------------

### Standalone resolve_references usage

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/resolve_references.md

Demonstrates how to resolve references in a YAML string with specific overrides applied before loading.

```python
from hyperpyyaml import resolve_references
from io import StringIO

config = """
output_folder: results/asr
n_layers: 4
model:
  hidden_size: !ref <n_layers> * 256
"""

resolved = resolve_references(config, overrides={"n_layers": 6})
print(type(resolved).__name__)        # StringIO
print(resolved.getvalue())
# output_folder: results/asr
# n_layers: 6
# model:
#   hidden_size: 1536
```

--------------------------------

### !new:collections.Counter with no arguments

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/yaml-tags.md

Constructs an instance of the specified class without any arguments.

```yaml
model: !new:collections.Counter            # Counter()
```

--------------------------------

### Internal implementation of dump_hyperpyyaml

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/dump_hyperpyyaml.md

The core implementation from source (core.py:260-263). It creates a fresh ruamel.yaml.YAML() instance, registers representers for RefTag and Placeholder, and dumps the tree. Only these representers are added, so other non-trivial objects raise RepresenterError.

```python
ruamel_yaml = ruamel.yaml.YAML()
ruamel_yaml.representer.add_representer(RefTag, RefTag.to_yaml)
ruamel_yaml.representer.add_representer(Placeholder, Placeholder.to_yaml)
ruamel_yaml.dump(yaml_tree, output_stream, *args, **kwargs)
```

--------------------------------

### Arithmetic with !ref

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/yaml-tags.md

Demonstrates arithmetic operations applied after interpolation via parse_arithmetic. Unparseable expressions are returned unchanged; unary +/- do not evaluate.

```yaml
foo: 1024
bar: 512
baz: !ref <foo> // <bar> + 1      # 3
```

--------------------------------

### YAML String Interpolation with !ref

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Use the !ref tag to perform string interpolation and reference other keys within the YAML file.

```yaml
folder1: abc/def
folder2: ghi/jkl
folder3: !ref <folder1>/<folder2>

foo: 1024
bar: 512
baz: !ref <foo> // <bar> + 1
```

--------------------------------

### YAML Nested Mapping and Sequence

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Shows how whitespace is used to denote nested items in YAML structures.

```yaml
foo:
    a: 1
    b: 2
bar:
    - c
    - d
```

--------------------------------

### Error handling for un-replaced placeholder

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/Placeholder.md

Attempts to load a document with an unfilled `!PLACEHOLDER` and catches the `ValueError`. The printed error is `'data_folder' is a !PLACEHOLDER and must be replaced.`

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, load_hyperpyyaml, Placeholder

buf = StringIO()
dump_hyperpyyaml({"data_folder": Placeholder()}, buf)

try:
    load_hyperpyyaml(buf.getvalue())
except ValueError as err:
    print(err)      # 'data_folder' is a !PLACEHOLDER and must be replaced.
```

--------------------------------

### Class definition for Placeholder

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/Placeholder.md

Exact source definition of `Placeholder` with `yaml_tag = "!PLACEHOLDER"` and `to_yaml` representing an empty scalar.

```python
class Placeholder:
    """Class for dumping !PLACEHOLDER tags to yaml

    Example
    -------
    See ``dump_hyperpyyaml``
    """

    yaml_tag = "!PLACEHOLDER"

    @classmethod
    def to_yaml(cls, representer, node):
        return representer.represent_scalar(cls.yaml_tag, "")
```

--------------------------------

### !include with overrides

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/yaml-tags.md

Loads another YAML file as part of the document. The path is appended to the including stream's directory when available. A mapping attached to the include node is passed as overrides to the included file's resolution.

```yaml
b: !PLACEHOLDER
import: !include:models/resnet.yaml
  n_layers: !ref <b>
d: !ref <import[out_dim]>
```

--------------------------------

### Error handling: composing against a missing key

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/RefTag.md

Shows that a RefTag referencing a missing key raises ValueError on load, with the message 'The reference "missing_folder" is not valid'.

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, load_hyperpyyaml, RefTag

buf = StringIO()
dump_hyperpyyaml({"model_path": RefTag("<missing_folder>/model.ckpt")}, buf)

try:
    load_hyperpyyaml(buf.getvalue())
except ValueError as err:
    print(err)      # The reference "missing_folder" is not valid
```

--------------------------------

### Load Hyperparameters with Overrides

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/overview.md

Use the load_hyperpyyaml function to parse a YAML file and apply specific overrides to the configuration.

```python
from hyperpyyaml import load_hyperpyyaml

with open("hyperparameters.yaml") as f:
    hparams = load_hyperpyyaml(f, overrides={"n_layers": 6})
```

--------------------------------

### load_hyperpyyaml

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/load_hyperpyyaml.md

Loads a YAML string with hyperpyyaml extensions, returning a dictionary with resolved references and constructed objects. Supports optional overrides and a custom YAML loader.

```APIDOC
## load_hyperpyyaml

### Description
Loads a YAML string with hyperpyyaml extensions, returning a dictionary with resolved references and constructed objects. Supports optional overrides and a custom YAML loader.

### Function Signature
load_hyperpyyaml(yaml_string, overrides=None, loader=None)

### Parameters
- **yaml_string** (str) - Required - The YAML string to load.
- **overrides** (dict or str) - Optional - Overrides to apply to the loaded configuration. Can be a dictionary or a YAML string. Nested overrides merge with the base configuration.
- **loader** (yaml.Loader) - Optional - Custom YAML loader to use. Defaults to the hyperpyyaml loader.

### Returns
- **dict** - The loaded configuration dictionary with resolved references and constructed objects.

### Errors
Raises errors originating in resolve_references and the tag constructors. Summary:
- ImportError - !new:/!name:/!module:/!apply:/!applyref: target does not exist.
- ValueError - tag applied to the wrong kind of entity; invalid reference; circular reference; !PLACEHOLDER not replaced; override structure mismatch.
- KeyError - override key not found and overrides_must_match=True.
- TypeError (with message prefixed "Invalid argument to class/callable ...") - wrong constructor arguments.
- RepresenterError (from ruamel.yaml.representer) - a resolved node (e.g. !applyref: returning an object) cannot be dumped back to YAML; re-raised with ". Please use the !apply tag instead." appended.
- FileNotFoundError - !include: points at a missing file.

### Examples

#### Basic usage
```python
from hyperpyyaml import load_hyperpyyaml

yaml_string = """
batch_size: 32
lr: !ref <batch_size> * 0.001
model: !new:collections.Counter
  a: 2
  b: 1
kernel: (3, 3)
"""

params = load_hyperpyyaml(yaml_string)

params["batch_size"]          # 32
params["lr"]                  # 0.032  (reference + arithmetic)
params["model"]               # Counter({'a': 2, 'b': 1})
params["kernel"]              # (3, 3)  (implicit tuple)
```

#### Overrides (dict or YAML string)
```python
from hyperpyyaml import load_hyperpyyaml

base = """
n_layers: 4
out_folder: results/exp1
model:
  hidden: !ref <n_layers> * 100
"""

params = load_hyperpyyaml(
    base,
    overrides={"n_layers": 6, "out_folder": "results/exp2"},
)
params["model"]["hidden"]     # 600

# Overrides may also be given as a YAML string; nested overrides merge:
params = load_hyperpyyaml(base, overrides="n_layers: 6\nmodel: {hidden: 700}")
params["model"]               # {'hidden': 700}

# Strict override matching is on by default:
try:
    load_hyperpyyaml("a: 1", overrides={"nope": 2})
except KeyError as err:
    print(err)                # Override 'nope' not found in: ['a']
```

#### Error handling
```python
from hyperpyyaml import load_hyperpyyaml

# Reference to a nonexistent key -> ValueError
try:
    load_hyperpyyaml("a: 1\nb: !ref <missing>")
except ValueError as err:
    print(err)                # The reference "missing" is not valid

# Nonexistent target -> ImportError
try:
    load_hyperpyyaml("a: !new:no.such.module.Class")
except ImportError as err:
    print(err)                # There is no such class as no.such.module.Class

# Wrong constructor arguments -> TypeError with prefixed message
try:
    load_hyperpyyaml("a: !new:collections.Counter\n  not_a_counter_arg: 1")
except TypeError as err:
    print(err)                # ('Invalid argument to class collections.Counter', ...)

# Object-producing !applyref -> RepresenterError with hint
try:
    load_hyperpyyaml("a: !applyref:collections.Counter\n  x: 1")
except Exception as err:
    print(type(err).__name__, err.args[0])
```

#### Custom loader
```python
import yaml
from hyperpyyaml import load_hyperpyyaml

params = load_hyperpyyaml("a: 1\nb: !ref <a>", loader=yaml.Loader)
params["b"]                   # 1
```
```

--------------------------------

### !name:operator.add

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/yaml-tags.md

Locates a class or function without instantiating it. Calling the returned entity with arguments returns the result directly.

```yaml
add: !name:operator.add
```

--------------------------------

### Catch ValueError for mismatched overrides

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/errors.md

Demonstrates catching the ValueError raised when overrides are non-mapping or mismatched. The error message includes the overrides list.

```python
from hyperpyyaml import load_hyperpyyaml, resolve_references

try:
    load_hyperpyyaml("a: 1", overrides=[1, 2])
except ValueError as err:
    print(err)
# "The structure of the overrides doesn't match the structure of the document: ", [1, 2]
```

--------------------------------

### dump_hyperpyyaml(yaml_tree, output_stream, *args, **kwargs)

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/dump_hyperpyyaml.md

Serializes a Python tree back to YAML, preserving HyperPyYAML placeholder and reference tags. It is the dump-side counterpart of load_hyperpyyaml and is typically paired with the Placeholder and RefTag wrapper classes.

```APIDOC
## dump_hyperpyyaml(yaml_tree, output_stream, *args, **kwargs)

### Description
Serializes a Python tree back to YAML, preserving HyperPyYAML placeholder and reference tags. It is the dump-side counterpart of `load_hyperpyyaml` and is typically paired with the `Placeholder` and `RefTag` wrapper classes.

### Signature
```python
def dump_hyperpyyaml(yaml_tree, output_stream, *args, **kwargs):
```

### Parameters
- **yaml_tree** (dict) - Required - An object to dump. Any `RefTag` / `Placeholder` values anywhere in the tree are represented as `!ref` / `!PLACEHOLDER` scalars.
- **output_stream** (stream) - Required - A file stream (or `io.StringIO`) for putting the YAML.
- **\*args, \*\*kwargs** (—) - Optional - Forwarded unchanged to `ruamel.yaml.YAML().dump()`.

### Behavior
From source (`core.py:260-263`):

```python
ruamel_yaml = ruamel.yaml.YAML()
ruamel_yaml.representer.add_representer(RefTag, RefTag.to_yaml)
ruamel_yaml.representer.add_representer(Placeholder, Placeholder.to_yaml)
ruamel_yaml.dump(yaml_tree, output_stream, *args, **kwargs)
```

A fresh `ruamel.yaml.YAML()` instance is created on each call; only the representers for `RefTag` and `Placeholder` are added, so any other non-trivial Python object in the tree raises `ruamel.yaml.representer.RepresenterError`.

### Return Value
`None` — output is written to `output_stream`.

### Errors
- `RepresenterError` — a value in `yaml_tree` (other than `RefTag`/`Placeholder` and YAML-native types) cannot be represented.
- Any errors raised by `ruamel.yaml.YAML().dump()` (e.g. `TypeError` for non-mapping roots) are propagated.

### Examples

#### Basic use: writing a template with placeholders

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, RefTag, Placeholder

tree = {
    "data_folder": Placeholder(),
    "examples": {"ex1": RefTag("<data_folder>/ex1.wav")},
}

out = StringIO()
dump_hyperpyyaml(tree, out)

print(out.getvalue())
# data_folder: !PLACEHOLDER
# examples:
#   ex1: !ref <data_folder>/ex1.wav
```

#### Round trip with `load_hyperpyyaml` (replace placeholders, then load)

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, load_hyperpyyaml, RefTag, Placeholder

tree = {
    "data_folder": Placeholder(),
    "preprocessed": RefTag("<data_folder>/preprocessed"),
}

buf = StringIO()
dump_hyperpyyaml(tree, buf)

# Fill in the missing value via overrides, then load normally:
loaded = load_hyperpyyaml(buf.getvalue(), overrides={"data_folder": "data/speech"})
loaded["data_folder"]   # 'data/speech'
loaded["preprocessed"]  # 'data/speech/preprocessed'
```

#### Forwarding dump arguments

```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, Placeholder

buf = StringIO()
dump_hyperpyyaml({"a": Placeholder(), "b": 3}, buf)
```

### See Also
- [RefTag.md](RefTag.md) — wrapper class dumped as `!ref <...>`.
- [Placeholder.md](Placeholder.md) — wrapper class dumped as `!PLACEHOLDER`.
- [load_hyperpyyaml.md](load_hyperpyyaml.md) — the loading counterpart.
- [types.md](../types.md) — type table for the wrapper classes.
```

--------------------------------

### TestThing class with from_keys classmethod

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/types.md

Test-support class used by the test suite to exercise constructors with dynamic attributes. Not part of the intended public API. The `from_keys` classmethod sets `specific_key` from `kwargs["thing1"]`.

```python
class TestThing:
    def __init__(self, *args, **kwargs):
        self.args = args
        self.kwargs = kwargs

    @classmethod
    def from_keys(cls, args, kwargs):
        obj = cls()
        obj.specific_key = kwargs["thing1"]
        obj.args = args
        obj.kwargs = kwargs
        return obj
```

--------------------------------

### Placeholder

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/types.md

A wrapper class representing a YAML placeholder tag (!PLACEHOLDER). It is accepted by dump_hyperpyyaml and serialized as a !PLACEHOLDER scalar with an empty value.

```APIDOC
## Placeholder

### Description
A wrapper class representing a YAML placeholder tag (!PLACEHOLDER). It is accepted by dump_hyperpyyaml and serialized as a !PLACEHOLDER scalar with an empty value.

### Class Definition
```python
class Placeholder:
    yaml_tag = "!PLACEHOLDER"

    @classmethod
    def to_yaml(cls, representer, node):
        return representer.represent_scalar(cls.yaml_tag, "")
```

### Fields
- **yaml_tag** (str, class attribute) - "!PLACEHOLDER" - The YAML tag emitted for instances.

No instance fields. Instances take no constructor arguments.

### Usage
- **Accepted by:** dump_hyperpyyaml(yaml_tree, ...) - represented as a !PLACEHOLDER scalar with an empty value.
- **Produced by:** never on the load path - a !PLACEHOLDER in a loaded document raises ValueError unless replaced by overrides.
```

--------------------------------

### Placeholder.to_yaml

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/Placeholder.md

Class method that represents a Placeholder instance as a YAML scalar node tagged !PLACEHOLDER with an empty value. This is used by the YAML representer during dumping.

```APIDOC
## Placeholder.to_yaml

### Description
Class method that represents a Placeholder instance as a YAML scalar node tagged !PLACEHOLDER with an empty value. This is used by the YAML representer during dumping.

### Method
Class method

### Parameters
- **representer** (ruamel.yaml.representer.BaseRepresenter) - Required - The ruamel representer instance supplied by ruamel.yaml.YAML().dump().
- **node** (Placeholder) - Required - The instance being represented.

### Returns
A scalar node tagged !PLACEHOLDER with an empty value.

### Example
```python
from hyperpyyaml import Placeholder
# Typically called internally by dump_hyperpyyaml
```
```

--------------------------------

### !new:collections.Counter with positional arguments

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/yaml-tags.md

Constructs an instance, passing sequence children as positional arguments. Here the string 'abracadabra' is passed to collections.Counter to count character occurrences.

```yaml
foo: !new:collections.Counter              # Counter('abracadabra')
  - abracadabra
```

--------------------------------

### RefTag.to_yaml(representer, node)

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/RefTag.md

This classmethod is called by the YAML representer to convert a `RefTag` instance into a YAML scalar node tagged `!ref`. It uses the provided representer to create a scalar with the tag `!ref` and the node's `ref_str` as its value.

```APIDOC
## RefTag.to_yaml(representer, node)

### Description
This classmethod is called by the YAML representer to convert a `RefTag` instance into a YAML scalar node tagged `!ref`. It uses the provided representer to create a scalar with the tag `!ref` and the node's `ref_str` as its value.

### Method
Classmethod

### Endpoint
`RefTag.to_yaml(representer, node)`

### Parameters
#### Path Parameters
- **representer** (BaseRepresenter) - Required - The ruamel representer instance supplied by `ruamel.yaml.YAML().dump()`.
- **node** (RefTag) - Required - The instance being represented.

### Returns
A scalar node tagged `!ref` whose value is the `ref_str` of the node.

### Example
```python
from io import StringIO
from hyperpyyaml import dump_hyperpyyaml, RefTag

tree = {
    "output_folder": "results/asr",
    "model_path": RefTag("<output_folder>/model.ckpt"),
}

buf = StringIO()
dump_hyperpyyaml(tree, buf)
print(buf.getvalue())
# output_folder: results/asr
# model_path: !ref <output_folder>/model.ckpt
```
```

--------------------------------

### RefTag class definition

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/RefTag.md

The exact class definition from source, including the yaml_tag attribute and to_yaml classmethod.

```python
class RefTag:
    """Class for dumping !ref tags to yaml

    Arguments
    ---------
    ref_str : str
        String including yaml keys in `<key>` notation

    Example
    -------
    See ``dump_hyperpyyaml``
    """

    yaml_tag = "!ref"

    def __init__(self, ref_str):
        self.ref_str = ref_str

    @classmethod
    def to_yaml(cls, representer, node):
        return representer.represent_scalar(cls.yaml_tag, node.ref_str)
```

--------------------------------

### Catch ValueError for unreplaced !PLACEHOLDER

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/errors.md

Shows the error message and a Python snippet that catches the ValueError raised when a !PLACEHOLDER is not replaced. The error message includes the fully qualified key path.

```text
ValueError: 'data_folder' is a !PLACEHOLDER and must be replaced.
```

```python
from hyperpyyaml import load_hyperpyyaml

try:
    load_hyperpyyaml("data_folder: !PLACEHOLDER\nepochs: 10")
except ValueError as err:
    print(err)   # 'data_folder' is a !PLACEHOLDER and must be replaced.
```

--------------------------------

### Referencing Sub-nodes with !ref

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Reference nested nodes or calculated values using brackets and the !ref tag.

```yaml
block_index: 1
cnn1:
    out_channels: !ref <block_index> * 64
    kernel_size: (3, 3)
cnn2: 
    out_channels: !ref <cnn1[out_channels]>
    kernel_size: (3, 3)
```

--------------------------------

### resolve_references(yaml_stream, overrides=None, overrides_must_match=False)

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/resolve_references.md

Resolves inter-document references, copies, includes, and applyrefs in a YAML stream, applies overrides, and returns a YAML-formatted stream with everything resolved to plain YAML.

```APIDOC
## resolve_references(yaml_stream, overrides=None, overrides_must_match=False)

### Description
Resolves inter-document references, copies, includes, and applyrefs in a YAML stream, applies overrides, and returns a YAML-formatted stream with everything resolved to plain YAML.

### Method
Function call

### Endpoint
resolve_references

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **yaml_stream** (stream) - Required - A file-like object or string with the contents of a YAML file written with the HyperPyYAML syntax. If the object has a `.name` attribute (e.g. an open file), `!include:` paths are resolved relative to `os.path.dirname(os.path.realpath(yaml_stream.name))`; otherwise `!include:` paths are used as-is.
- **overrides** (mapping or str) - Optional - Replacement values, either a nested mapping or a YAML-formatted string (loaded with ruamel.yaml). Merged into the preview tree with `recursive_update`.
- **overrides_must_match** (bool) - Optional - Whether an error is thrown when an override does not match a corresponding key in the yaml_stream. This is the opposite default from `load_hyperpyyaml` because `resolve_references` doesn't need to be as strict by default.

### Request Example
```python
>>> 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'
```

### Response
#### Success Response (200)
- **stream** (io.StringIO) - An `io.StringIO` containing the resolved, YAML-formatted stream, positioned at the beginning (`stream.seek(0)` was called). The returned text has no remaining `!ref`, `!copy`, `!include:` or `!applyref:` tags; references have been substituted into the scalar values.

#### Response Example
```python
'constants:\n  a: 4\n  b: 4\n'
```
```

--------------------------------

### Function Result References with !applyref

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/README.md

Use !applyref to reference the return value of a function, supporting various argument passing styles.

```yaml
# 1. Pass the positional and keyword arguments at the same time. Like `!!python/object/apply:module.function` in pyyaml
c: !applyref:sorted
    _args: 
        - [3, 4, 1, 2]
    _kwargs:
        reverse: False
d: !ref <c>-<c>

# 2. Only pass the keyword arguments
e: !applyref:random.randint
    a: 1
    b: 3
f: !ref <e><e>

# 3. Only pass the positional arguments
g: !applyref:random.randint
    - 1
    - 3
h: !ref <g><g>

# 4. No arguments
i: !applyref:random.random
j: !ref <i><i>
```

--------------------------------

### Function signature of load_hyperpyyaml

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/load_hyperpyyaml.md

The exact function signature from the source. It accepts a YAML stream, optional overrides, a flag to enforce override matching, and a custom loader class.

```python
def load_hyperpyyaml(
    yaml_stream, overrides=None, overrides_must_match=True, loader=ruamel.yaml.Loader
):
```

--------------------------------

### resolve_references function signature

Source: https://github.com/speechbrain/hyperpyyaml/blob/main/_autodocs/api-reference/resolve_references.md

The function signature for resolve_references as defined in the source.

```python
def resolve_references(yaml_stream, overrides=None, overrides_must_match=False):
```
Tokens:
Raw