## read_yaml()


Read a YAML file from `path` and parse it.


Usage


``` python
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. Filesystem paths beginning with `~` are expanded using `os.path.expanduser()`.

`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: _YamlOutput | list[_YamlOutput] | Any`  
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](Yaml.md#yaml12.Yaml) wrapper to keep them hashable. Tagged nodes without a matching handler are also wrapped in [Yaml](Yaml.md#yaml12.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


``` python
    >>> read_yaml('config.yml')
```

    {'debug': True}