OmegaConf

OmegaConf is a hierarchical configuration system for Python that lets you build a single configuration object out of multiple sources — YAML files, YAML strings, plain dictionaries and lists, dataclass or attrs instances, environment variables, and command-line arguments — and work with all of them through one consistent API. Configs support variable interpolation (${a.b.c}), custom and built-in resolvers, mandatory-value markers (???), and deep merging that preserves type information across sources.

What sets OmegaConf apart from plain YAML loading is its Structured Configs feature: dataclasses and attrs classes can be used as schemas, giving runtime type validation, IDE-friendly static typing, and safe defaults, while still allowing the flexible source-merging YAML users expect. It’s the configuration engine underneath Hydra and is widely used across machine-learning and research codebases for managing experiment configuration.

What You Get

• A unified OmegaConf.create()/OmegaConf.merge() API that combines YAML files, YAML strings, plain Python containers, and structured (dataclass/attrs) configs into one config tree
• Variable interpolation (${a.b.c}) with a custom ANTLR-based grammar, built-in resolvers (env, oc.select, oc.decode, etc.), and support for registering custom resolvers
• Structured Configs — use dataclasses or attrs classes as schemas for runtime type validation and static type-checker/IDE support
• Fine-grained config flags: readonly, struct mode (reject unknown keys), and mandatory-value markers (???) that raise clearly when an unset value is accessed
• Deep merge semantics that combine multiple config sources while preserving reference types and validating compatibility
• Support for str, int, bool, float, bytes, and Enum dictionary key types, plus an experimental immutable TupleConfig

Common Use Cases

• Managing machine-learning experiment configuration (hyperparameters, dataset/model paths) merged from a base YAML file, environment-specific overrides, and CLI flags
• Defining typed application settings with dataclasses so config errors are caught at access time instead of deep inside business logic
• Composing configuration across multiple YAML files (defaults + environment-specific overrides) with a single deep-merge call
• Powering configuration for larger frameworks — OmegaConf is the config layer underneath Hydra and is used across PyTorch-ecosystem projects

Under The Hood

Architecture OmegaConf is built around a layered node hierarchy: an abstract Node (base.py) underlies Container (basecontainer.py), which is specialized into DictConfig, ListConfig, and TupleConfig, with leaf values wrapped by ValueNode subclasses in nodes.py. Interpolations (${...}) are parsed by a custom ANTLR4 grammar (omegaconf/grammar/*.g4, compiled into omegaconf/grammar/gen) and evaluated lazily by grammar_visitor.py only when an interpolated value is actually accessed. Structured configs are supported through dataclass/attrs introspection in _utils.py, which builds per-node type metadata (ref_type) used for runtime validation. The public OmegaConf class in omegaconf.py orchestrates creation, merging, and resolution, walking two node trees to produce a new merged tree while respecting per-node flags like readonly and struct. The separation between grammar/parsing, the node model, and the public API is clean, though the generated ANTLR parser and a vendored runtime under omegaconf/vendor add real complexity to anything touching the interpolation grammar itself.

Tech Stack A pure Python 3.10+ library (CI and packaging target py310–py314) with a single runtime dependency, PyYAML (requirements/base.txt). Interpolation parsing runs on an ANTLR4-generated parser, with the ANTLR runtime vendored directly under omegaconf/vendor to avoid adding antlr4-runtime as an installed dependency. Testing runs on pytest with Sphinx doctest integration for the documentation examples; linting uses Ruff (pyproject.toml [tool.ruff]) with isort import ordering, static typing is checked with Pyrefly, and CI runs on CircleCI via nox sessions across Python versions plus a dedicated Jupyter-notebook test session. Releases are version-bumped with bump-my-version, packaged via setuptools with a custom ANTLR build step, and docs are built with Sphinx and hosted on Read the Docs.

Code Quality The tests/ directory holds over fifty test modules covering base config operations, dict/list/tuple semantics, deep merging, the interpolation grammar, and a dedicated structured_conf suite for dataclass/attrs schemas — extensive coverage befitting a library that underlies widely used tools like Hydra. Errors are explicit and typed rather than generic: errors.py defines a hierarchy of exceptions (MissingMandatoryValue, KeyValidationError, and others) that carry structured context such as the offending node, full key path, and expected/actual types. Ruff enforces lint rules and import ordering, Pyrefly performs static type checking against an explicit project-includes list, and CircleCI runs the full nox test matrix plus coverage tracking via Coveralls on every push.

API Design The public surface is small and consistent — OmegaConf.create(), .merge(), .load(), .to_yaml(), .structured() — so most usage funnels through a handful of well-documented entry points rather than a sprawling API. Structured Configs let a plain @dataclass double as a schema with almost no boilerplate, and the ??? mandatory-value marker and struct flag give clear, immediate failures instead of silent Nones or typos surfacing far from their source. Documentation is thorough: a Sphinx site with runnable doctest examples for every major feature (interpolation, resolvers, structured configs, grammar, YAML aliases), which keeps the docs verified against the actual behavior on every docs build.