YAML

yaml ¶

Utility functions for handling YAML and TOML configuration files.

read_yaml(filename: str | Path, encoding: str = 'utf-8') -> dict[str, Any]

Read from file.

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	File name.	required
`encoding`	`str`	File encoding.	`'utf-8'`

Returns:

Type	Description
`dict[str, Any]`	A dictionary of data.

read_data_file(filename: str | Path, encoding: str = 'utf-8') -> dict[str, Any]

Read a YAML or TOML mapping from disk.

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	File name.	required
`encoding`	`str`	File encoding for text-based formats.	`'utf-8'`

Returns:

Type	Description
`dict[str, Any]`	A dictionary of data.

Raises:

Type	Description
`ValueError`	If the suffix is unsupported or the top-level object is not a mapping.

write_yaml(filename: str | Path, data: dict[str, Any], encoding: str = 'utf-8', round_trip: bool = False, **kwargs: Any) -> None

Write to file.

Parameters:

Name	Type	Description	Default
`filename`	`str \| Path`	File name.	required
`data`	`dict[str, Any]`	A dictionary of data.	required
`encoding`	`str`	Encoding of the file.	`'utf-8'`
`round_trip`	`bool`	If True, use ruyaml to preserve comments/order.	`False`
`**kwargs`	`Any`	Extra arguments passed to yaml.safe_dump (or ruyaml.YAML.dump).	`{}`