YAML API Reference¶

def load(text: str) -> Any:
    """Parse a YAML string and return a Python object.

    Only produces safe types: dict, list, str, int, float, bool, None.
    Equivalent to PyYAML's ``yaml.safe_load()``.

    Args:
        text: YAML document string.

    Returns:
        Parsed Python object.

    Raises:
        YAMLError: If the YAML is malformed.
    """
    if not text or not text.strip():
        return None
    raw_lines = text.splitlines()
    lines = _scan(text)
    if not lines:
        return None
    parser = _Parser(lines, raw_lines)
    docs = parser.parse_stream()
    return docs[0] if docs else None

def load_all(text: str) -> Iterator[Any]:
    """Parse a multi-document YAML string.

    Yields one Python object per YAML document (separated by ``---``).

    Args:
        text: Multi-document YAML string.

    Yields:
        Parsed Python objects, one per document.
    """
    if not text or not text.strip():
        yield None
        return
    raw_lines = text.splitlines()
    lines = _scan(text)
    if not lines:
        yield None
        return
    parser = _Parser(lines, raw_lines)
    docs = parser.parse_stream()
    yield from docs

def dump(
    data: Any,
    stream: IO[str] | None = None,
    *,
    default_flow_style: bool | None = None,
    indent: int = 2,
    sort_keys: bool = True,
    allow_unicode: bool = True,
) -> str | None:
    """Serialize a Python object to a YAML string.

    Args:
        data: Python object to serialize.
        stream: If provided, write to this stream and return None.
        default_flow_style: True for flow (inline) style, False for block,
            None for auto (empty collections use flow).
        indent: Number of spaces per indentation level.
        sort_keys: Sort mapping keys alphabetically.
        allow_unicode: Allow unicode characters in output.

    Returns:
        YAML string if *stream* is None, otherwise None.
    """
    dumper = _Dumper(
        indent=indent,
        default_flow_style=default_flow_style,
        sort_keys=sort_keys,
        allow_unicode=allow_unicode,
    )
    result = dumper.dump(data)
    if stream is not None:
        stream.write(result)
        return None
    return result

def dump_all(
    documents: list[Any] | tuple[Any, ...],
    stream: IO[str] | None = None,
    *,
    default_flow_style: bool | None = None,
    indent: int = 2,
    sort_keys: bool = True,
    allow_unicode: bool = True,
) -> str | None:
    """Serialize multiple Python objects as a multi-document YAML string.

    Args:
        documents: Iterable of Python objects to serialize.
        stream: If provided, write to this stream and return None.
        default_flow_style: True for flow style, False for block, None for auto.
        indent: Number of spaces per indentation level.
        sort_keys: Sort mapping keys alphabetically.
        allow_unicode: Allow unicode characters in output.

    Returns:
        YAML string if *stream* is None, otherwise None.
    """
    dumper = _Dumper(
        indent=indent,
        default_flow_style=default_flow_style,
        sort_keys=sort_keys,
        allow_unicode=allow_unicode,
    )
    parts: list[str] = []
    for i, doc in enumerate(documents):
        if i > 0:
            parts.append("---\n")
        parts.append(dumper.dump(doc))
    result = "".join(parts)
    if stream is not None:
        stream.write(result)
        return None
    return result