0
# OmegaConf
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: omegaconf
7
- **Language**: Python  
8
- **Installation**: `pip install omegaconf`
9

10
## Core Imports
11

12
```python
13
from omegaconf import OmegaConf, DictConfig, ListConfig
14
```
15

16
Common imports for structured configs and error handling:
17

18
```python
19
from omegaconf import (
20
    OmegaConf, DictConfig, ListConfig,
21
    MISSING, ValidationError, MissingMandatoryValue,
22
    __version__
23
)
24
```
25

26
## Basic Usage
27

28
```python
29
from omegaconf import OmegaConf, DictConfig
30

31
# Create from dictionary
32
config = OmegaConf.create({
33
    "database": {
34
        "driver": "mysql",
35
        "host": "localhost", 
36
        "port": 3306
37
    },
38
    "debug": True
39
})
40

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

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

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

54
# Variable interpolation
55
config = OmegaConf.create({
56
    "server": {
57
        "host": "localhost",
58
        "port": 8080,
59
        "url": "http://${server.host}:${server.port}"
60
    }
61
})
62
print(config.server.url)  # "http://localhost:8080"
63

64
# Convert to plain Python objects
65
python_dict = OmegaConf.to_container(config, resolve=True)
66
```
67

68
## Architecture
69

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

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

78
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.
79

80
## Capabilities
81

82
### Configuration Creation
83

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

86
```python { .api }
87
def create(obj=None, parent=None, flags=None): ...
88
def load(file_): ...
89
def save(config, f, resolve=False): ...
90
def from_cli(args_list=None): ...
91
def from_dotlist(dotlist): ...
92
```
93

94
[Configuration Creation](./configuration-creation.md)
95

96
### Configuration Containers
97

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

100
```python { .api }
101
class DictConfig(BaseContainer, MutableMapping[Any, Any]):
102
    def __init__(self, content, key=None, parent=None, ref_type=Any, key_type=Any, element_type=Any, is_optional=True, flags=None): ...
103
    def get(self, key, default_value=None): ...
104
    def pop(self, key, default=_DEFAULT_MARKER_): ...
105
    def keys(self): ...
106
    def items(self): ...
107

108
class ListConfig(BaseContainer, MutableSequence[Any]):
109
    def __init__(self, content, key=None, parent=None, element_type=Any, is_optional=True, ref_type=Any, flags=None): ...
110
    def append(self, item): ...
111
    def insert(self, index, item): ...
112
    def extend(self, lst): ...
113
```
114

115
[Configuration Containers](./containers.md)
116

117
### Configuration Manipulation
118

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

121
```python { .api }
122
def merge(*configs): ...
123
def select(cfg, key, default=None, throw_on_resolution_failure=True, throw_on_missing=False): ...
124
def update(cfg, key, value, merge=True, force_add=False): ...
125
def resolve(cfg): ...
126
def missing_keys(cfg): ...
127
```
128

129
[Configuration Manipulation](./manipulation.md)
130

131
### Type System & Nodes
132

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

135
```python { .api }
136
class StringNode(ValueNode): ...
137
class IntegerNode(ValueNode): ...
138
class FloatNode(ValueNode): ...
139
class BooleanNode(ValueNode): ...
140
class EnumNode(ValueNode): ...
141
class PathNode(ValueNode): ...
142
class AnyNode(ValueNode): ...
143
```
144

145
[Type System & Nodes](./types-and-nodes.md)
146

147
### Interpolation & Resolvers
148

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

151
```python { .api }
152
def II(interpolation: str) -> Any: ...
153
def SI(interpolation: str) -> Any: ...
154
def register_new_resolver(name, resolver, replace=False, use_cache=False): ...
155
def has_resolver(name): ...
156
def clear_resolvers(): ...
157
```
158

159
[Interpolation & Resolvers](./interpolation.md)
160

161
### Structured Configs
162

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

165
```python { .api }
166
def structured(obj, parent=None, flags=None): ...
167
def to_object(cfg): ...
168
def get_type(obj, key=None): ...
169
```
170

171
[Structured Configs](./structured-configs.md)
172

173
### Utilities & Context Managers
174

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

177
```python { .api }
178
def open_dict(config): ...
179
def read_write(config): ...
180
def flag_override(config, names, values): ...
181
def is_config(obj): ...
182
def is_missing(cfg, key): ...
183
def to_yaml(cfg, resolve=False, sort_keys=False): ...
184
```
185

186
[Utilities & Context Managers](./utilities.md)
187

188
## Constants
189

190
```python { .api }
191
MISSING: Any = "???"  # Sentinel for mandatory missing values
192
```
193

194
## Exception Classes
195

196
```python { .api }
197
class MissingMandatoryValue(OmegaConfBaseException): ...
198
class ValidationError(OmegaConfBaseException): ...
199
class ReadonlyConfigError(ValidationError): ...
200
class KeyValidationError(ValidationError): ...
201
class UnsupportedValueType(ValidationError): ...
202
class InterpolationResolutionError(OmegaConfBaseException): ...
203
```