or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-creation.mdcontainers.mdindex.mdinterpolation.mdmanipulation.mdstructured-configs.mdtypes-and-nodes.mdutilities.md
tile.json

tessl/pypi-omegaconf

A flexible configuration library that provides hierarchical configuration management with YAML support, variable interpolation, and type validation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/omegaconf@2.3.x

To install, run

npx @tessl/cli install tessl/pypi-omegaconf@2.3.0

index.mddocs/

OmegaConf

A hierarchical configuration system that provides a unified API for handling configurations from multiple sources including YAML files, dataclasses/objects, and CLI arguments. OmegaConf supports advanced features like configuration merging, variable interpolation, type safety with structured configs, missing value handling, and dynamic configuration modification at runtime.

Package Information

  • Package Name: omegaconf
  • Language: Python
  • Installation: pip install omegaconf

Core Imports

from omegaconf import OmegaConf, DictConfig, ListConfig

Common imports for structured configs and error handling:

from omegaconf import (
    OmegaConf, DictConfig, ListConfig,
    MISSING, ValidationError, MissingMandatoryValue,
    __version__
)

Basic Usage

from omegaconf import OmegaConf, DictConfig

# Create from dictionary
config = OmegaConf.create({
    "database": {
        "driver": "mysql",
        "host": "localhost", 
        "port": 3306
    },
    "debug": True
})

# Access values with dot notation or dictionary syntax
print(config.database.host)  # "localhost"
print(config["database"]["port"])  # 3306

# Load from YAML file
config = OmegaConf.load("config.yaml")

# Merge configurations
base_config = OmegaConf.create({"a": 1, "b": 2})
override_config = OmegaConf.create({"b": 3, "c": 4})
merged = OmegaConf.merge(base_config, override_config)
print(merged)  # {"a": 1, "b": 3, "c": 4}

# Variable interpolation
config = OmegaConf.create({
    "server": {
        "host": "localhost",
        "port": 8080,
        "url": "http://${server.host}:${server.port}"
    }
})
print(config.server.url)  # "http://localhost:8080"

# Convert to plain Python objects
python_dict = OmegaConf.to_container(config, resolve=True)

Architecture

OmegaConf's design centers around a hierarchical node system that provides type safety, validation, and flexible configuration management:

  • OmegaConf: Main utility class providing static methods for configuration operations
  • Container Classes: DictConfig and ListConfig represent dictionary and list structures
  • Value Nodes: Specialized nodes (StringNode, IntegerNode, etc.) handle type validation and conversion
  • Interpolation System: Custom resolvers enable dynamic value computation and variable substitution
  • Structured Configs: Integration with Python dataclasses and attrs for type-safe configuration schemas

This architecture enables OmegaConf to serve as a comprehensive configuration management solution for applications ranging from simple scripts to complex machine learning pipelines and distributed systems.

Capabilities

Configuration Creation

Primary methods for creating OmegaConf configurations from various sources including dictionaries, YAML files, dataclasses, command-line arguments, and dot notation lists.

def create(obj=None, parent=None, flags=None): ...
def load(file_): ...
def save(config, f, resolve=False): ...
def from_cli(args_list=None): ...
def from_dotlist(dotlist): ...

Configuration Creation

Configuration Containers

Container classes DictConfig and ListConfig that provide dictionary and list-like interfaces with additional OmegaConf features like type validation, interpolation support, and configuration flags.

class DictConfig(BaseContainer, MutableMapping[Any, Any]):
    def __init__(self, content, key=None, parent=None, ref_type=Any, key_type=Any, element_type=Any, is_optional=True, flags=None): ...
    def get(self, key, default_value=None): ...
    def pop(self, key, default=_DEFAULT_MARKER_): ...
    def keys(self): ...
    def items(self): ...

class ListConfig(BaseContainer, MutableSequence[Any]):
    def __init__(self, content, key=None, parent=None, element_type=Any, is_optional=True, ref_type=Any, flags=None): ...
    def append(self, item): ...
    def insert(self, index, item): ...
    def extend(self, lst): ...

Configuration Containers

Configuration Manipulation

Methods for updating, merging, selecting, and modifying configurations including dot notation access, deep merging strategies, and configuration resolution.

def merge(*configs): ...
def select(cfg, key, default=None, throw_on_resolution_failure=True, throw_on_missing=False): ...
def update(cfg, key, value, merge=True, force_add=False): ...
def resolve(cfg): ...
def missing_keys(cfg): ...

Configuration Manipulation

Type System & Nodes

Value node classes that handle type validation, conversion, and specialized data types including strings, numbers, booleans, enums, paths, and custom types.

class StringNode(ValueNode): ...
class IntegerNode(ValueNode): ...
class FloatNode(ValueNode): ...
class BooleanNode(ValueNode): ...
class EnumNode(ValueNode): ...
class PathNode(ValueNode): ...
class AnyNode(ValueNode): ...

Type System & Nodes

Interpolation & Resolvers

Variable interpolation system with custom resolvers for dynamic value computation, including built-in resolvers and registration of custom resolver functions.

def II(interpolation: str) -> Any: ...
def SI(interpolation: str) -> Any: ...
def register_new_resolver(name, resolver, replace=False, use_cache=False): ...
def has_resolver(name): ...
def clear_resolvers(): ...

Interpolation & Resolvers

Structured Configs

Integration with Python dataclasses and attrs classes for type-safe configuration schemas, enabling automatic validation and IDE support.

def structured(obj, parent=None, flags=None): ...
def to_object(cfg): ...
def get_type(obj, key=None): ...

Structured Configs

Utilities & Context Managers

Helper functions, context managers for temporary configuration state changes, and utility methods for configuration inspection and conversion.

def open_dict(config): ...
def read_write(config): ...
def flag_override(config, names, values): ...
def is_config(obj): ...
def is_missing(cfg, key): ...
def to_yaml(cfg, resolve=False, sort_keys=False): ...

Utilities & Context Managers

Constants

MISSING: Any = "???"  # Sentinel for mandatory missing values

Exception Classes

class MissingMandatoryValue(OmegaConfBaseException): ...
class ValidationError(OmegaConfBaseException): ...
class ReadonlyConfigError(ValidationError): ...
class KeyValidationError(ValidationError): ...
class UnsupportedValueType(ValidationError): ...
class InterpolationResolutionError(OmegaConfBaseException): ...