PyYAML

https://github.com/yaml/pyyaml
Admin
PyYAML is a full-featured YAML processing framework for Python, enabling the parsing and emitting of...
Tokens:135,965
Snippets:943
Trust Score:7.4
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example: yaml.emit with event list

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Creates a list of YAML events and emits them to a string, printing 'key: value\n'.

```python
import yaml

events = [
    yaml.StreamStartEvent(),
    yaml.DocumentStartEvent(),
    yaml.MappingStartEvent(None, None, True),
    yaml.ScalarEvent(None, None, (True, False), "key"),
    yaml.ScalarEvent(None, None, (True, False), "value"),
    yaml.MappingEndEvent(),
    yaml.DocumentEndEvent(),
    yaml.StreamEndEvent(),
]
print(yaml.emit(events))  # 'key: value\n'
```

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

### load with FullLoader

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Example of using yaml.load with a file opened in binary mode and Loader=yaml.FullLoader to parse a YAML configuration file.

```python
import yaml

with open("config.yaml", "rb") as f:
    data = yaml.load(f, Loader=yaml.FullLoader)
```

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

### Implicit resolver and constructor pair example

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Example that registers an implicit resolver and constructor to parse scalars like 'd:2024-01-02' into datetime.date objects. Uses yaml.full_load to demonstrate the parsing.

```python
import yaml, datetime, re

# implicit-resolver + constructor pair: parse "d:2024-01-02" scalars
day_re = re.compile(r'^d:(\d{4})-(\d{2})-(\d{2})$')
yaml.add_implicit_resolver("!day", day_re, ["d"])
yaml.add_constructor("!day", lambda loader, node: datetime.date(*map(int, node.value[2:].split("-"))))
print(yaml.full_load("when: d:2024-01-02\n"))
```

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

### Example: yaml.serialize with a node

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Creates a mapping node and serializes it, printing 'a: '1'\n' with a comment about implicit resolution.

```python
import yaml

node = yaml.MappingNode("tag:yaml.org,2002:map", [
    (yaml.ScalarNode("tag:yaml.org,2002:str", "a"),
     yaml.ScalarNode("tag:yaml.org,2002:int", "1")),
])
print(yaml.serialize(node))  # 'a: '1'\n'  (implicit resolution fails for quoted tag)
```

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

### load_all with SafeLoader

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Example of iterating over all documents in a stream using yaml.load_all with Loader=yaml.SafeLoader.

```python
import yaml

for doc in yaml.load_all(open("app.log"), Loader=yaml.SafeLoader):
    process(doc)
```

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

### Use fast LibYAML-based parser and emitter

Source: https://github.com/yaml/pyyaml/blob/main/README.md

When LibYAML bindings are installed, you can use the fast C-based Loader and Dumper by passing yaml.CLoader and yaml.CDumper to yaml.load and yaml.dump respectively.

```python
>>> yaml.load(stream, Loader=yaml.CLoader)
>>> yaml.dump(data, Dumper=yaml.CDumper)
```

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

### Get LibYAML version string

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Returns the LibYAML version as a string, such as '0.2.5'.

```python
def get_version_string():
    cdef const char *value
    value = yaml_get_version_string()
    return PyUnicode_FromString(value)
```

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

### load with SafeLoader and error handling

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Example of using yaml.load with a string and Loader=yaml.SafeLoader, catching yaml.YAMLError and printing the problem and mark.

```python
import yaml

try:
    obj = yaml.load("a: [1, 2, 3}", Loader=yaml.SafeLoader)
except yaml.YAMLError as exc:
    print("problem:", getattr(exc, "problem", exc))
    print("mark:", exc.problem_mark)
```

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

### Specify Loader argument to avoid warning

Source: https://github.com/yaml/pyyaml/wiki/PyYAML-yaml.load(input)-Deprecation

Shows the recommended way to call yaml.load with the Loader parameter, using yaml.FullLoader as an example.

```python
yaml.load(input, Loader=yaml.FullLoader)
```

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

### unsafe_load round-trip example

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Example of round-tripping a Python object through its unsafe representation, using yaml.add_representer and yaml.add_constructor, then yaml.unsafe_load to load the blob.

```python
import yaml

# Round-trip a Python object through its unsafe representation
class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

yaml.add_representer(Point, lambda d, o: d.represent_yaml_object(
    "!Point", o, Point))
yaml.add_constructor("!Point", lambda l, n: l.construct_yaml_object(n, Point))

blob = yaml.dump(Point(1, 2))
p = yaml.unsafe_load(blob)          # only unsafe_load may resolve !!python/...
```

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

### Exploit example using yaml.load without Loader

Source: https://github.com/yaml/pyyaml/wiki/PyYAML-yaml.load(input)-Deprecation

Shows a trivial exploit that calls os.system via a crafted YAML string, demonstrating why yaml.load is unsafe without a Loader.

```bash
python -c 'import yaml; yaml.load("!!python/object/new:os.system [echo EXPLOIT!]")'
```

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

### add_multi_constructor(tag_prefix, multi_constructor, Loader=None)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Registers a multi-constructor for tags that start with a given prefix. The multi-constructor is called with the loader, the tag suffix, and the node, and returns the constructed object.

```APIDOC
## add_multi_constructor(tag_prefix, multi_constructor, Loader=None)

### Description
Registers a multi-constructor for tags that start with `tag_prefix`. The `multi_constructor` is `f(loader, tag_suffix, node) -> object`, called when a node's tag starts with `tag_prefix`.

### Signature
```python
def add_multi_constructor(tag_prefix, multi_constructor, Loader=None):
```

### Parameters
- **tag_prefix** (string) - Required - The prefix of tags that trigger this multi-constructor.
- **multi_constructor** (callable) - Required - Function `f(loader, tag_suffix, node) -> object`.
- **Loader** (class) - Optional - Loader class to apply to; `None` applies to `Loader`, `FullLoader`, and `UnsafeLoader`.

### Source
`lib/yaml/__init__.py:315`
```

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

### Handling ConstructorError for unknown tags

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/constructor.md

Shows how to catch ConstructorError when a tag has no registered constructor. The first example uses an unknown custom tag, the second uses a python/object/apply tag that is not available in the safe FullLoader.

```python
import yaml
from yaml.constructor import ConstructorError

try:
    yaml.full_load("!unknown tag value")
except ConstructorError as exc:
    print(exc.problem)   # "could not determine a constructor for the tag '!unknown'"

try:
    yaml.full_load("!!python/object/apply:os.system ['echo pwned']")
except ConstructorError as exc:
    print(exc.problem)   # "could not determine a constructor for the tag 'tag:yaml.org,2002:python/object/apply'"
```

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

### Using compose_all with FullLoader

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Example usage of yaml.compose_all() with yaml.FullLoader to iterate over node trees for each document in a multi-document stream. The output shows the node tag and value for each document.

```python
import yaml

for node in yaml.compose_all("a: 1\n---\nb: 2\n", Loader=yaml.FullLoader):
    print(node.tag, node.value)  # tag:yaml.org,2002:map [(ScalarNode(...), ScalarNode(...))]

```

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

### Custom constructor with FullLoader for !Point2D

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/constructor.md

Shows how to register a custom constructor for a tag with yaml.FullLoader. The constructor builds a namedtuple from a mapping, and the example prints the loaded result.

```python
import yaml
from collections import namedtuple

Point = namedtuple("Point", "x y")

def point_constructor(loader, node):
    value = loader.construct_mapping(node)
    return Point(**value)

yaml.FullLoader.add_constructor("!Point2D", point_constructor)

print(yaml.load("p: !Point2D {x: 1, y: 2}", Loader=yaml.FullLoader))
# {'p': Point(x=1, y=2)}
```

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

### Basic C-extension loading and dumping

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Demonstrates using CFullLoader, CLoader, and CDumper for YAML processing.

```python
import yaml

text = "a: [1, 2, 3]\n"
print(yaml.load(text, Loader=yaml.CFullLoader))        # {'a': [1, 2, 3]}
print(yaml.load(text, Loader=yaml.CLoader))            # unsafe C loader
print(yaml.dump({"a": [1, 2, 3]}, Dumper=yaml.CDumper, default_flow_style=True))
# {a: [1, 2, 3]}
```

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

### Register a custom implicit scalar resolver

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/resolver.md

Use add_implicit_resolver to define a custom tag for scalars matching a specific regex and starting character. This example registers a hex word type.

```python
import yaml

# Custom implicit scalar type
yaml.add_implicit_resolver("!hexword", re.compile(r'^0x[0-9a-fA-F]+$'), ["0"])
yaml.add_constructor("!hexword", lambda loader, node: int(node.value, 16))
doc = yaml.full_load("value: 0x1F\n")
print(type(doc["value"]), doc["value"])   # <class 'int'> 31
```

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

### Mark.__init__

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/error-types.md

Initializes a Mark instance with position information and buffer details.

```APIDOC
## Mark.__init__

### Description
Initializes a Mark instance with position information and buffer details.

### Method
Constructor

### Signature
```python
def __init__(self, name, index, line, column, buffer, pointer):
```

### Parameters
- **name** (str) - Required - Source name: `'<unicode string>'`, `'<byte string>'`, `stream.name`, or `'<file>'`.
- **index** (int) - Required - Zero-based character index in the stream.
- **line** (int) - Required - Zero-based line number.
- **column** (int) - Required - Zero-based column number.
- **buffer** (str or None) - Required - The reader's buffer at error time; `None` for streamed inputs and for C-parser marks.
- **pointer** (int or None) - Required - Offsets into `buffer` to the error position; `None` for streamed inputs.

### Notes
- `encoding` is only for `ReaderError`.

### Source
`lib/yaml/error.py:4–12`
```

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

### Dump YAML with custom configuration

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/dumpers.md

Demonstrates how to use yaml.dump with various configuration parameters such as default_flow_style, sort_keys, and indent.

```python
import yaml

yaml.dump({"s": "text", "n": 3.5}, stream=open("out.yaml", "w"),
          default_flow_style=False, sort_keys=False, indent=4,
          allow_unicode=True, width=100)
```

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

### dump function signature and usage example

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Signature of dump, a single-object shorthand that calls dump_all with a list containing the data. The example shows dumping a dictionary with default_flow_style=False, producing a block-style YAML output.

```python
def dump(data, stream=None, Dumper=Dumper, **kwds):
    return dump_all([data], stream, Dumper=Dumper, **kwds)
```

```python
import yaml

print(yaml.dump({"list": [1, 2, 3], "flag": True}, default_flow_style=False))
# flag: true
# list:
# - 1
# - 2
# - 3
```

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

### Run complete test suite

Source: https://github.com/yaml/pyyaml/blob/main/README.md

Run the full local test suite with make test. This creates a local Python environment, runs pure Python tests, builds a local LibYAML, and runs LibYAML extension tests.

```makefile
make test
```

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

### Manually compose Reader, Scanner, and Parser

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/reader-scanner-parser.md

Demonstrates stacking the Reader, Scanner, and Parser classes to create a custom loader chain.

```python
from yaml.reader import Reader
from yaml.scanner import Scanner
from yaml.parser import Parser

class ScanParse(Reader, Scanner, Parser):
    def __init__(self, stream):
        Reader.__init__(self, stream)
        Scanner.__init__(self, stream)
        Scanner.__init__(self)
        Parser.__init__(self)
```

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

### Get LibYAML version tuple

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Returns the LibYAML version as a tuple of integers (major, minor, patch).

```python
def get_version():
    cdef int major, minor, patch
    yaml_get_version(&major, &minor, &patch)
    return (major, minor, patch)
```

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

### Perform canonical dump with options

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/serializer-emitter.md

Shows how to use the canonical option along with indentation and width settings to produce a canonical YAML output.

```python
import yaml

print(yaml.dump({"a": [1, "x"]}, canonical=True, indent=4, width=100))
# !!map {
#   ? !!str "a"
#   : !!seq [
#     !!int "1",
#     !!str "x",
#   ],
# }
```

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

### BaseRepresenter.__init__

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/representer.md

Constructor for the BaseRepresenter class.

```APIDOC
## `BaseRepresenter.__init__`

### Description
Initializes a new BaseRepresenter instance.

### Constructor
- **default_style** (str, optional) - Default style for scalars.
- **default_flow_style** (bool, optional) - Default flow style for collections.
- **sort_keys** (bool, optional) - Whether to sort mapping keys.

### Source
`lib/yaml/representer.py:18`
```

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

### Usage: Catching and inspecting errors

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/error-types.md

Example of catching yaml.YAMLError and accessing structured position data from a mark, including rendering a snippet.

```APIDOC
## Usage: Catching and inspecting errors

### Description
Demonstrates how to catch YAMLError and MarkedYAMLError, access structured position data, and render a snippet.

### Example 1: Basic error handling
```python
import yaml

try:
    data = yaml.full_load("key: [unclosed\n")
except yaml.YAMLError as exc:
    print(type(exc).__name__)     # ScannerError / ParserError / ...
    if isinstance(exc, yaml.MarkedYAMLError):
        print("context:", exc.context)
        print("problem:", exc.problem)
        mark = exc.problem_mark
        print(mark.name, mark.line, mark.column)   # e.g. <byte string> 0 5
    print(str(exc))
```

### Example 2: Accessing mark details and snippet
```python
import yaml

document = "a: 1\nb: [2, 3} c"
try:
    yaml.safe_load(document)
except yaml.MarkedYAMLError as exc:
    mark = exc.problem_mark
    print(f"{mark.name} line={mark.line + 1} column={mark.column + 1}")
    print(mark.get_snippet(indent=4, max_length=40))   # caret line if buffer present
    print(mark.__str__())
```
```

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

### CBaseLoader.__init__(stream)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Constructor for the CBaseLoader class. It initializes the loader with the given input stream.

```APIDOC
## CBaseLoader.__init__(stream)

### Description
Constructor for the CBaseLoader class. It initializes the loader with the given input stream.

### Method
Constructor

### Signature
```python
def __init__(self, stream):
```

### Parameters
- **stream** - Required - The input stream to load YAML data from.
```

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

### Building and emitting a YAML document from events

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/tokens-events-nodes.md

Builds a YAML document from hand-made events and emits it using yaml.emit. Includes error handling for yaml.emitter.EmitterError.

```python
import yaml

def build():
    return [
        yaml.StreamStartEvent(),
        yaml.DocumentStartEvent(explicit=True, version=(1, 1)),
        yaml.MappingStartEvent("root", None, (False,), flow_style=True),
        yaml.ScalarEvent(None, None, (True, False), "k"),
        yaml.ScalarEvent(None, None, (True, False), "v"),
        yaml.MappingEndEvent(),
        yaml.DocumentEndEvent(explicit=True),
        yaml.StreamEndEvent(),
    ]

try:
    print(yaml.emit(build()))
except yaml.emitter.EmitterError as exc:
    print(exc)
```

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

### LibYAML availability detection and error handling

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Shows how to conditionally select C-based classes based on LibYAML availability and handle ComposerError exceptions.

```python
import yaml

if yaml.__with_libyaml__:
    LoaderCls, DumperCls = yaml.CFullLoader, yaml.CDumper
else:
    LoaderCls, DumperCls = yaml.FullLoader, yaml.Dumper

print(yaml._yaml.get_version() if yaml.__with_libyaml__ else "libyaml unavailable")

try:
    node = LoaderCls("a: *missing").get_single_node()
except yaml.composer.ComposerError as exc:
    print(exc.problem)     # libyaml-marked error; mark.get_snippet() is None
```

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

### add_multi_constructor function signature

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Signature for add_multi_constructor. The multi_constructor is f(loader, tag_suffix, node) -> object, called when a node's tag starts with tag_prefix.

```python
def add_multi_constructor(tag_prefix, multi_constructor, Loader=None):
```

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

### CBaseDumper.__init__(stream, ...)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Constructor for the CBaseDumper class. It initializes the dumper with the given output stream and various formatting options.

```APIDOC
## CBaseDumper.__init__(stream, ...)

### Description
Constructor for the CBaseDumper class. It initializes the dumper with the given output stream and various formatting options.

### Method
Constructor

### Signature
```python
def __init__(self, stream,
        default_style=None, default_flow_style=False,
        canonical=None, indent=None, width=None,
        allow_unicode=None, line_break=None,
        encoding=None, explicit_start=None, explicit_end=None,
        version=None, tags=None, sort_keys=True):
```

### Parameters
- **stream** - Required - The output stream to dump YAML data to.
- **default_style** (optional) - The default style for scalars.
- **default_flow_style** (bool, optional) - Whether to use flow style by default. Defaults to False.
- **canonical** (optional) - Whether to use canonical output.
- **indent** (int, optional) - The indentation level.
- **width** (int, optional) - The maximum line width.
- **allow_unicode** (bool, optional) - Whether to allow unicode characters.
- **line_break** (optional) - The line break style.
- **encoding** (optional) - The output encoding.
- **explicit_start** (bool, optional) - Whether to include an explicit document start marker.
- **explicit_end** (bool, optional) - Whether to include an explicit document end marker.
- **version** (optional) - The YAML version.
- **tags** (optional) - Custom tags.
- **sort_keys** (bool, optional) - Whether to sort keys. Defaults to True.
```

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

### Emitter.prepare_version

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/serializer-emitter.md

Formats a version tuple and validates that the major version is 1.

```APIDOC
## Emitter.prepare_version

### Description
Formats a version tuple as a string and raises EmitterError if the major version is not 1.

### Method
`prepare_version`

### Signature
```python
def prepare_version(self, version):
```

### Parameters
- **version** (tuple) - Required - A tuple of (major, minor) version numbers.

### Returns
- **str** - The formatted version string in the form '%d.%d'.

### Raises
- **EmitterError** - If the major version is not 1.

### Source
`lib/yaml/emitter.py:539`
```

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

### safe_dump with unsupported type raises RepresenterError

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Example showing safe_dump raising RepresenterError when attempting to dump a pathlib.Path object, which has no representer. The error message is printed as 'unsupported: <data>'.

```python
import yaml, pathlib
from yaml.representer import RepresenterError

try:
    yaml.safe_dump({pathlib.Path("/tmp")}, stream=open("out.yaml", "w"))
except RepresenterError as exc:
    print("unsupported:", exc.args[1])
```

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

### Reader.__init__(self, stream)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/reader-scanner-parser.md

Initializes a Reader instance with a stream, which can be a string, bytes, or file-like object. Determines encoding and prepares the buffer.

```APIDOC
## Reader.__init__(self, stream)

### Description
Initializes a Reader instance with a stream, which can be a string, bytes, or file-like object. Determines encoding and prepares the buffer.

### Method
Constructor

### Signature
`def __init__(self, stream):`

### Parameters
- **stream** (str, bytes, or file-like) - Required - The input stream. If str, stored as unicode string with printable check and '\0' appended. If bytes, encoding is sniffed (UTF-16 BOM or UTF-8) and decoded lazily. If file-like, read in chunks.

### Throws
- `ReaderError` - If characters fail the printable check during construction or first read.

### Source
`lib/yaml/reader.py:59`
```

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

### Generator constructor for cyclic YAML with UnsafeLoader

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/constructor.md

Demonstrates a generator-based constructor that yields the object before its children are fully constructed, enabling cyclic references. The example registers it with yaml.UnsafeLoader and prints the number of children.

```python
import yaml

class Node:
    def __init__(self):
        self.children = []

def make_node(loader, node):
    obj = Node()
    yield obj
    for child in loader.construct_yaml_seq(node):
        obj.children.append(child)

yaml.UnsafeLoader.add_constructor("!node", make_node)

root = yaml.load("!node [ !node [], !node [] ]", Loader=yaml.UnsafeLoader)
print(len(root.children))  # 2
```

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

### Handle MarkedYAMLError when manually driving UnsafeLoader

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/loaders.md

Demonstrates error handling around manual driving. The loader is given malformed input, and get_single_data() raises yaml.MarkedYAMLError. The example prints the problem message and the problem_mark (a yaml.Mark with line/column/snippet). The loader is disposed in a finally block.

```python
import yaml

loader = yaml.UnsafeLoader("ok: [1, 2\n  bad: ]")
try:
    data = loader.get_single_data()
except yaml.MarkedYAMLError as exc:
    print(exc.problem)          # e.g. "expected ',' or ']'"
    print(exc.problem_mark)     # yaml.Mark with line/column/snippet
finally:
    loader.dispose()
```

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

### Loader.__init__(stream)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/loaders.md

Initializes a Loader instance. This is the legacy unsafe loader, kept for backwards compatibility, using Constructor (UnsafeConstructor) and Resolver.

```APIDOC
## Loader.__init__(stream)

### Description
Initializes a Loader instance. This is the legacy unsafe loader, kept for backwards compatibility. It uses Constructor (which is UnsafeConstructor) and Resolver, supporting the full tag set including arbitrary `!!python/object:*` instantiation.

### Method
Constructor

### Signature
```python
Loader(stream)
```

### Parameters
- **stream** (str, bytes, or file-like with `.read()`) - Required - The input. `str` is sniffed/checked for printable characters; `bytes` is encoding-detected (UTF-8 default, UTF-16 BOM honored); file-likes are read in 4096-byte chunks.

### Throws
- `ReaderError` - For unprintable characters / undecodable bytes.
- `ScannerError` - While pulling tokens.
- `ParserError` - While pulling events.
- `ComposerError` - While pulling nodes.
- `ConstructorError` - While pulling data.

### Example
```python
from yaml.loader import Loader
loader = Loader(stream)
```
```

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

### CUnsafeLoader.__init__(stream)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Constructor for the CUnsafeLoader class. It initializes the loader with the given input stream, using the unsafe constructor and resolver.

```APIDOC
## CUnsafeLoader.__init__(stream)

### Description
Constructor for the CUnsafeLoader class. It initializes the loader with the given input stream, using the unsafe constructor and resolver.

### Method
Constructor

### Signature
```python
def __init__(self, stream):
```

### Parameters
- **stream** - Required - The input stream to load YAML data from.
```

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

### CDumper.__init__(stream, ...)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Constructor for the CDumper class. It initializes the dumper with the given output stream and various formatting options, using the standard representer.

```APIDOC
## CDumper.__init__(stream, ...)

### Description
Constructor for the CDumper class. It initializes the dumper with the given output stream and various formatting options, using the standard representer.

### Method
Constructor

### Signature
```python
def __init__(self, stream,
        default_style=None, default_flow_style=False,
        canonical=None, indent=None, width=None,
        allow_unicode=None, line_break=None,
        encoding=None, explicit_start=None, explicit_end=None,
        version=None, tags=None, sort_keys=True):
```

### Parameters
- **stream** - Required - The output stream to dump YAML data to.
- **default_style** (optional) - The default style for scalars.
- **default_flow_style** (bool, optional) - Whether to use flow style by default. Defaults to False.
- **canonical** (optional) - Whether to use canonical output.
- **indent** (int, optional) - The indentation level.
- **width** (int, optional) - The maximum line width.
- **allow_unicode** (bool, optional) - Whether to allow unicode characters.
- **line_break** (optional) - The line break style.
- **encoding** (optional) - The output encoding.
- **explicit_start** (bool, optional) - Whether to include an explicit document start marker.
- **explicit_end** (bool, optional) - Whether to include an explicit document end marker.
- **version** (optional) - The YAML version.
- **tags** (optional) - Custom tags.
- **sort_keys** (bool, optional) - Whether to sort keys. Defaults to True.
```

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

### FullConstructor.make_python_instance

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/constructor.md

Instantiates a Python class from a tag, with optional newobj flag and unsafe mode.

```APIDOC
## FullConstructor.make_python_instance

### Description
Instantiates a Python class from a tag, with optional newobj flag and unsafe mode. Rejects non-class targets unless unsafe.

### Method
`make_python_instance(self, suffix, node, args=None, kwds=None, newobj=False, unsafe=False)`

### Parameters
- **suffix** (str) - Required - The suffix of the tag.
- **node** - Required - The YAML node.
- **args** (list) - Optional - Positional arguments for instantiation.
- **kwds** (dict) - Optional - Keyword arguments for instantiation.
- **newobj** (bool) - Optional - If True, uses `cls.__new__(cls, *args, **kwds)`.
- **unsafe** (bool) - Optional - If True, allows non-class targets.

### Returns
- **instance** - The instantiated object.
```

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

### CFullLoader.__init__(stream)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Constructor for the CFullLoader class. It initializes the loader with the given input stream, using the full constructor and resolver.

```APIDOC
## CFullLoader.__init__(stream)

### Description
Constructor for the CFullLoader class. It initializes the loader with the given input stream, using the full constructor and resolver.

### Method
Constructor

### Signature
```python
def __init__(self, stream):
```

### Parameters
- **stream** - Required - The input stream to load YAML data from.
```

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

### Manually compose Serializer and Emitter

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/serializer-emitter.md

Demonstrates how to manually compose the Emitter and Serializer classes, which is equivalent to using yaml.Dumper without the representer and resolver.

```python
import yaml
from yaml.emitter import Emitter
from yaml.serializer import Serializer

class Pipe:
    def __init__(self, stream):
        self.stream = stream
    def write(self, data):
        self.stream.write(data)
    def flush(self):
        self.stream.flush()

buf = []
es = Emitter(Pipe(buf))
ser = Serializer(explicit_start=True)
es.open() if hasattr(es, "open") else None
# Serializer-style usage is normally via Dumper (which bundles Emitter+Serializer).
```

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

### BaseLoader.__init__(stream)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/loaders.md

Initializes a BaseLoader instance with the given stream. This is the lowest-level loader that only honors explicit tags with user-registered constructors.

```APIDOC
## BaseLoader.__init__(stream)

### Description
Initializes a BaseLoader instance. This loader uses BaseConstructor and BaseResolver, meaning no implicit resolvers and no tag constructors are registered by default. Only explicit tags with user-registered constructors are honored.

### Method
Constructor

### Signature
```python
BaseLoader(stream)
```

### Parameters
- **stream** (str, bytes, or file-like with `.read()`) - Required - The input. `str` is sniffed/checked for printable characters; `bytes` is encoding-detected (UTF-8 default, UTF-16 BOM honored); file-likes are read in 4096-byte chunks.

### Throws
- `ReaderError` - For unprintable characters / undecodable bytes.
- `ScannerError` - While pulling tokens.
- `ParserError` - While pulling events.
- `ComposerError` - While pulling nodes.
- `ConstructorError` - While pulling data.

### Example
```python
from yaml.loader import BaseLoader
loader = BaseLoader(stream)
```
```

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

### FullLoader.__init__(stream)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/loaders.md

Initializes a FullLoader instance. This is the recommended default loader that resolves all standard and python/* scalar types but blocks python/module and python/object* imports.

```APIDOC
## FullLoader.__init__(stream)

### Description
Initializes a FullLoader instance. This loader uses FullConstructor and Resolver, resolving all standard YAML tags plus `python/*` scalar types, but blocks `python/module` and `python/object*` imports.

### Method
Constructor

### Signature
```python
FullLoader(stream)
```

### Parameters
- **stream** (str, bytes, or file-like with `.read()`) - Required - The input. `str` is sniffed/checked for printable characters; `bytes` is encoding-detected (UTF-8 default, UTF-16 BOM honored); file-likes are read in 4096-byte chunks.

### Throws
- `ReaderError` - For unprintable characters / undecodable bytes.
- `ScannerError` - While pulling tokens.
- `ParserError` - While pulling events.
- `ComposerError` - While pulling nodes.
- `ConstructorError` - While pulling data.

### Example
```python
from yaml.loader import FullLoader
loader = FullLoader(stream)
```
```

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

### BaseLoader constructor

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/loaders.md

Shows the __init__ method of BaseLoader, which initializes all pipeline stages: Reader, Scanner, Parser, Composer, BaseConstructor, and BaseResolver. The other loader classes are identical except they use different constructor and resolver mixins.

```python
class BaseLoader(Reader, Scanner, Parser, Composer, BaseConstructor, BaseResolver):

    def __init__(self, stream):
        Reader.__init__(self, stream)
        Scanner.__init__(self)
        Parser.__init__(self)
        Composer.__init__(self)
        BaseConstructor.__init__(self)
        BaseResolver.__init__(self)
```

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

### PyYAML package initialization sequence

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/overview.md

The code executed upon importing the yaml package, which sets up the version, LibYAML availability, and exports core components.

```python
from .error import *
from .tokens import *
from .events import *
from .nodes import *

from .loader import *
from .dumper import *

__version__ = '7.0.0.dev0'
try:
    from .cyaml import *
    __with_libyaml__ = True
except ImportError:
    __with_libyaml__ = False
```

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

### UnsafeLoader.__init__(stream)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/loaders.md

Initializes an UnsafeLoader instance. This loader uses Constructor (UnsafeConstructor) and Resolver, supporting the full tag set including arbitrary python/object instantiation. Never use on untrusted input.

```APIDOC
## UnsafeLoader.__init__(stream)

### Description
Initializes an UnsafeLoader instance. This loader uses Constructor (which is UnsafeConstructor) and Resolver, supporting the full tag set including arbitrary `!!python/object:*` instantiation. Never use on untrusted input.

### Method
Constructor

### Signature
```python
UnsafeLoader(stream)
```

### Parameters
- **stream** (str, bytes, or file-like with `.read()`) - Required - The input. `str` is sniffed/checked for printable characters; `bytes` is encoding-detected (UTF-8 default, UTF-16 BOM honored); file-likes are read in 4096-byte chunks.

### Throws
- `ReaderError` - For unprintable characters / undecodable bytes.
- `ScannerError` - While pulling tokens.
- `ParserError` - While pulling events.
- `ComposerError` - While pulling nodes.
- `ConstructorError` - While pulling data.

### Example
```python
from yaml.loader import UnsafeLoader
loader = UnsafeLoader(stream)
```
```

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

### Emitter constructor

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/serializer-emitter.md

Initializes an Emitter instance with the given stream and optional formatting parameters.

```APIDOC
## Emitter constructor

### Description
Creates an Emitter that writes YAML output to the provided stream. Optional parameters control canonical output, indentation, line width, Unicode handling, and line breaks.

### Method
Constructor

### Signature
```python
def __init__(self, stream, canonical=None, indent=None, width=None,
        allow_unicode=None, line_break=None):
```

### Parameters
- **stream** (file-like) - Required - The output stream to write YAML to.
- **canonical** (bool) - Optional - If true, forces canonical style.
- **indent** (int) - Optional - Indentation width; must be between 2 and 9 inclusive to take effect.
- **width** (int) - Optional - Preferred line width; must be greater than twice the indent to take effect.
- **allow_unicode** (bool) - Optional - If true, allows Unicode characters in output.
- **line_break** (str) - Optional - Line break style; one of '\r', '\n', or '\r\n'.

### Defaults
- best_indent = 2 (overridden if indent and 1 < indent < 10)
- best_width = 80 (overridden if width and width > best_indent*2)
- best_line_break = '\n' (overridden if line_break in ['\r', '\n', '\r\n'])

### Source
`lib/yaml/emitter.py:38`
```

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

### Define and use a YAMLObject subclass

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/yaml-object.md

Demonstrates defining a class that inherits from yaml.YAMLObject with a custom tag, then dumping and loading it using full_load.

```python
import yaml

class Person(yaml.YAMLObject):
    yaml_tag = '!Person'

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

    def __repr__(self):
        return f"Person({self.name!r}, {self.age!r})"

blob = yaml.dump(Person("Ada", 37))
print(blob)
# !Person
# age: 37
# name: Ada

p = yaml.full_load(blob)   # Loader, FullLoader, UnsafeLoader registered
print(p)                   # Person('Ada', 37)
```

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

### Compose YAML nodes with FullLoader

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/composer.md

Demonstrates using FullLoader to iterate through YAML nodes and inspect their tags and resolved alias values.

```python
import yaml

composer = yaml.Composer()
# -- Composer alone has no Reader; drive a full loader instead: --

loader = yaml.FullLoader("base: &base {x: 1}\ncopy: *base\n")
try:
    while loader.check_node():
        node = loader.get_node()
        print(node.tag)                        # tag:yaml.org,2002:map
        print(node.value[1][1].value)          # alias resolved -> {'x': 1}
finally:
    loader.dispose()
```

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

### CSafeDumper.__init__(stream, ...)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Constructor for the CSafeDumper class. It initializes the dumper with the given output stream and various formatting options, using the safe representer.

```APIDOC
## CSafeDumper.__init__(stream, ...)

### Description
Constructor for the CSafeDumper class. It initializes the dumper with the given output stream and various formatting options, using the safe representer.

### Method
Constructor

### Signature
```python
def __init__(self, stream,
        default_style=None, default_flow_style=False,
        canonical=None, indent=None, width=None,
        allow_unicode=None, line_break=None,
        encoding=None, explicit_start=None, explicit_end=None,
        version=None, tags=None, sort_keys=True):
```

### Parameters
- **stream** - Required - The output stream to dump YAML data to.
- **default_style** (optional) - The default style for scalars.
- **default_flow_style** (bool, optional) - Whether to use flow style by default. Defaults to False.
- **canonical** (optional) - Whether to use canonical output.
- **indent** (int, optional) - The indentation level.
- **width** (int, optional) - The maximum line width.
- **allow_unicode** (bool, optional) - Whether to allow unicode characters.
- **line_break** (optional) - The line break style.
- **encoding** (optional) - The output encoding.
- **explicit_start** (bool, optional) - Whether to include an explicit document start marker.
- **explicit_end** (bool, optional) - Whether to include an explicit document end marker.
- **version** (optional) - The YAML version.
- **tags** (optional) - Custom tags.
- **sort_keys** (bool, optional) - Whether to sort keys. Defaults to True.
```

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

### Mark.__str__ implementation

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/error-types.md

Provides a human-readable string representation of the Mark, including the file name, line, column, and a visual snippet.

```python
def __str__(self):
    snippet = self.get_snippet()
    where = "  in \"%s\", line %d, column %d"   \
            % (self.name, self.line+1, self.column+1)
    if snippet is not None:
        where += ":\n"+snippet
    return where
```

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

### FullConstructor.construct_python_object_new

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/constructor.md

Constructs a Python object using newobj=True, delegating to construct_python_object_apply.

```APIDOC
## FullConstructor.construct_python_object_new

### Description
Constructs a Python object using `newobj=True`, delegating to `construct_python_object_apply`.

### Method
`construct_python_object_new(self, suffix, node)`

### Parameters
- **suffix** (str) - Required - The suffix of the tag.
- **node** - Required - The YAML node.

### Returns
- **instance** - The constructed Python object.
```

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

### SafeLoader.__init__(stream)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/loaders.md

Initializes a SafeLoader instance. This loader uses SafeConstructor and Resolver, supporting only basic YAML tags and safe for untrusted input.

```APIDOC
## SafeLoader.__init__(stream)

### Description
Initializes a SafeLoader instance. This loader uses SafeConstructor and Resolver, supporting only basic YAML tags and safe for untrusted input.

### Method
Constructor

### Signature
```python
SafeLoader(stream)
```

### Parameters
- **stream** (str, bytes, or file-like with `.read()`) - Required - The input. `str` is sniffed/checked for printable characters; `bytes` is encoding-detected (UTF-8 default, UTF-16 BOM honored); file-likes are read in 4096-byte chunks.

### Throws
- `ReaderError` - For unprintable characters / undecodable bytes.
- `ScannerError` - While pulling tokens.
- `ParserError` - While pulling events.
- `ComposerError` - While pulling nodes.
- `ConstructorError` - While pulling data.

### Example
```python
from yaml.loader import SafeLoader
loader = SafeLoader(stream)
```
```

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

### FullConstructor.get_state_keys_blacklist

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/constructor.md

Returns a list of regular expression patterns used to blacklist state keys during object state restoration.

```APIDOC
## FullConstructor.get_state_keys_blacklist

### Description
Returns a list of regular expression patterns used to blacklist state keys during object state restoration.

### Method
`get_state_keys_blacklist(self)`

### Returns
- **list** - List of regex patterns: `['^extend$', '^__.*__$']`
```

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

### CParser.__init__

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Constructor for CParser. Accepts a string, bytes, or a readable stream. Raises TypeError for other input types.

```APIDOC
## CParser.__init__

### Description
Initializes a new CParser instance with the given input stream. The input can be a string, bytes, or a readable stream object.

### Method
Constructor

### Signature
`def __init__(self, stream):`

### Parameters
- **stream** (str, bytes, or readable stream) - Required - The input to parse. Strings are encoded as UTF-8 internally.

### Exceptions
- **TypeError** - Raised if the input is not a string, bytes, or a readable stream. Message: "a string or stream input is required".
```

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

### Run only one test mode

Source: https://github.com/yaml/pyyaml/blob/main/README.md

Run only the pure Python tests or only the LibYAML extension tests.

```makefile
make test-python
make test-libyaml
```

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

### get_version_string()

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/cyaml.md

Module-level function that returns the LibYAML version string.

```APIDOC
## get_version_string()

### Description
Returns the LibYAML version string (e.g. `'0.2.5'`).

### Method
Function call

### Endpoint
`yaml._yaml.get_version_string()`

### Parameters
None

### Response
#### Success Response
- **Return** (str) - LibYAML version string

#### Response Example
```python
'0.2.5'
```
```

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

### Register a custom representer

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/dumpers.md

Shows how to register a custom representer on a subclassed dumper to avoid global state changes.

```python
import yaml
from yaml.representer import RepresenterError

# register a custom representer on a subclassed dumper to avoid globals
class MyDumper(yaml.Dumper):
    pass

def represent_pair(dumper, data):
    return dumper.represent_mapping("!pair", {"a": data[0], "b": data[1]})

MyDumper.add_representer(tuple, represent_pair)

try:
    print(yaml.dump((1, 2), Dumper=MyDumper))
    # !pair
    # a: 1
    # b: 2
except RepresenterError as exc:
    print("unrepresentable:", exc.args[1])
```

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

### FullConstructor.get_state_keys_blacklist_regexp

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/constructor.md

Returns a lazily-compiled combined regular expression from the blacklist patterns, cached on the instance.

```APIDOC
## FullConstructor.get_state_keys_blacklist_regexp

### Description
Returns a lazily-compiled combined regular expression from the blacklist patterns, cached on the instance.

### Method
`get_state_keys_blacklist_regexp(self)`

### Returns
- **compiled regexp** - Combined regexp object
```

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

### warnings(settings=None)

Source: https://github.com/yaml/pyyaml/blob/main/_autodocs/api-reference/api-functions.md

Deprecated no-op function. With no/None argument returns an empty dict; passing any other value returns None.

```APIDOC
## warnings(settings=None)

### Description
Deprecated no-op retained for API compatibility. With no/None argument returns an empty dict; passing any other value returns None (no filtering occurs).

### Method
Function call

### Signature
warnings(settings=None)

### Parameters
- **settings** (any) - Optional - If None or omitted, returns an empty dict. If any other value, returns None.

### Return Value
- If settings is None: dict (empty)
- If settings is any other value: None

### Example
```python
warnings()  # returns {}
warnings(None)  # returns {}
warnings('some_value')  # returns None
```
```
Tokens:
Raw