Getting started

Overview

YaLoader is a YAML configuration system and loader which allows you to load different configurations from multiple sources and merge them into a single configuration while taking priority, correctness, hierarchy and inheritance into account. A configuration can be specified for any python object.

Using YaLoader can be divided into three steps: defining possible configurations, loading YAML files or strings holding configuration information, and constructing the final configuration for.

Installation

YaLoader is distributed over PyPI, so

pip install yaloader

is all you need.

Tip

If you want to build the docs or run the tests, you can use

pip install yaloader[docs,tests]

to install the additional needed dependencies.

Defining possible configurations

Basic Examples

Loading a class

Consider you have any class, and you want to configure and load it though a yaml file. For example a dataclass of a user:

from dataclasses import dataclass
from typing import Any

@dataclass
class User:
    age: int
    name: str

To load it from yaml, you first have to define its configuration.

import yaloader
    
@yaloader.loads(User)
class UserConfig(yaloader.YAMLBaseConfig):
    age: int
    name: str

Now a loader can be used to load a string or file holding the classes’ configuration.

loader = yaloader.ConfigLoader()
user_config = loader.construct_from_string("!User {age: 42, name: Alice}")
print(type(user_config))
print(user_config)

<class '__main__.UserConfig'>
age=42 name='Alice'

user_config now holds the configuration of the user. The user itself can be loaded using the user_config.load() method.

user = user_config.load()
print(type(user))
print(user)

<class '__main__.User'>
User(age=42, name='Alice')

The loading is not limited to single configurations. Every valid YAML file, containing !User tags is fine.

loader = yaloader.ConfigLoader()
all_user_configs = loader.construct_from_string(
    """
    - !User {age: 42, name: Alice}
    - !User {age: 20, name: Bob}
    - !User {age: 12, name: Peter}
    """
)
print(all_user_configs)

[UserConfig(age=42, name='Alice'), UserConfig(age=20, name='Bob'), UserConfig(age=12, name='Peter')]

Adding multiple configurations to the loader

The configuration loader allows you to add multiple configurations for the same tag which will be layered while construction.

Error messages

Thanks to pydantic you also get nice error messages when an incorrect configuration will be loaded.

try:
    loader.construct_from_string("!User {age: 'Not an int', name: Alice}")
except yaloader.YAMLValueError as e:
    raise e from None

An exception has occurred, use %tb to see the full traceback.

YAMLValueError: Could not validate the configuration for the tag !User
  in "<unicode string>", line 1, column 1:
    !User {age: 'Not an int', name:  ... 
    ^
  1 validation error for UserConfig
  age
    Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='Not an int', input_type=str]
      For further information visit https://errors.pydantic.dev/2.6/v/int_parsing