YamlConfig¶

class passengersim.config.base.YamlConfig[source]¶

Bases: PrettyModel

A Pydantic BaseModel with methods for loading from and writing to YAML files.

Methods:

`from_yaml`(filenames, *[, cache_file, ...])	Read from YAML.
`from_raw_yaml`(content)	Read from raw YAML content.
`to_yaml`([stream, include, exclude, ...])	Write a config to YAML format.
`to_yaml_parts`(directory, *[, include, ...])	Write to a set of YAML files, one for each top level key.

Attributes:

`tags`	Tags that can be used in format strings in the config.

classmethod from_yaml(filenames: PathLike | list[PathLike], *, cache_file: PathLike | None = None, on_validation_error: 'raise' | 'warn' = 'raise') → TConfig[source]¶

Read from YAML.

Parameters:

filenames : path-like or list[path-like]¶: If multiple filenames are provided, they are loaded in order and values with matching keys defined in later files will overwrite the ones found in earlier files.
cache_file : path-like, optional¶: If provided, the validated config will be cached to this file in binary format using pickle. If the cache file exists and is newer than the YAML files, the cached config will be loaded instead of reloading and revalidating the YAML files, which can be considerably faster.
on_validation_error : {'raise', 'warn'}, default 'raise'¶: Whether to raise an exception or log a warning when a validation error is encountered. If ‘warn’, the error is logged and the unvalidated raw loaded yaml content (not a Config object) is returned. This can be useful for debugging YAML files that are failing validation, but it is recommended to leave this as ‘raise’ in production to avoid accidentally using an unvalidated config.

Returns:

Config

classmethod from_raw_yaml(content: str | bytes) → Self[source]¶

Read from raw YAML content.

Parameters:

content : str or bytes¶: The YAML content to parse. Note this is not a filename – if you are ostensibly working with a file, this is the contents of the file instead of its name. Alternatively, this can just be notional YAML content as a string or bytes, without there being a “file” at all.

Returns:

YamlConfig

tags : dict[str, Any]¶: Tags that can be used in format strings in the config.

to_yaml(stream: os.PathLike | io.FileIO | None = None, *, include: IncEx = None, exclude: IncEx = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, warnings: bool = True, human_readable: bool = True) → None | bytes[source]¶

Write a config to YAML format.

Parameters:

stream : Path-like or File-like, optional¶: Write the results here. If given as a path, a new file is written at this location, or give a File-like object open for writing.
include : list[int | str]¶: A list of fields to include in the output.
exclude : list[int | str]¶: A list of fields to exclude from the output.
exclude_unset : bool, default False¶: Whether to exclude from the output fields that were unset when the Config was created. There are a variety of cleaning and updating functions that may have been run on this Config that would set things that were originally not set (e.g. path building), so you probably want to leave this as False unless you know what you are doing.
exclude_defaults : bool, default False¶: Whether to exclude fields that are set to their default value from the output.
exclude_none : bool, default False¶: Whether to exclude fields that have a value of None from the output.
warnings : bool, default True¶: Whether to log warnings when invalid fields are encountered.
human_readable : bool, default True¶: Whether to write the YAML files in a human-readable format. This will reformat inputs back to normal human-readable values (e.g. leg departure times as ‘HH:MN’ in local time, not an integer giving unix time.

Returns:

bytes or None – When no stream is given, the YAML content is returned as bytes, otherwise this method returns nothing.

to_yaml_parts(directory: pathlib.Path | str, *, include: IncEx = None, exclude: IncEx = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, warnings: bool = True, general_config: tuple[str] = ('simulation_controls', 'tags'), human_readable: bool = True, compress_large_files: bool = True, use_csv: bool = True) → None[source]¶

Write to a set of YAML files, one for each top level key.

Parameters:

directory : pathlib.Path or str¶: The directory to write the YAML files to. If it does not exist, it will be created.
include : list[int | str], optional¶: A list of fields to include in the output.
exclude : list[int | str], optional¶: A list of fields to exclude from the output.
exclude_unset : bool, default False¶: Whether to exclude from the output fields that were unset when the Config was created. There are a variety of cleaning and updating functions that may have been run on this Config that would set things that were originally not set (e.g. path building), so you probably want to leave this as False unless you know what you are doing.
exclude_defaults : bool, default False¶: Whether to exclude fields that are set to their default value from the output.
exclude_none : bool, default False¶: Whether to exclude fields that have a value of None from the output.
warnings : bool, default True¶: Whether to log warnings when invalid fields are encountered.
general_config : tuple[str], default ("simulation_controls", "tags")¶: The top-level keys to write to the general config file (general.yaml) instead of their own files.
human_readable : bool, default True¶: Whether to write the output files in a human-readable format. This will reformat inputs back to normal human-readable values (e.g. leg departure times as ‘HH:MN’ in local time, not an integer giving unix time.
compress_large_files : bool, default True¶: Whether to compress files larger than 1MB with lz4. This can be helpful to reduce file sizes when saving large networks.
use_csv : bool, default True¶: Whether to write tabular-compatible data (e.g. demands, fares, legs) as CSV files instead of YAML.