StrataConf

A layered configuration library based on OmegaConf with nested includes, object instantiation, YAML-based argparse definitions and fingerprinting.

Welcome

A layered configuration library for Python. StrataConf merges configuration from three layers: defaults, configs and overrides. Each layer can have multiple sources with all sources and layers being maintained independently.

Features include:

• Includes via includes: from files or published packages
• Interpolation via ${...} using configuration paths or resolvers
• Object instantiation via _target_ with typed coercion
• Configuration of argparse from YAML files to enable command-line overrides
• Extracting field defaults from dataclass/Pydantic classes
• Overriding function parameter defaults via the config_defaults decorator
• Tracking actively-used configuration values
• Creating a unique fingerprint of a subset of configuration values

It is built on OmegaConf, with some changes to streamline usage (e.g., adds resolvers without namespaces). Refer to the OmegaConf docs for the underlying expression grammar.

Install

pip install strataconf

Quick Start

from strataconf import Config

config = Config()
config.load_defaults("configs/defaults.yaml")     # base layer
config.load_config("configs/config.yaml")         # main layer, on top of defaults
config.add_overrides({"server": {"port": 9000}})  # highest-precedence layer

port = config.get("server.port")                  # merged + interpolated value

Learning More

To learn the fundamentals, read through the configuration basics:

• Basic Structure: How configuration files and dot-separated paths work.
• Includes: Split configuration across files and published packages.
• Expressions: Reference other values and call resolvers with ${...}.
• Resolvers: The built-in resolvers and how to register your own.
• Defaults & Overrides: How the three layers merge.

To explore the more advanced features, check out:

• Object Instantiation: Construct objects and call factory functions via _target_.
• CLI Argument Parsing: Define argparse specs in YAML and map them to configuration paths.
• Class Field Defaults: Seed defaults from dataclasses and Pydantic models.
• Defaults Decorator: Fill a function’s parameters from the configuration.
• Usage Tracking: Capture exactly which values a run used.
• Fingerprinting: Uniquely identify a configuration and detect changes between runs.

For the full programmatic surface, see Programmatic Usage, and for the complete API, see the Reference.