Skip to main content

Config Syntax

We use the yaml file format for configuration with some enhancements through custom tags and utility functions.

YAML Tags​

The following custom YAML tags are supported:

  • !include <PATH>.yaml - Reads and includes the content of another YAML file at the position of the tag. When using relative paths, they are resolved relative to the directory of the YAML file being loaded.

  • !flatten_seq - Flattens a nested sequence into a single-level sequence.

    Example.yaml
    arrays: !flatten_seq
        - - a
          - b
        - c

    Will be translated to:

    Actually_Loaded.yaml
    arrays:
        - a
        - b
        - c

Utility Functions​

The configuration system provides several utility functions:

load_config(path: Path)​

Loads a YAML configuration file and returns it as both a SimpleNamespace object and a dictionary.

build_dynamic_config(spec: DynamicConfigSpec)​

Builds a configuration from a dynamic specification that can include:

  • Dictionary configurations
  • List configurations
  • LoadFrom objects that specify paths to load YAML files
  • Primitive types (str, int, float, bool)

asNamespace(dictionary)​

Converts a dictionary into a SimpleNamespace object, with nested dictionaries also being converted to SimpleNamespace objects. Null values are converted to empty SimpleNamespace objects.

namespace_to_cfgnode(ns: SimpleNamespace)​

Converts a SimpleNamespace configuration to a YACS CfgNode format, which is used by some components like Flowformer.

Type Definitions​

The configuration system uses the following type definitions:

DynamicConfigSpec = dict[str, "DynamicConfigSpec"] | list["DynamicConfigSpec"] | LoadFrom | str | int | float | bool | None

Error Handling​

The configuration system includes robust error handling:

  • Attempts to include non-existent files will raise a ValueError with a descriptive message
  • File existence is checked before loading
  • Type safety is enforced through type hints and runtime checks