0
# Configuration Containers
1

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

4
## Capabilities
5

6
### DictConfig
7

8
Configuration container that behaves like a dictionary while providing OmegaConf's advanced features including type validation, interpolation, and attribute access.
9

10
```python { .api }
11
class DictConfig(BaseContainer, MutableMapping[Any, Any]):
12
    def __init__(self, content, key=None, parent=None, ref_type=Any, key_type=Any, element_type=Any, is_optional=True, flags=None):
13
        """
14
        Create a DictConfig instance.
15
        
16
        Parameters:
17
        - content: Dict, DictConfig, structured object, or None
18
        - key: Key name if this is a child node
19
        - parent: Parent container
20
        - ref_type: Reference type for structured configs
21
        - key_type: Type validation for dictionary keys
22
        - element_type: Type validation for dictionary values
23
        - is_optional: Whether this node can be None
24
        - flags: Configuration flags (readonly, struct, etc.)
25
        """
26
```
27

28
#### Dictionary Interface Methods
29

30
```python { .api }
31
def get(self, key, default_value=None):
32
    """
33
    Get value with optional default.
34
    
35
    Parameters:
36
    - key: Dictionary key
37
    - default_value: Value to return if key not found
38
    
39
    Returns:
40
    Value at key or default_value
41
    """
42

43
def pop(self, key, default=_DEFAULT_MARKER_):
44
    """
45
    Remove and return value at key.
46
    
47
    Parameters:
48
    - key: Dictionary key to remove
49
    - default: Value to return if key not found
50
    
51
    Returns:
52
    Removed value or default
53
    
54
    Raises:
55
    - KeyError: If key not found and no default provided
56
    """
57

58
def keys():
59
    """
60
    Get dictionary keys.
61
    
62
    Returns:
63
    KeysView of configuration keys
64
    """
65

66
def items():
67
    """
68
    Get key-value pairs.
69
    
70
    Returns:
71
    ItemsView of (key, value) pairs
72
    """
73

74
def items_ex(self, resolve=True, keys=None):
75
    """
76
    Extended items with interpolation and filtering options.
77
    
78
    Parameters:
79
    - resolve: Whether to resolve interpolations
80
    - keys: Optional list of keys to include
81
    
82
    Returns:
83
    Generator of (key, value) pairs
84
    """
85

86
def setdefault(self, key, default=None):
87
    """
88
    Set key to default if not present.
89
    
90
    Parameters:
91
    - key: Dictionary key
92
    - default: Value to set if key not found
93
    
94
    Returns:
95
    Existing value or newly set default
96
    """
97
```
98

99
#### Additional Methods
100

101
```python { .api }
102
def copy():
103
    """
104
    Create shallow copy of DictConfig.
105
    
106
    Returns:
107
    New DictConfig with copied structure
108
    """
109
```
110

111
### ListConfig
112

113
Configuration container that behaves like a list while providing OmegaConf's features including type validation and interpolation support.
114

115
```python { .api }
116
class ListConfig(BaseContainer, MutableSequence[Any]):
117
    def __init__(self, content, key=None, parent=None, element_type=Any, is_optional=True, ref_type=Any, flags=None):
118
        """
119
        Create a ListConfig instance.
120
        
121
        Parameters:
122
        - content: List, tuple, ListConfig, or None
123
        - key: Key name if this is a child node
124
        - parent: Parent container
125
        - element_type: Type validation for list elements
126
        - is_optional: Whether this node can be None
127
        - ref_type: Reference type for structured configs
128
        - flags: Configuration flags (readonly, struct, etc.)
129
        """
130
```
131

132
#### List Interface Methods
133

134
```python { .api }
135
def append(self, item):
136
    """
137
    Add item to end of list.
138
    
139
    Parameters:
140
    - item: Item to append
141
    """
142

143
def insert(self, index, item):
144
    """
145
    Insert item at specified index.
146
    
147
    Parameters:
148
    - index: Position to insert at
149
    - item: Item to insert
150
    """
151

152
def extend(self, lst):
153
    """
154
    Extend list with items from iterable.
155
    
156
    Parameters:
157
    - lst: Iterable of items to add
158
    """
159

160
def remove(self, x):
161
    """
162
    Remove first occurrence of value.
163
    
164
    Parameters:
165
    - x: Value to remove
166
    
167
    Raises:
168
    - ValueError: If value not found
169
    """
170

171
def pop(self, index=-1):
172
    """
173
    Remove and return item at index.
174
    
175
    Parameters:
176
    - index: Index to remove (default: last item)
177
    
178
    Returns:
179
    Removed item
180
    
181
    Raises:
182
    - IndexError: If index out of range
183
    """
184

185
def clear(self):
186
    """Remove all items from list."""
187

188
def index(self, x, start=0, end=None):
189
    """
190
    Find index of first occurrence of value.
191
    
192
    Parameters:
193
    - x: Value to find
194
    - start: Start search index
195
    - end: End search index
196
    
197
    Returns:
198
    Index of value
199
    
200
    Raises:
201
    - ValueError: If value not found
202
    """
203

204
def count(self, x):
205
    """
206
    Count occurrences of value.
207
    
208
    Parameters:
209
    - x: Value to count
210
    
211
    Returns:
212
    Number of occurrences
213
    """
214

215
def sort(self, key=None, reverse=False):
216
    """
217
    Sort list in place.
218
    
219
    Parameters:
220
    - key: Function to compute sort key
221
    - reverse: Whether to sort in reverse order
222
    """
223
```
224

225
## Usage Examples
226

227
### DictConfig Usage
228

229
```python
230
from omegaconf import OmegaConf
231

232
# Create and use DictConfig
233
config = OmegaConf.create({
234
    "database": {"host": "localhost", "port": 3306},
235
    "debug": True
236
})
237

238
# Access via attribute or dictionary syntax
239
print(config.database.host)  # "localhost"
240
print(config["database"]["port"])  # 3306
241

242
# Dictionary methods
243
print(config.get("missing_key", "default"))  # "default"
244
print(list(config.keys()))  # ["database", "debug"]
245

246
# Modify configuration
247
config.database.host = "remote-server"
248
config["new_key"] = "new_value"
249
```
250

251
### ListConfig Usage
252

253
```python
254
from omegaconf import OmegaConf
255

256
# Create and use ListConfig
257
config = OmegaConf.create([1, 2, 3, {"nested": "value"}])
258

259
# List operations
260
config.append(4)
261
config.insert(0, 0)
262
config.extend([5, 6])
263

264
# Access elements
265
print(config[0])  # 0
266
print(config[-1].nested)  # "value" (nested DictConfig)
267

268
# List methods
269
print(config.count(1))  # 1
270
print(config.index(3))  # 3
271
```
272

273
### Type Validation
274

275
```python
276
from omegaconf import OmegaConf, ValidationError
277

278
# Create with type constraints
279
config = OmegaConf.create({}, key_type=str, element_type=int)
280

281
config["valid_key"] = 123  # OK
282
try:
283
    config[123] = "value"  # KeyValidationError - key must be str
284
except ValidationError:
285
    pass
286

287
try:
288
    config["key"] = "invalid"  # ValidationError - value must be int
289
except ValidationError:
290
    pass
291
```