Config Elements

The config specification in Yaml Config is essentially a tree of ConfigElement instances, where ConfigElement is the base class of all element types in the tree.

This page describes all the defined ConfigElement types. For information on creating custom ConfigElements, see below.

Numeric Elements

Numeric types come in a variety where choices are specified as a list, and another where choices are given as an inclusive range.

class yaml_config.IntElem(name=None, **kwargs)

An integer configuration element.

__init__(name=None, **kwargs)

Most ConfigElement child classes take all of these arguments, and just add a few of their own.

Parameters

  • name (str) – The name of this configuration element. Required if this is a key in a KeyedElem. Will receive a descriptive default otherwise.

  • default – The default value if no value is retrieved from a config file.

  • required (bool) – When validating a config file, a RequiredError will be thrown if there is no value for this element. NULL does not count as a value.

  • hidden – Hidden elements are ignored when writing out the config (or example configs). They can still be set by the user.

  • choices (list) – A optional sequence of values that this type will accept.

  • post_validator (post_validator) – A optional post validation function for this element. See the Post-Validation section in the online documentation for more info.

  • _sub_elem (Union(ConfigElement,None)) – The ConfigElement contained within this one, such as for ListElem definitions. Meant to be set by subclasses if needed, never the user. Names are optional for all sub-elements, and will be given sane defaults.

Raises

ValueError – May raise a value error for invalid configuration options.

class yaml_config.IntRangeElem(name=None, vmin=None, vmax=None, **kwargs)

An int element with range validation.

__init__(name=None, vmin=None, vmax=None, **kwargs)
Parameters

  • vmin – The minimum value for this element, inclusive.

  • vmax – The max value, inclusive.

class yaml_config.FloatElem(name=None, **kwargs)

A float configuration element.

class yaml_config.FloatRangeElem(name=None, vmin=None, vmax=None, **kwargs)

A float with range validation.

class yaml_config.BoolElem(name=None, **kwargs)

A boolean element. YAML automatically translates many strings into boolean values.

String Elements

Both exact and regex validated versions are included.

class yaml_config.StrElem(name=None, **kwargs)

A basic string element.

class yaml_config.RegexElem(name=None, regex='', **kwargs)

Just like a string item, but validates against a regex.

__init__(name=None, regex='', **kwargs)
Parameters

regex – A regular expression string to match against.

Derived Elements

This allow you to build config information from other config values.

class yaml_config.DerivedElem(name, resolver=None, **kwargs)

The value is derived from the values of other elements. This is only valid when used as an element in a KeyedElem (or YamlConfigLoader), trying to use it elsewhere will raise an exception (It simply doesn’t make sense anywhere else).

Resolution of this element is deferred until after all non-derived elements are resolved. All derived elements are then resolved in the order they were listed. This resolution is performed by a function, which can be given either:

  • As the ‘resolver’ argument to __init__

  • The ‘resolve’ method of this class

  • The ‘resolve_<name>’ method of the parent KeyedElem or YamlConfigLoader class.

This function is expected to take one positional argument, which is the dictionary of validated values from the KeyedElem so far.

_resolve(siblings)

A resolver function gets a dictionary of its returned sibling’s values, and should return the derived value. A resolver passed as an argument to DerivedElem’s __init__ should have the same signature ( without the self).

Parameters

siblings ({}) – The dictionary of validated values from the keyed element that this is a part of.

Returns

The derived element value

Container Types

These allow you to build nested, complex configuration specifications.

class yaml_config.KeyedElem(name=None, elements=None, key_case='mixed', **kwargs)

A dictionary configuration item with predefined keys that may have non-uniform types. The valid keys are are given as ConfigItem objects, with their names being used as the key name.

__init__(name=None, elements=None, key_case='mixed', **kwargs)
Parameters

  • key_case – Must be one of the <cls>.KC_* values. Determines whether keys are automatically converted to lower or upper case, or left alone.

  • elements – This list of config elements is also forms the list of accepted keys, with the element.name being the key.

class yaml_config.CategoryElem(name=None, sub_elem=None, defaults=None, allow_empty_keys=False, key_case='mixed', **kwargs)

A dictionary config item where all the keys must be of the same type, but the key values themselves do not have to be predefined. The possible keys may still be restricted with the choices argument.

__init__(name=None, sub_elem=None, defaults=None, allow_empty_keys=False, key_case='mixed', **kwargs)

Initialize the Config Element. :param name: The name of this Config Element :param ConfigElement sub_elem: The type all keys in this mapping must conform to. (required) :param Union(None,list) choices: The possible keys for this element. None denotes that any are valid. :param bool required: Whether this element is required. :param Union[dict,None] defaults: An optional dictionary of default key:value pairs. :param bool allow_empty_keys: Allow dict keys to be None when validating. :param str key_case: Must be one of the <cls>.KC_* values. Determines whether keys are automatically converted to lower or upper case, or left alone. :param help_text: Description of the purpose and usage of this element.

class yaml_config.ListElem(name=None, sub_elem=None, min_length=0, max_length=None, defaults=None, **kwargs)

A list of configuration items. All items in the list must be the same ConfigElement type. Configuration inheritance appends new, unique items to these lists.

A shortcut is allowed in the interpretation of lists, such that a single value is interpreted as a single valued list. Each of the following is valid.

colors: red
colors: [red, yellow, green]
colors:
    - red
    - yellow
    - blue

However, if the sub-element is another list, the lists must always be explicit.

collections:
    - [quarter, dime, nickel]
    - [thing1, thing2, thing3]
collections: [[quarter, dime, nickel], [thing1, thing2, thing3]

When dumping configs, the lists are always given explicitly.

__init__(name=None, sub_elem=None, min_length=0, max_length=None, defaults=None, **kwargs)
Parameters

  • sub_elem – A ConfigItem that each item in the list must conform to.

  • min_length – The minimum number of items allowed, inclusive. Default: 0

  • max_length – The maximum number of items allowed, inclusive. None denotes unlimited.

  • defaults ([]) – Defaults on a list are items that are added to the list if no items are explicitly added.

Validation

Validation has several steps.

  1. The value is checked to make sure it is of the type expected, if not type conversion is attempted. If this fails, a ValueError is raised.

  2. If the value was None, and required, a RequiredError is raised.

  3. Values outside the choices given raise a ValueError.

  4. After all values in a container type are validated, Derived Element values are generated.

  5. Finally, post validation functions are run for each element in a validated container.

Post Validation

Each element can also run a user provided post-validation function. The purpose of this step is to allow for custom, user provided validation, as well as provide a way to validate based on the values of other sibling elements (and their children). As shown above, this step occurs last in the validation process after all elements have their normally validated values. The function can be provided in one of three ways, and the first found is used:

  • As the post_validator argument to the Element’s __init__.

  • As a post_validator method on the Element itself (not defined by default).

  • As a post_validate_<key name> method on the container Element.

There are a couple of things to note:

  • The signature is post_validator(siblings, value)

    • siblings is all the validated data from the parent container.

    • value is the value of he element being validated.

  • The return value of the post_validator will replace the original value.

  • siblings may be a dict or list, depending on the container element.

  • Make sure siblings used in your post_validation should generally be required or have a default.

  • If a post-validator is found, it is expected to return the validated value.

  • In Keyed Elements and Yaml Configs, post-validators are executed in the order the elements were listed in ELEMENTS.

  • For Lists and Category Elements/Configs, the order is undefined.

  • If validation fails in a post_validator, a ValueError is expected to be raised. That error’s message and element location will be included in a more specific ValueError message raised from the container.

Example:

import yaml_config as yc

class MultTenElem(yc.IntElem):
    def post_validator(self, siblings, value):
        if value % 10 != 0:
            raise ValueError("Must be a multiple of 10.")

        return value

def bigger(siblings, value):
    if value <= siblings['by_tens']:
        raise ValueError('Must be larger than by_tens')

    return value

class MyConfig(yc.YamlConfigLoader):
    ELEMENTS = [
        MultTenElem('by_tens', required=True),
        yc.IntElem('bigger', post_validator=bigger),
        yc.ListElem('sum_smaller', sub_elem=IntElem())
        yc.IntElem('scale', post_validator=lambda sib, val: return val*10)
    ]

    def post_validate_sum_smaller(self, siblings, list_values):
        if sum(list_values) >= siblings['by_tens']:
            raise ValueError('Total more then by_tens')

        return list_values

Creating Your Own

The ConfigElement type forms the basis for all other element types. The class description below lists the class variables and methods expected to be overridden, as well as those most likely to be.

class yaml_config.ConfigElement(name=None, default=None, required=False, hidden=False, _sub_elem=None, choices=None, post_validator=None, help_text='')

The base class for all other element types.

Variables

  • type – The type object used to type-check, and convert if needed, the values loaded by YAML. This must be defined.

  • type_converter – A function that, given a generic value of unknown type, will convert it into the type expected by this ConfigElement. If this is None, the type object itself is used instead.

  • _type_name – The name of the type, if different from type.__name__.

__init__(name=None, default=None, required=False, hidden=False, _sub_elem=None, choices=None, post_validator=None, help_text='')

Most ConfigElement child classes take all of these arguments, and just add a few of their own.

Parameters

  • name (str) – The name of this configuration element. Required if this is a key in a KeyedElem. Will receive a descriptive default otherwise.

  • default – The default value if no value is retrieved from a config file.

  • required (bool) – When validating a config file, a RequiredError will be thrown if there is no value for this element. NULL does not count as a value.

  • hidden – Hidden elements are ignored when writing out the config (or example configs). They can still be set by the user.

  • choices (list) – A optional sequence of values that this type will accept.

  • post_validator (post_validator) – A optional post validation function for this element. See the Post-Validation section in the online documentation for more info.

  • _sub_elem (Union(ConfigElement,None)) – The ConfigElement contained within this one, such as for ListElem definitions. Meant to be set by subclasses if needed, never the user. Names are optional for all sub-elements, and will be given sane defaults.

Raises

ValueError – May raise a value error for invalid configuration options.

_check_range(value)

Make sure the value is in the given list of choices. Throws a ValueError if not.

The value of self.choices doesn’t matter outside of this method.

Returns

None

Raises

ValueError – When out of range.

make_comment(show_choices=True, show_name=True, recursive=False)

Create a comment for this configuration element.

Parameters

  • show_name – Whether to show the name of this element.

  • show_choices – Whether to include the valid choices for this item in the help comments.

  • recursive – The comments should recursively include the help for sub elements.

Returns

A comment string.

validate(value, partial=False)

Validate the given value, and return the validated form.

Returns

The value, converted to this type if needed.

Raises

  • ValueError – if the value is out of range.

  • RequiredError – if the value is required, but missing.