0
# Configuration Manipulation
1

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

4
## Capabilities
5

6
### Configuration Merging
7

8
Combines multiple configurations with different merging strategies and conflict resolution approaches.
9

10
```python { .api }
11
def merge(*configs):
12
    """
13
    Merge multiple configs with copying for safety.
14
    
15
    Parameters:
16
    - *configs: Variable number of configs to merge (DictConfig, ListConfig, or dicts/lists)
17
    
18
    Returns:
19
    Merged configuration (DictConfig or ListConfig)
20
    
21
    Notes:
22
    - Later configs override earlier ones
23
    - Creates copies to avoid modifying originals
24
    - Supports deep merging of nested structures
25
    """
26

27
def unsafe_merge(*configs):
28
    """
29
    Fast merge without copying for performance.
30
    
31
    Parameters:
32
    - *configs: Variable number of configs to merge
33
    
34
    Returns:
35
    Merged configuration
36
    
37
    Warning:
38
    - May modify input configurations
39
    - Use only when input configs won't be reused
40
    """
41
```
42

43
### Dot Notation Selection
44

45
Selects values from nested configurations using dot notation paths with robust error handling.
46

47
```python { .api }
48
def select(cfg, key, default=None, throw_on_resolution_failure=True, throw_on_missing=False):
49
    """
50
    Select value using dot notation key.
51
    
52
    Parameters:
53
    - cfg: Configuration to select from
54
    - key: Dot notation key (e.g., "database.host" or "servers[0].name")
55
    - default: Value to return if key not found
56
    - throw_on_resolution_failure: Whether to raise on interpolation errors
57
    - throw_on_missing: Whether to raise on missing keys
58
    
59
    Returns:
60
    Selected value or default
61
    
62
    Examples:
63
    - select(cfg, "database.host") -> cfg.database.host
64
    - select(cfg, "servers[0]") -> cfg.servers[0]
65
    - select(cfg, "missing.key", "default") -> "default"
66
    """
67
```
68

69
### Configuration Updates
70

71
Updates configuration values using dot notation with support for nested creation and type validation.
72

73
```python { .api }
74
def update(cfg, key, value, merge=True, force_add=False):
75
    """
76
    Update configuration value using dot notation.
77
    
78
    Parameters:
79
    - cfg: Configuration to update
80
    - key: Dot notation key for update location
81
    - value: New value to set
82
    - merge: Whether to merge if value is a config/dict
83
    - force_add: Whether to add new keys even in struct mode
84
    
85
    Examples:
86
    - update(cfg, "database.host", "new-host")
87
    - update(cfg, "new.nested.key", {"a": 1, "b": 2})
88
    """
89
```
90

91
### Interpolation Resolution
92

93
Resolves all variable interpolations in configurations with cycle detection and error handling.
94

95
```python { .api }
96
def resolve(cfg):
97
    """
98
    Resolve all interpolations in configuration.
99
    
100
    Parameters:
101
    - cfg: Configuration to resolve
102
    
103
    Returns:
104
    None (modifies configuration in-place)
105
    
106
    Notes:
107
    - Resolves ${key} interpolations
108
    - Handles nested interpolations
109
    - Detects and prevents circular references
110
    - Uses registered resolvers for custom interpolations
111
    """
112
```
113

114
### Missing Key Detection
115

116
Identifies keys with missing mandatory values throughout the configuration hierarchy.
117

118
```python { .api }
119
def missing_keys(cfg):
120
    """
121
    Get set of keys with missing mandatory values.
122
    
123
    Parameters:
124
    - cfg: Configuration to analyze
125
    
126
    Returns:
127
    Set of dot notation paths to missing keys
128
    
129
    Examples:
130
    - {"key": "???"} -> {"key"}
131
    - {"nested": {"key": "???"}} -> {"nested.key"}
132
    """
133
```
134

135
### Configuration Copying and Masking
136

137
Creates modified copies of configurations with selective key inclusion and state preservation.
138

139
```python { .api }
140
def masked_copy(conf, keys):
141
    """
142
    Create copy with only specified keys included.
143
    
144
    Parameters:
145
    - conf: Configuration to copy
146
    - keys: List of keys to include in copy
147
    
148
    Returns:
149
    New configuration with only specified keys
150
    """
151
```
152

153
## Usage Examples
154

155
### Merging Configurations
156

157
```python
158
from omegaconf import OmegaConf
159

160
# Basic merging
161
base = OmegaConf.create({"a": 1, "b": {"x": 10}})
162
override = OmegaConf.create({"b": {"y": 20}, "c": 3})
163
merged = OmegaConf.merge(base, override)
164
# Result: {"a": 1, "b": {"x": 10, "y": 20}, "c": 3}
165

166
# Multiple config merging
167
config = OmegaConf.merge(base_config, user_config, cli_overrides)
168

169
# Performance-focused merging (unsafe)
170
result = OmegaConf.unsafe_merge(cfg1, cfg2, cfg3)
171
```
172

173
### Dot Notation Operations
174

175
```python
176
from omegaconf import OmegaConf
177

178
config = OmegaConf.create({
179
    "database": {
180
        "connections": [
181
            {"host": "primary", "port": 5432},
182
            {"host": "replica", "port": 5432}
183
        ]
184
    },
185
    "features": {"auth": True, "logging": "???"}
186
})
187

188
# Select values
189
host = OmegaConf.select(config, "database.connections[0].host")  # "primary"
190
missing = OmegaConf.select(config, "missing.key", default="fallback")  # "fallback"
191

192
# Update values
193
OmegaConf.update(config, "database.connections[1].port", 5433)
194
OmegaConf.update(config, "new.nested.setting", {"enabled": True})
195

196
# Check for missing values
197
missing_keys = OmegaConf.missing_keys(config)  # {"features.logging"}
198
```
199

200
### Configuration Resolution
201

202
```python
203
from omegaconf import OmegaConf
204

205
# Config with interpolations
206
config = OmegaConf.create({
207
    "server": {
208
        "host": "localhost",
209
        "port": 8080,
210
        "url": "http://${server.host}:${server.port}",
211
        "api_url": "${server.url}/api/v1"
212
    },
213
    "client": {
214
        "endpoint": "${server.api_url}/users"
215
    }
216
})
217

218
# Before resolution
219
print(config.server.url)  # "http://${server.host}:${server.port}"
220

221
# Resolve all interpolations
222
OmegaConf.resolve(config)
223

224
# After resolution
225
print(config.server.url)      # "http://localhost:8080"
226
print(config.client.endpoint) # "http://localhost:8080/api/v1/users"
227
```
228

229
### Advanced Manipulation
230

231
```python
232
from omegaconf import OmegaConf
233

234
config = OmegaConf.create({
235
    "database": {"host": "localhost", "port": 5432},
236
    "cache": {"enabled": True, "ttl": 300},
237
    "logging": {"level": "INFO", "file": "/var/log/app.log"}
238
})
239

240
# Create masked copy with subset of keys
241
db_config = OmegaConf.masked_copy(config, ["database"])
242
# Result: {"database": {"host": "localhost", "port": 5432}}
243

244
# Bulk updates with merging
245
updates = {"database": {"pool_size": 10}, "cache": {"ttl": 600}}
246
for key, value in updates.items():
247
    OmegaConf.update(config, key, value, merge=True)
248

249
# Check configuration completeness
250
if OmegaConf.missing_keys(config):
251
    print("Configuration has missing mandatory values")
252
```