read_yaml()

Read a YAML file from path and parse it.

Usage

read_yaml(path: str | PathLike[str] | _Readable, multi: Literal[False] = False, handlers: None = None) -> _YamlOutput
 
read_yaml(path: str | PathLike[str] | _Readable, multi: Literal[True], handlers: None = None) -> list[_YamlOutput]
 
read_yaml(path: str | PathLike[str] | _Readable, multi: bool = False, handlers: Mapping[str, Callable[[Any], Any]] | None = None) -> Any

Parameters

path: str | os.PathLike | object with .read

Filesystem path or readable object whose .read() returns str/bytes.

multi: bool = False

Return a list of documents when true; otherwise a single document or None for empty input.

handlers: dict[str, Callable] | None = None

Optional tag handlers for values and keys; matching handlers receive the parsed value.

Returns

object

Parsed value(s): YAML mappings become dict, sequences become list, and scalars resolve using the YAML 1.2 core schema to bool/int/float/None/str. Unhashable mapping keys (for example list/dict) are wrapped in the lightweight Yaml wrapper to keep them hashable. Tagged nodes without a matching handler are also wrapped in Yaml so the tag can be preserved.

Raises

IOError

When the file cannot be read.

ValueError

On YAML parse errors or invalid tag strings.

TypeError

When handlers are not callables or inputs are the wrong type.

Exception

Propagated directly from user-provided handlers.

Examples

>>> read_yaml('config.yml')
{'debug': True}