BaseConfig#

class config_base.BaseConfig#

Bases: BaseModel

Base class for storing model parameters.

Contains functionality for reading / writing parameters to config files in the YAML format.

See also

[pydantic docs](https://pydantic-docs.helpmanual.io/):: for more information about using pydantic’s model classes.

pydantic.BaseModel: which handles converting data to Python types. pydantic.validator: which allows additional custom validation methods.

Examples

Example of creating a config class and initialising it with values, values will be validated and converted to correct type on initialisation.

>>> from pathlib import Path
>>> from caf.toolkit import BaseConfig
>>> class ExampleParameters(BaseConfig):
...    import_folder: Path
...    name: str
...    some_option: bool = True
>>> parameters = ExampleParameters(
...    import_folder="Test Folder",
...    name="Test",
...    some_option=False,
... )

Example of instance of class after initialisation, the path differs depending on operating system.

>>> parameters 
ExampleParameters(
    import_folder=WindowsPath('Test Folder'),
    name='Test',
    some_option=False,
)

Config class can be converted to YAML or saved with save_yaml.

>>> print(parameters.to_yaml())
import_folder: Test Folder
name: Test
some_option: no

Config class data can be loaded from a YAML config file using load_yaml.

>>> yaml_text = '''
... import_folder: Test Folder
... name: Test
... some_option: no
... '''
>>> loaded_parameters = ExampleParameters.from_yaml(yaml_text)
>>> loaded_parameters == parameters
True

Methods Summary

`from_yaml`(text)	Parse class attributes from YAML text.
`load_yaml`(path)	Read YAML file and load the data using from_yaml.
`save_yaml`(path[, datetime_comment, ...])	Write data from self to a YAML file.
`to_yaml`()	Convert attributes from self to YAML string.
`write_example`(path_, /[, comment_])	Write examples to a config file.

Methods Documentation

classmethod from_yaml(text)#

Parse class attributes from YAML text.

Parameters:: text (str) – YAML formatted string, with parameters for the class attributes.
Returns:: Instance of class with attributes filled in from the YAML data.
Return type:: Instance of self

classmethod load_yaml(path)#

Read YAML file and load the data using from_yaml.

Parameters:: path (Path) – Path to YAML file containing parameters.
Returns:: Instance of class with attributes filled in from the YAML data.
Return type:: Instance of self

save_yaml(path, datetime_comment=True, other_comment=None, format_comment=False)#

Write data from self to a YAML file.

Parameters:

path (Path) – Path to YAML file to output.
datetime_comment (bool, default True) – Whether to include a comment at the top of the config file with the current date and time.
other_comment (str, optional) – Additional comments to add to the top of the config file, “#” will be added to the start of each new line if it isn’t already there.
format_comment (bool, default False) – Whether to remove newlines from other_comment and format lines to a specific character length.

Return type:

None

to_yaml()#

Convert attributes from self to YAML string.

Returns:: YAML formatted string with the data from the class attributes.
Return type:: str

classmethod write_example(path_, /, comment_=None, **examples)#

Write examples to a config file.

Parameters:

path (Path) – Path to the YAML file to write.
comment (str, optional) – Comment to add to the top of the example config file, will be formatted to add “#” symbols and split across multiple lines.
examples (str) – Fields of the config to write, any missing fields are filled in with their default value (if they have one) or ‘REQUIRED’ / ‘OPTIONAL’.
path_ (Path) –
comment_ (str | None) –

Return type:

None