ruamel.yaml

https://yaml.dev/doc/ruamel.yaml/
Admin
ruamel.yaml is a YAML 1.2 loader/dumper package for Python that supports round-trip preservation of...
Tokens:24,188
Snippets:182
Trust Score:5.2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install ruamel.yaml with --no-deps and ruamel.yaml.clib

Source: https://yaml.dev/doc/ruamel.yaml

Install ruamel.yaml without dependencies and explicitly install ruamel.yaml.clib. The source notes this solution did not work for at least one setup.

```bash
    python -m pip install --no-deps ruamel.yaml ruamel.yaml.clib

```

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

### Import and instantiate YAML

Source: https://yaml.dev/doc/ruamel.yaml/detail

Import the YAML class and create a YAML instance. This setup is assumed in the following examples on this page.

```python
from ruamel.yaml import YAML
yaml = YAML()

```

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

### Install ruamel.yaml.cmd commandline utility

Source: https://yaml.dev/doc/ruamel.yaml/install

Install the commandline utility yaml for round-trip testing, re-indenting, and conversion of YAML files (JSON, INI, HTML tables).

```bash
pip install ruamel.yaml.cmd

```

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

### Install ruamel.yaml from PyPI

Source: https://yaml.dev/doc/ruamel.yaml/install

Install ruamel.yaml from PyPI. For jinja2/YAML template support, use pip install ruamel.yaml[jinja2] (quote the argument due to brackets).

```bash
pip install ruamel.yaml

```

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

### Upgrade pip, setuptools, and wheel

Source: https://yaml.dev/doc/ruamel.yaml/install

Upgrade pip, setuptools, and wheel in your environment before installing ruamel.yaml. Requires setuptools>=20.6.8 for environment marker support.

```bash
pip install -U pip setuptools wheel

```

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

### Install python-devel on CentOS

Source: https://yaml.dev/doc/ruamel.yaml/install

Install Python development headers on CentOS (7) based systems to enable the faster C loader and emitter.

```bash
sudo yum install python-devel

```

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

### Install python3-dev on Debian

Source: https://yaml.dev/doc/ruamel.yaml/install

Install Python header files on Debian systems to enable the faster C loader and emitter. Omit python3-dev if not using Python 3.

```bash
sudo apt-get install python3-dev

```

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

### Build PDF documentation with ryd

Source: https://yaml.dev/doc/ruamel.yaml/contributing

Run this command from the ruamel.yaml repository root to build PDF documentation from .ryd files. Quoting may not be necessary depending on your shell. ryd will check for single backquotes and automatically run any example programs included in the documentation.

```bash
ryd --pdf '**/*.ryd'

```

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

### Register and load a dataclass with ruamel.yaml

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Shows how to define a dataclass with a custom YAML tag, register it with ruamel.yaml, and load a YAML document into an instance. Since version 0.17.34, __post_init__() is called on load, so the xyz field is computed from abc and klm. The example prints dc2.xyz=50 after loading.

```python
from typing import ClassVar
from dataclasses import dataclass
import ruamel.yaml

@dataclass
class DC:
    yaml_tag: ClassVar = '!dc_example'   # if you don't want !DC as tag
    abc: int
    klm: int
    xyz: int = 0

    def __post_init__(self) -> None:
        self.xyz = self.abc + self.klm

yaml = ruamel.yaml.YAML()
yaml.register_class(DC)
dc = DC(abc=5, klm=42)
assert dc.xyz == 47

yaml_str = """\
!dc_example
abc: 13
klm: 37
"""
dc2 = yaml.load(yaml_str)
print(f'{dc2.xyz=}')

```

```text
dc2.xyz=50

```

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

### Multiple dumps with explicit start and transform

Source: https://yaml.dev/doc/ruamel.yaml/example

Dump the same data three times to produce a multi-document stream. The first uses default indentation, the second uses yaml.indent(sequence=4, offset=2), and the third applies a custom transform function to adjust sequence indentation.

```python
import sys
from ruamel.yaml import YAML

data = {1: {1: [{1: 1, 2: 2}, {1: 1, 2: 2}], 2: 2}, 2: 42}

yaml = YAML()
yaml.explicit_start = True
yaml.dump(data, sys.stdout)
yaml.indent(sequence=4, offset=2)
yaml.dump(data, sys.stdout)


def sequence_indent_four(s):
    # this will fail on direclty nested lists: {1; [[2, 3], 4]}
    levels = []
    ret_val = ''
    for line in s.splitlines(True):
        ls = line.lstrip()
        indent = len(line) - len(ls)
        if ls.startswith('- '):
            if not levels or indent > levels[-1]:
                levels.append(indent)
            elif levels:
                if indent < levels[-1]:
                    levels = levels[:-1]
            # same -> do nothing
        else:
            if levels:
                if indent <= levels[-1]:
                    while levels and indent <= levels[-1]:
                        levels = levels[:-1]
        ret_val += '  ' * len(levels) + line
    return ret_val

yaml = YAML()
yaml.explicit_start = True
yaml.dump(data, sys.stdout, transform=sequence_indent_four)

```

```yaml
---
1:
  1:
  - 1: 1
    2: 2
  - 1: 1
    2: 2
  2: 2
2: 42
---
1:
  1:
    - 1: 1
      2: 2
    - 1: 1
      2: 2
  2: 2
2: 42
---
1:
  1:
    - 1: 1
      2: 2
    - 1: 1
      2: 2
  2: 2
2: 42

```

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

### yaml.explicit_start attribute

Source: https://yaml.dev/doc/ruamel.yaml/api

The explicit_start attribute controls whether an explicit document start marker (---) is written at the beginning of the output.

```APIDOC
## [YAML] yaml.explicit_start attribute

### Description
Controls whether an explicit document start marker (---) is written at the beginning of the output.

### Method
Attribute assignment

### Endpoint
yaml.explicit_start

### Parameters
#### Attribute Parameters
- **explicit_start** (boolean) - Required - If True, write an explicit document start marker; if False, do not.

### Request Example
```python
ymlo.explicit_start = True
```

### Response
#### Success Response
- No return value. The attribute is set on the YAML instance.

#### Response Example
```python
ymlo.explicit_start = True
```
```

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

### Adding comments with yaml_add_eol_comment

Source: https://yaml.dev/doc/ruamel.yaml/detail

Demonstrates adding or replacing comments on block-style collections using yaml_add_eol_comment. The key is the element index for lists and the actual key for dictionaries. The column for a new comment is derived from the previous, next, or preceding comment column. If the comment does not start with '#', it is added automatically. When a comment contains newlines, the following line must be empty, contain only spaces, or start with '#'.

```python
from __future__ import print_function

import sys
import ruamel.yaml

yaml = ruamel.yaml.YAML()  # defaults to round-trip

inp = """\
abc:
  - a     # comment 1
xyz:
  a: 1    # comment 2
  b: 2
  c: 3
  d: 4
  e: 5
  f: 6 # comment 3
"""

data = yaml.load(inp)
data['abc'].append('b')
data['abc'].yaml_add_eol_comment('comment 4', 1)  # takes column of comment 1
data['xyz'].yaml_add_eol_comment('comment 5', 'c')  # takes column of comment 2
data['xyz'].yaml_add_eol_comment('comment 6', 'e')  # takes column of comment 3
data['xyz'].yaml_add_eol_comment('comment 7\n\n# that\'s all folks', 'd', column=20)

yaml.dump(data, sys.stdout)

```

```yaml
abc:
- a       # comment 1
- b       # comment 4
xyz:
  a: 1    # comment 2
  b: 2
  c: 3    # comment 5
  d: 4              # comment 7

# that's all folks
  e: 5 # comment 6
  f: 6 # comment 3

```

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

### Allow duplicate keys in ruamel.yaml

Source: https://yaml.dev/doc/ruamel.yaml/api

Allows duplicate keys in mappings when using the new API (starting 0.15.1). Set allow_duplicate_keys to True before loading. When a duplicate key is found, it and its value are discarded as per YAML 1.1.

```python
yaml = ruamel.yaml.YAML()
yaml.allow_duplicate_keys = True
yaml.load(stream)

```

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

### Combine YAML documents from multiple files

Source: https://yaml.dev/doc/ruamel.yaml/api

Combines multiple YAML documents from separate files into one output stream using the context manager. The output is a valid, uniformly indented YAML file. Note that concatenating files with cat may produce a single document if the second file lacks a document start marker.

```python
list_of_filenames = ['x.yaml', 'y.yaml', ]
with YAML(output=sys.stdout) as yaml:
        yaml.explicit_start = True
        for path in list_of_filename:
            with open(path) as fp:
                yaml.dump(yaml.load(fp))

```

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

### Inconsistently indented YAML with top-level sequence indented 2

Source: https://yaml.dev/doc/ruamel.yaml/detail

Example of inconsistently indented YAML where the top-level sequence is indented 2 without offset and the other sequence is indented 4 with offset 2.

```yaml
- key:
    - foo
    - bar

```

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

### Inconsistently indented YAML with b indented 3, c indented 4

Source: https://yaml.dev/doc/ruamel.yaml/detail

Example of inconsistently indented YAML where b is indented 3 and c is indented 4 positions. Such indentation cannot be preserved and will be normalized on the first round-trip.

```yaml
a:
   b:
       c: 1

```

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

### Use mlget to access nested data in round-tripped YAML

Source: https://yaml.dev/doc/ruamel.yaml/detail

Shows how to use the mlget method on data loaded with ruamel.yaml's round-trip loader to access nested values. The example asserts that data.mlget(['a', 1, 'd', 'f'], list_ok=True) returns 196.

```python
yaml_str = """\
a:
- b:
  c: 42
- d:
    f: 196
  e:
    g: 3.14
"""

data = yaml.load(yaml_str)

assert data.mlget(['a', 1, 'd', 'f'], list_ok=True) == 196

```

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

### Transform YAML dump output with transform parameter

Source: https://yaml.dev/doc/ruamel.yaml/basicuse

Transform the string representation of dumped YAML output. The `transform` parameter takes a function that receives the output string and returns a modified string. The example replaces newlines with `<\n`, which is not valid YAML.

```python
def tr(s):
    return s.replace('\n', '<\n')  # such output is not valid YAML!

yaml.dump(data, sys.stdout, transform=tr)

```

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

### Set yaml.max_depth to limit nesting depth

Source: https://yaml.dev/doc/ruamel.yaml/cve

Set the maximum nesting depth for the YAML loader to prevent recursion depth overflow when processing unchecked input. The example sets max_depth to 42, but Docker's compose.yaml files typically have a max_depth of only 4.

```python
yaml = ruamel.yaml.YAML()
yaml.max_depth = 42

```

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

### Override YAML.dump() to return a string

Source: https://yaml.dev/doc/ruamel.yaml/example

Subclass YAML to override dump() so that when the stream parameter is omitted, the YAML output is returned as a string instead of being written to a stream. This provides a memory-inefficient but convenient way to get a string representation, similar to the old API's behavior.

```python
import sys
from ruamel.yaml import YAML
from ruamel.yaml.compat import StringIO

class MyYAML(YAML):
    def dump(self, data, stream=None, **kw):
        inefficient = False
        if stream is None:
            inefficient = True
            stream = StringIO()
        YAML.dump(self, data, stream, **kw)
        if inefficient:
            return stream.getvalue()

yaml = MyYAML()   # or typ='safe'/'unsafe' etc

```

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

### Before 0.15.0: safe_load and safe_dump with default_flow_style

Source: https://yaml.dev/doc/ruamel.yaml/api

Shows the pre-0.15.0 API for loading and dumping YAML with ruamel.yaml, using yaml.safe_load and yaml.safe_dump with a file stream and the default_flow_style=False keyword argument.

```python
from pathlib import Path
from ruamel import yaml

data = yaml.safe_load("abc: 1")
out = Path('/tmp/out.yaml')
with out.open('w') as fp:
    yaml.safe_dump(data, fp, default_flow_style=False)

```

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

### YAML() constructor

Source: https://yaml.dev/doc/ruamel.yaml/api

The YAML() constructor is the primary entry point for creating a YAML instance. It accepts optional keyword arguments to select the type of loader/dumper and whether to use pure Python or C-based implementations.

```APIDOC
## [YAML] YAML() constructor

### Description
Creates a YAML instance for dumping and loading YAML data. The constructor accepts optional keyword arguments to select the type of loader/dumper and whether to use pure Python or C-based implementations.

### Method
Constructor

### Endpoint
YAML(typ='safe', pure=True)

### Parameters
#### Constructor Parameters
- **typ** (string) - Optional - The type of YAML loader/dumper. Defaults to 'rt' (round-trip). Common values include 'safe', 'rt', 'base', 'unsafe'.
- **pure** (boolean) - Optional - If True, use pure Python implementation; if False, use C-based implementation when available.

### Request Example
```python
yaml = YAML(typ='safe', pure=True)
```

### Response
#### Success Response
- **yaml** (YAML instance) - A YAML instance configured with the specified options.

#### Response Example
```python
yaml = YAML(typ='safe', pure=True)
```
```

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

### After 0.15.0: YAML instance with typ='safe' and default_flow_style attribute

Source: https://yaml.dev/doc/ruamel.yaml/api

Shows the post-0.15.0 API for loading and dumping YAML with ruamel.yaml, using a YAML instance with typ='safe' and setting default_flow_style as an attribute before calling load and dump.

```python
from pathlib import Path
from ruamel.yaml import YAML

yaml = YAML(typ='safe')
yaml.default_flow_style = False
data = yaml.load("abc: 1")
out = Path('/tmp/out.yaml')
yaml.dump(data, out)

```

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

### Load YAML with simple from_yaml (incorrect)

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Attempts to load YAML with a custom from_yaml that constructs a mapping directly. This results in missing siblings for nested objects, as shown in the output.

```python
from pathlib import Path
import ruamel.yaml

class Person:
    def __init__(self, name, siblings=None):
        self.name = name
        self.siblings = [] if siblings is None else siblings

    def __repr__(self):
        return f'Person(name: {self.name}, siblings: {self.siblings})'

    @classmethod
    def from_yaml(cls, constructor, node):
        data = ruamel.yaml.CommentedMap()
        constructor.construct_mapping(node, maptyp=data, deep=True)
        return cls(**data)


path = Path('/tmp/arya.yaml')
yaml = ruamel.yaml.YAML()
yaml.register_class(Person)
data = yaml.load(path)
print(data)
```

```text
Person(name: Arya, siblings: [Person(name: Sansa, siblings: [None])])
```

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

### Load YAML with ruamel.yaml safe loader

Source: https://yaml.dev/doc/ruamel.yaml/basicuse

Load a YAML document with the safe loader. `doc` can be a file pointer (object with `.read()`), a string, or a `pathlib.Path()` instance. `typ='safe'` matches the old `safe_load()` behavior, resolving no unknown tags. Use `pure=True` to force the pure Python implementation; otherwise faster C libraries are used when available, but they behave slightly differently and sometimes more like a YAML 1.1 loader.

```python
from ruamel.yaml import YAML

yaml=YAML(typ='safe')   # default, if not specfied, is 'rt' (round-trip)
yaml.load(doc)

```

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

### Version-aware safe load and dump

Source: https://yaml.dev/doc/ruamel.yaml/api

Version-aware loading and dumping using the SafeLoader. For ruamel.yaml versions before 0.15, use the old API; for 0.15 and later, use the new YAML instance with typ='safe' and pure=True.

```python
if ruamel.yaml.version_info < (0, 15):
    data = yaml.safe_load(istream)
    yaml.safe_dump(data, ostream)
else:
    yml = ruamel.yaml.YAML(typ='safe', pure=True)  # 'safe' load and dump
    data = yml.load(istream)
    yml.dump(data, ostream)

```

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

### Load YAML into Person class with default loader

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Loads a YAML file into a Person class instance using ruamel.yaml's default class registration. The output shows the recursive structure with siblings.

```python
from pathlib import Path
import ruamel.yaml

class Person:
    def __init__(self, name, siblings=None):
        self.name = name
        self.siblings = [] if siblings is None else siblings

    def __repr__(self):
        return f'Person(name: {self.name}, siblings: {self.siblings})'

path = Path('/tmp/arya.yaml')
yaml = ruamel.yaml.YAML()
yaml.register_class(Person)
data = yaml.load(path)

print(data)
```

```text
Person(name: Arya, siblings: [Person(name: Sansa, siblings: [Person(name: Arya, siblings: [...])])])
```

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

### Dump multi-document YAML with context manager

Source: https://yaml.dev/doc/ruamel.yaml/api

Uses YAML as a context manager to dump multiple documents to a single output stream. Requires specifying the output at creation time, works only for dumping, and does not support transform. Within the context, dump() cannot take a second stream argument and dump_all() is not allowed.

```python
with YAML(output=sys.stdout) as yaml:
        yaml.explicit_start = True
        for data in yaml.load_all(Path(multi_document_filename)):
            # do something on data
            yaml.dump(data)

```

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

### Run mypy with strict typing

Source: https://yaml.dev/doc/ruamel.yaml/contributing

Command to run mypy from the directory containing the ruamel link. Uses --py2, --strict, --follow-imports silent, and targets ruamel/yaml/*.py. Should produce no errors or warnings.

```bash
mypy --py2 --strict --follow-imports silent ruamel/yaml/*.py

```

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

### Preserve anchors, references, and key merging

Source: https://yaml.dev/doc/ruamel.yaml/example

Load YAML with anchors, references, and key merging. The merged keys are accessible via [] and .get(), as shown by the assertion.

```python
from ruamel.yaml import YAML

inp = """\
- &CENTER {x: 1, y: 2}
- &LEFT {x: 0, y: 2}
- &BIG {r: 10}
- &SMALL {r: 1}
# All the following maps are equal:
# Explicit keys
- x: 1
  y: 2
  r: 10
  label: center/big
# Merge one map
- <<: *CENTER
  r: 10
  label: center/big
# Merge multiple maps
- <<: [*CENTER, *BIG]
  label: center/big
# Override
- <<: [*BIG, *LEFT, *SMALL]
  x: 1
  label: center/big
"""

yaml = YAML()
data = yaml.load(inp)
assert data[7]['y'] == 2

```

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

### Toggle compact notation with yaml.compact()

Source: https://yaml.dev/doc/ruamel.yaml/example

Control compact notation for sequences within sequences and mappings within sequences using yaml.compact(). The output shows the default compact style and the non-compact style with seq_seq=False and seq_map=False.

```python
import sys
from ruamel.yaml import YAML

d = [dict(b=2), [3, 4]]
yaml = YAML()
yaml.dump(d, sys.stdout)
print('='*15)
yaml = YAML()
yaml.compact(seq_seq=False, seq_map=False)
yaml.dump(d, sys.stdout)

```

```yaml
- b: 2
- - 3
  - 4
===============
-
  b: 2
-
  - 3
  - 4

```

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

### Version-aware CSafeLoader load and round-trip dump

Source: https://yaml.dev/doc/ruamel.yaml/api

Version-aware loading with CSafeLoader and dumping with RoundTripLoader. For versions before 0.15, use the old API; for 0.15 and later, use two YAML instances: one for safe loading and one for round-trip dumping with width and explicit_start set.

```python
if ruamel.yaml.version_info < (0, 15):
    data = yaml.load(istream, Loader=yaml.CSafeLoader)
    yaml.round_trip_dump(data, ostream, width=1000, explicit_start=True)
else:
    yml = ruamel.yaml.YAML(typ='safe')
    data = yml.load(istream)
    ymlo = ruamel.yaml.YAML()   # or yaml.YAML(typ='rt')
    ymlo.width = 1000
    ymlo.explicit_start = True
    ymlo.dump(data, ostream)

```

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

### flake8 configuration

Source: https://yaml.dev/doc/ruamel.yaml/contributing

Configuration file for flake8, located at ~/.config/flake8. Sets show-source to True, max-line-length to 95, and ignores F405 to allow 'from xxx import *'.

```ini
[flake8]
show-source = True
max-line-length = 95
ignore = F405

```

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

### ruamel.yaml.clibz test matrix

Source: https://yaml.dev/doc/ruamel.yaml

Test matrix for ruamel.yaml.clibz covering Python versions, operating systems, architectures, and Zig version constraints.

```text
    Python versions: 3.9 - 3.14
    OS-es:           Linux, Alpine (musl), macOS, Windows
    Architectures:   Intel/AMD, Arm (and others), in 64 and some also in 32 bit versions
    Zig version:     ziglang < 0.16 is taken from PyPI

```

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

### Block sequence indentation with yaml.indent(sequence=4)

Source: https://yaml.dev/doc/ruamel.yaml/detail

Shows the default dump of a block sequence and the output when yaml.indent(sequence=4) is specified. The indentation is counted to the beginning of the sequence element.

```yaml
x:
- b: 1
- 2

```

```yaml
x:
-   b: 1
-   2

```

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

### Load YAML with correct from_yaml using yield

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Correctly loads YAML by yielding an empty Person instance and then populating it, preserving recursive references. The output shows the full structure.

```python
from pathlib import Path
import ruamel.yaml

class Person:
    def __init__(self, name, siblings=None):
        self.name = name
        self.siblings = [] if siblings is None else siblings

    def __repr__(self):
        return f'Person(name: {self.name}, siblings: {self.siblings})'

    @classmethod
    def from_yaml(cls, constructor, node):
        person = Person(name='')
        yield person
        data = ruamel.yaml.CommentedMap()
        constructor.construct_mapping(node, maptyp=data, deep=True)
        for k, v in data.items():
            setattr(person, k, v)


path = Path('/tmp/arya.yaml')
yaml = ruamel.yaml.YAML()
yaml.register_class(Person)
data = yaml.load(path)
print(data)
```

```text
Person(name: Arya, siblings: [Person(name: Sansa, siblings: [Person(name: Arya, siblings: [...])])])
```

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

### Register a class with YAML.register_class()

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Registers a Python class with a YAML instance using YAML.register_class() so that instances can be dumped. The output uses the class name as the tag (e.g., !User).

```python
import sys
import ruamel.yaml


class User:
    def __init__(self, name, age):
        self.name = name
        self.age = age


yaml = ruamel.yaml.YAML()
yaml.register_class(User)
yaml.dump([User('Anthon', 18)], sys.stdout)

```

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

### Register a class with custom yaml_tag and to_yaml/from_yaml

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Registers a class with a custom yaml_tag and custom to_yaml/from_yaml classmethods. The to_yaml method represents the object as a scalar, and from_yaml reconstructs it from the scalar value.

```python
import sys
import ruamel.yaml


class User:
    yaml_tag = u'!user'

    def __init__(self, name, age):
        self.name = name
        self.age = age

    @classmethod
    def to_yaml(cls, representer, node):
        return representer.represent_scalar(cls.yaml_tag,
                                            u'{.name}-{.age}'.format(node, node))

    @classmethod
    def from_yaml(cls, constructor, node):
        return cls(*node.value.split('-'))


yaml = ruamel.yaml.YAML()
yaml.register_class(User)
yaml.dump([User('Anthon', 18)], sys.stdout)

```

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

### Dump multi-document YAML with list

Source: https://yaml.dev/doc/ruamel.yaml/api

Reads a multi-document YAML stream into a list and dumps it back. The 'normal' dump_all expects a list of documents. This is the traditional approach before the context manager was introduced.

```python
yaml = YAML()
data = list(yaml.load_all(in_path))
# do something on data[0], data[1], etc.
yaml.dump_all(data, out_path)

```

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

### Version-aware pathlib.Path round-trip load and dump

Source: https://yaml.dev/doc/ruamel.yaml/api

Version-aware loading and dumping from pathlib.Path instances using the round-trip loader. Defines a MyYAML subclass that preserves quotes and sets indentation, then uses it for both old and new API paths.

```python
# in myyaml.py
if ruamel.yaml.version_info < (0, 15):
    class MyYAML(yaml.YAML):
        def __init__(self):
            yaml.YAML.__init__(self)
            self.preserve_quotes = True
            self.indent(mapping=4, sequence=4, offset=2)
# in your code
try:
    from myyaml import MyYAML
except (ModuleNotFoundError, ImportError):
    if ruamel.yaml.version_info >= (0, 15):
        raise

# some pathlib.Path
from pathlib import Path
inf = Path('/tmp/in.yaml')
outf = Path('/tmp/out.yaml')

if ruamel.yaml.version_info < (0, 15):
    with inf.open() as ifp:
         data = yaml.round_trip_load(ifp, preserve_quotes=True)
    with outf.open('w') as ofp:
         yaml.round_trip_dump(data, ofp, indent=4, block_seq_indent=2)
else:
    yml = MyYAML()
    # no need for with statement when using pathlib.Path instances
    data = yml.load(inf)
    yml.dump(data, outf)

```

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

### Basic round-trip load, modify, and dump

Source: https://yaml.dev/doc/ruamel.yaml/example

Round-trip load a YAML string, modify a nested value, and dump the result to stdout. The output preserves comments and key order.

```python
import sys
from ruamel.yaml import YAML

inp = """\
# example
name:
  # details
  family: Smith   # very common
  given: Alice    # one of the siblings
"""

yaml = YAML()
code = yaml.load(inp)
code['name']['given'] = 'Bob'

yaml.dump(code, sys.stdout)

```

```yaml
# example
name:
  # details
  family: Smith   # very common
  given: Bob      # one of the siblings

```

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

### Output of dumping a registered User class

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Output of dumping a User instance registered with YAML.register_class(). The tag !User is derived from the class name.

```yaml
- !User
  name: Anthon
  age: 18

```

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

### Print YAML dump as a string

Source: https://yaml.dev/doc/ruamel.yaml/example

Use the custom MyYAML class to dump a dictionary and print the resulting YAML string. This replaces the old API's round_trip_dump() call that would add an extra empty line after the output.

```python
print(yaml.dump(dict(a=1, b=2)))

```

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

### Dump YAML to stdout with newline

Source: https://yaml.dev/doc/ruamel.yaml/example

The old API approach: dump to sys.stdout and then add a newline manually. This is the alternative to the string-returning method and is the recommended way to avoid the extra empty line.

```python
yaml.dump((dict(a=1, b=2)), sys.stdout)
print()  # or sys.stdout.write('\n')

```

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

### yaml.load(istream)

Source: https://yaml.dev/doc/ruamel.yaml/api

The load method reads YAML data from an input stream or path and returns the parsed Python object. It uses the loader type configured on the YAML instance.

```APIDOC
## [YAML] yaml.load(istream)

### Description
Loads YAML data from an input stream or path. The method is available on a YAML instance and uses the configured loader type.

### Method
load

### Endpoint
yaml.load(istream)

### Parameters
#### Parameters
- **istream** (stream or path) - Required - The input stream or path from which to read YAML data.

### Request Example
```python
data = yml.load(istream)
```

### Response
#### Success Response
- **data** (object) - The parsed YAML data as a Python object.

#### Response Example
```python
data = yml.load(istream)
```
```

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

### YAML.dump (context manager)

Source: https://yaml.dev/doc/ruamel.yaml/api

Dumps data to a multi-document YAML stream when used within a context manager.

```APIDOC
## [METHOD] YAML.dump (context manager)

### Description
When using `YAML()` as a context manager, `dump()` can be called multiple times to create a multi-document YAML stream. The output stream is specified at creation time.

### Method
`dump`

### Parameters
- **data** - Required - The data to dump.

### Notes
- Cannot use `dump()` with a second (stream) argument inside the context manager.
- Cannot use `dump_all()` inside the context manager.
- `transform` is not supported.

### Example
```python
import sys
from pathlib import Path
from ruamel.yaml import YAML

with YAML(output=sys.stdout) as yaml:
    yaml.explicit_start = True
    for data in yaml.load_all(Path(multi_document_filename)):
        # do something on data
        yaml.dump(data)
```
```

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

### Dump YAML with ruamel.yaml

Source: https://yaml.dev/doc/ruamel.yaml/basicuse

Dump a Python object to YAML. `s` can be a file pointer (object with `.write()`) or a `pathlib.Path()`. Stream to `sys.stdout` to display output. Setting `default_flow_style = False` produces block-style output.

```python
from ruamel.yaml import YAML

yaml=YAML()
yaml.default_flow_style = False
yaml.dump({'a': [1, 2]}, s)

```

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

### Indentation with yaml.indent(mapping=2, sequence=4, offset=2)

Source: https://yaml.dev/doc/ruamel.yaml/detail

Output when using yaml.indent(mapping=2, sequence=4, offset=2). The offset pushes the dash inwards within the space defined by sequence.

```yaml
x:
  y:
    - b: 1
    - 2

```

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

### YAML.dump_all

Source: https://yaml.dev/doc/ruamel.yaml/api

Dumps multiple YAML documents to a stream. The first argument should be a list of documents or an iterable.

```APIDOC
## [METHOD] YAML.dump_all

### Description
Dumps a list of documents to a stream. The first argument should be a list of documents or an iterable.

### Method
`dump_all`

### Parameters
- **documents** (list) - Required - List of documents to dump.
- **stream** - Required - Output stream (file, buffer, Path).

### Example
```python
from ruamel.yaml import YAML

yaml = YAML()
data = list(yaml.load_all(in_path))
# do something on data[0], data[1], etc.
yaml.dump_all(data, out_path)
```
```

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

### Top-level mapping with aligned colons

Source: https://yaml.dev/doc/ruamel.yaml/detail

Shows the desired top-level mapping layout when yaml.top_level_colon_align is set to True (and yaml.indent to 4). The alignment is calculated based on the longest key.

```yaml
library version: 1
comment        : |
    this is just a first try

```

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

### Set YAML instance attributes for dumping

Source: https://yaml.dev/doc/ruamel.yaml/api

Set attributes on a YAML() instance to control dumping behavior. Here allow_unicode is set to False, which affects how Unicode characters are output.

```python
yaml = YAML(typ='safe', pure=True)
yaml.allow_unicode = False

```

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

### Decorate a class with @yaml_object(yaml)

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Decorates a class with @yaml_object(yaml) to register it with the YAML instance. The YAML() instance must be created before the decorator is applied.

```python
import sys
from ruamel.yaml import YAML, yaml_object

yaml = YAML()


@yaml_object(yaml)
class User:
    yaml_tag = u'!user'

    def __init__(self, name, age):
        self.name = name
        self.age = age

    @classmethod
    def to_yaml(cls, representer, node):
        return representer.represent_scalar(cls.yaml_tag,
                                            u'{.name}-{.age}'.format(node, node))

    @classmethod
    def from_yaml(cls, constructor, node):
        return cls(*node.value.split('-'))


yaml.dump([User('Anthon', 18)], sys.stdout)

```

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

### Load YAML with C based SafeLoader

Source: https://yaml.dev/doc/ruamel.yaml/basicuse

Load YAML using the C based SafeLoader, which is inherited from libyaml/PyYAML and loads `0o52` as well as `052` as integer `42`.

```python
from ruamel.yaml import YAML

yaml=YAML(typ="safe")
yaml.load("""a:\n  b: 2\n  c: 3\n""")

```

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

### Output of dumping a User with custom tag

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Output of dumping a User instance with a custom yaml_tag and to_yaml method. The object is represented as a scalar with the tag !user.

```yaml
- !user Anthon-18

```

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

### yaml.allow_duplicate_keys

Source: https://yaml.dev/doc/ruamel.yaml/api

Configuration option to allow duplicate keys in YAML mappings when using the new API.

```APIDOC
## [CONFIG] yaml.allow_duplicate_keys

### Description
Set this attribute to `True` to allow duplicate keys in mappings when loading YAML. By default, duplicate keys are not allowed in the new API (starting 0.15.1).

### Configuration
- **allow_duplicate_keys** (boolean) - Set to `True` to allow duplicate keys.

### Example
```python
import ruamel.yaml

yaml = ruamel.yaml.YAML()
yaml.allow_duplicate_keys = True
yaml.load(stream)
```
```

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

### Load YAML with Python based SafeLoader

Source: https://yaml.dev/doc/ruamel.yaml/basicuse

Load YAML using the Python based SafeLoader, which supports YAML 1.2 and loads `052` as `52`.

```python
from ruamel.yaml import YAML

yaml=YAML(typ="safe", pure=True)
yaml.load("""a:\n  b: 2\n  c: 3\n""")

```

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

### yaml.indent(mapping=4, sequence=4, offset=2)

Source: https://yaml.dev/doc/ruamel.yaml/api

The indent method sets the indentation for mappings, sequences, and offset in the output. It is used to customize the formatting of dumped YAML.

```APIDOC
## [YAML] yaml.indent(mapping=4, sequence=4, offset=2)

### Description
Sets the indentation for mapping, sequence, and offset in the output. This method is used to customize the formatting of dumped YAML.

### Method
indent

### Endpoint
yaml.indent(mapping=4, sequence=4, offset=2)

### Parameters
#### Parameters
- **mapping** (integer) - Optional - Indentation for mappings. Defaults to 4.
- **sequence** (integer) - Optional - Indentation for sequences. Defaults to 4.
- **offset** (integer) - Optional - Offset for the indentation. Defaults to 2.

### Request Example
```python
self.indent(mapping=4, sequence=4, offset=2)
```

### Response
#### Success Response
- No return value. The indentation settings are applied to the YAML instance.

#### Response Example
```python
self.indent(mapping=4, sequence=4, offset=2)
```
```

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

### Use register_class() as a decorator

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Uses the register_class() method as a decorator to register a class with the YAML instance. The YAML instance must be available before the decorator is applied.

```python
import sys
import ruamel.yaml

yaml = ruamel.yaml.YAML()

@yaml.register_class
class User:
    yaml_tag = u'!user'

    def __init__(self, name, age):
        self.name = name
        self.age = age

    @classmethod
    def to_yaml(cls, representer, node):
        return representer.represent_scalar(cls.yaml_tag,
                                            u'{.name}-{.age}'.format(node, node))

    @classmethod
    def from_yaml(cls, constructor, node):
        return cls(*node.value.split('-'))


yaml.dump([User('Anthon', 18)], sys.stdout)

```

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

### Insert key at position with comment

Source: https://yaml.dev/doc/ruamel.yaml/example

Insert a new key at a specific position in a CommentedMap with an optional comment. The comment is aligned with the neighboring key's comment.

```python
import sys
from ruamel.yaml import YAML

yaml_str = """\
first_name: Art
occupation: Architect  # This is an occupation comment
about: Art Vandelay is a fictional character that George invents...
"""

yaml = YAML()
data = yaml.load(yaml_str)
data.insert(1, 'last name', 'Vandelay', comment="new key")
yaml.dump(data, sys.stdout)

```

```yaml
first_name: Art
last name: Vandelay    # new key
occupation: Architect  # This is an occupation comment
about: Art Vandelay is a fictional character that George invents...

```

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

### Explicit YAML document version

Source: https://yaml.dev/doc/ruamel.yaml/detail

Explicitly sets the YAML document version. For ruamel.yaml, x must be 1 or 2. If no version is set, version 1.2 is assumed.

```yaml
%YAML 1.x

```

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

### yaml.dump(data, ostream)

Source: https://yaml.dev/doc/ruamel.yaml/api

The dump method serializes a Python object to YAML and writes it to an output stream or path. It uses the dumper type configured on the YAML instance.

```APIDOC
## [YAML] yaml.dump(data, ostream)

### Description
Dumps a Python object to YAML format and writes it to an output stream or path. The method uses the dumper type configured on the YAML instance.

### Method
dump

### Endpoint
yaml.dump(data, ostream)

### Parameters
#### Parameters
- **data** (object) - Required - The Python object to dump.
- **ostream** (stream or path) - Required - The output stream or path to write the YAML data to.

### Request Example
```python
yml.dump(data, ostream)
```

### Response
#### Success Response
- No return value. The YAML data is written to the output stream.

#### Response Example
```python
yml.dump(data, ostream)
```
```

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

### Dump a class with self-referencing objects

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Dumps a class with self-referencing objects. The YAML output uses anchors and aliases to handle circular references.

```python
from pathlib import Path
import ruamel.yaml

class Person:
    def __init__(self, name, siblings=None):
        self.name = name
        self.siblings = [] if siblings is None else siblings

arya = Person('Arya')   
sansa = Person('Sansa')
arya.siblings.append(sansa)  # there are better ways to represent this
sansa.siblings.append(arya)

yaml = ruamel.yaml.YAML()
yaml.register_class(Person)

path = Path('/tmp/arya.yaml')
yaml.dump(arya, path)
print(path.read_text())

```

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

### Customize indentation with yaml.indent()

Source: https://yaml.dev/doc/ruamel.yaml/example

Change default indentation for mappings and sequences using yaml.indent(). The output shows the default two-position indent and the custom indent with mapping=4, sequence=6, offset=3.

```python
import sys
from ruamel.yaml import YAML

d = dict(a=dict(b=2),c=[3, 4])
yaml = YAML()
yaml.dump(d, sys.stdout)
print('#123456789')
yaml = YAML()
yaml.indent(mapping=4, sequence=6, offset=3)
yaml.dump(d, sys.stdout)
print('#123456789')

```

```yaml
a:
  b: 2
c:
- 3
- 4
#123456789
a:
    b: 2
c:
   -  3
   -  4
#123456789

```

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

### yaml.width attribute

Source: https://yaml.dev/doc/ruamel.yaml/api

The width attribute sets the maximum line width for the output. When dumping, lines longer than this width are wrapped.

```APIDOC
## [YAML] yaml.width attribute

### Description
Sets the maximum line width for the output. When dumping, lines longer than this width are wrapped.

### Method
Attribute assignment

### Endpoint
yaml.width

### Parameters
#### Attribute Parameters
- **width** (integer) - Required - The maximum line width in characters.

### Request Example
```python
ymlo.width = 1000
```

### Response
#### Success Response
- No return value. The attribute is set on the YAML instance.

#### Response Example
```python
ymlo.width = 1000
```
```

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

### Non-indented scalars with default_flow_style=False

Source: https://yaml.dev/doc/ruamel.yaml/detail

Output of PyYAML and older ruamel.yaml versions when default_flow_style=False is specified, showing non-indented scalars.

```yaml
x:
-   b: 1
- 2

```

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

### Output of dumping a self-referencing Person

Source: https://yaml.dev/doc/ruamel.yaml/dumpcls

Output of dumping a Person instance with circular references. The anchor &id001 and alias *id001 represent the self-reference.

```yaml
&id001 !Person
name: Arya
siblings:
- !Person
  name: Sansa
  siblings:
  - *id001

```

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

### Mapping with prefix_colon space

Source: https://yaml.dev/doc/ruamel.yaml/detail

Shows the effect of setting yaml.prefix_colon = ' ', which adds an extra space between the mapping key and the colon. The comment marks the extra space.

```yaml
- https://myurl/abc.tar.xz : 23445
#      extra space here --^
- https://myurl/def.tar.xz : 944

```

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

### yaml.allow_unicode attribute

Source: https://yaml.dev/doc/ruamel.yaml/api

The allow_unicode attribute controls whether Unicode characters are allowed in the output. Setting it to False forces escaping of non-ASCII characters.

```APIDOC
## [YAML] yaml.allow_unicode attribute

### Description
Sets whether to allow Unicode characters in output. When set to False, non-ASCII characters are escaped.

### Method
Attribute assignment

### Endpoint
yaml.allow_unicode

### Parameters
#### Attribute Parameters
- **allow_unicode** (boolean) - Required - If True, allow Unicode characters in output; if False, escape non-ASCII characters.

### Request Example
```python
yaml.allow_unicode = False
```

### Response
#### Success Response
- No return value. The attribute is set on the YAML instance.

#### Response Example
```python
yaml.allow_unicode = False
```
```

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

### yaml.unicode_supplementary attribute

Source: https://yaml.dev/doc/ruamel.yaml/api

The unicode_supplementary attribute controls whether supplementary Unicode characters are output as-is or escaped. It defaults to True if Python's Unicode size is larger than 2 bytes.

```APIDOC
## [YAML] yaml.unicode_supplementary attribute

### Description
Controls whether supplementary Unicode characters (those above U+FFFF) are output as-is or escaped. Defaults to True if Python's Unicode size is larger than 2 bytes. Set to False to enforce output of the form \U0001f601 (ignored if allow_unicode is False).

### Method
Attribute assignment

### Endpoint
yaml.unicode_supplementary

### Parameters
#### Attribute Parameters
- **unicode_supplementary** (boolean) - Required - If True, output supplementary Unicode characters as-is; if False, escape them as \U0001f601.

### Request Example
```python
yaml.unicode_supplementary = False
```

### Response
#### Success Response
- No return value. The attribute is set on the YAML instance.

#### Response Example
```python
yaml.unicode_supplementary = False
```
```

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

### yaml.preserve_quotes attribute

Source: https://yaml.dev/doc/ruamel.yaml/api

The preserve_quotes attribute controls whether quotes are preserved in the output. When set to True, quotes are preserved as they were in the input.

```APIDOC
## [YAML] yaml.preserve_quotes attribute

### Description
Controls whether quotes are preserved in the output. When set to True, quotes are preserved as they were in the input.

### Method
Attribute assignment

### Endpoint
yaml.preserve_quotes

### Parameters
#### Attribute Parameters
- **preserve_quotes** (boolean) - Required - If True, preserve quotes in the output; if False, do not.

### Request Example
```python
self.preserve_quotes = True
```

### Response
#### Success Response
- No return value. The attribute is set on the YAML instance.

#### Response Example
```python
self.preserve_quotes = True
```
```
Tokens:
Raw