0
# Configuration Creation
1

2
Methods for creating OmegaConf configurations from various sources including dictionaries, YAML files, dataclasses, command-line arguments, and dot notation lists.
3

4
## Capabilities
5

6
### Core Configuration Creation
7

8
Creates OmegaConf configurations from various Python objects including dictionaries, lists, dataclasses, and other structured objects.
9

10
```python { .api }
11
def create(obj=None, parent=None, flags=None):
12
    """
13
    Create a config from a variety of inputs.
14
    
15
    Parameters:
16
    - obj: Input object (dict, list, dataclass, object, or None for empty config)
17
    - parent: Parent node for nested configs
18
    - flags: Dict of configuration flags (struct, readonly, etc.)
19
    
20
    Returns:
21
    DictConfig or ListConfig based on input type
22
    """
23
```
24

25
```python { .api }
26
def structured(obj, parent=None, flags=None):
27
    """
28
    Create config from structured object (alias for create).
29
    
30
    Parameters:
31
    - obj: Structured object (dataclass, attrs class, or instance)
32
    - parent: Parent node for nested configs  
33
    - flags: Dict of configuration flags
34
    
35
    Returns:
36
    DictConfig with type validation based on structured schema
37
    """
38
```
39

40
### YAML File Loading
41

42
Loads configuration from YAML files with support for complex nested structures and OmegaConf-specific features.
43

44
```python { .api }
45
def load(file_):
46
    """
47
    Load configuration from YAML file or file-like object.
48
    
49
    Parameters:
50
    - file_: File path (str/Path) or file-like object
51
    
52
    Returns:
53
    DictConfig containing the loaded configuration
54
    
55
    Raises:
56
    - FileNotFoundError: If file doesn't exist
57
    - yaml.YAMLError: If YAML parsing fails
58
    """
59
```
60

61
```python { .api }
62
def save(config, f, resolve=False):
63
    """
64
    Save configuration object to a file.
65
    
66
    Parameters:
67
    - config: Configuration object (DictConfig, ListConfig, dataclass, or attrs)
68
    - f: File path (str/Path) or file-like object
69
    - resolve: Whether to resolve interpolations before saving (default: False)
70
    
71
    Notes:
72
    - Saves in YAML format
73
    - Automatically converts dataclass/attrs objects to configs before saving
74
    """
75
```
76

77
Usage examples:
78

79
```python
80
# Load from file path
81
config = OmegaConf.load("config.yaml")
82

83
# Save to file path
84
OmegaConf.save(config, "output.yaml")
85

86
# Save with resolved interpolations
87
OmegaConf.save(config, "resolved_config.yaml", resolve=True)
88

89
# Load from file object
90
with open("config.yaml") as f:
91
    config = OmegaConf.load(f)
92

93
# Save to file object
94
with open("output.yaml", "w") as f:
95
    OmegaConf.save(config, f)
96
```
97

98
### Command Line Arguments
99

100
Creates configuration from command-line arguments using dot notation syntax.
101

102
```python { .api }
103
def from_cli(args_list=None):
104
    """
105
    Create config from command line arguments.
106
    
107
    Parameters:
108
    - args_list: List of arguments (defaults to sys.argv[1:])
109
    
110
    Returns:
111
    DictConfig with parsed command line overrides
112
    
113
    Examples:
114
    - ["key=value"] -> {"key": "value"}
115
    - ["nested.key=123"] -> {"nested": {"key": 123}}
116
    - ["list=[1,2,3]"] -> {"list": [1, 2, 3]}
117
    """
118
```
119

120
Usage example:
121

122
```python
123
# From sys.argv automatically
124
config = OmegaConf.from_cli()
125

126
# From explicit argument list  
127
config = OmegaConf.from_cli(["database.host=localhost", "debug=true"])
128
```
129

130
### Dot Notation Lists
131

132
Creates configuration from lists of dot notation strings.
133

134
```python { .api }
135
def from_dotlist(dotlist):
136
    """
137
    Create config from list of dot notation assignments.
138
    
139
    Parameters:
140
    - dotlist: List of "key=value" strings using dot notation
141
    
142
    Returns:
143
    DictConfig with parsed assignments
144
    
145
    Examples:
146
    - ["a=1", "b.c=2"] -> {"a": 1, "b": {"c": 2}}
147
    - ["list=[1,2,3]"] -> {"list": [1, 2, 3]}
148
    """
149
```
150

151
Usage example:
152

153
```python
154
dotlist = [
155
    "server.host=localhost",
156
    "server.port=8080", 
157
    "features=[auth,logging]"
158
]
159
config = OmegaConf.from_dotlist(dotlist)
160
# Result: {"server": {"host": "localhost", "port": 8080}, "features": ["auth", "logging"]}
161
```
162

163
## Advanced Creation Patterns
164

165
### Creating with Flags
166

167
Configuration flags control behavior during creation and usage:
168

169
```python
170
# Create read-only config
171
config = OmegaConf.create({"key": "value"}, flags={"readonly": True})
172

173
# Create struct config (no new keys allowed)
174
config = OmegaConf.create({"key": "value"}, flags={"struct": True})
175
```
176

177
### Nested Configuration Creation
178

179
```python
180
# Create hierarchical configs with parent relationships
181
parent_config = OmegaConf.create({"parent_key": "parent_value"})
182
child_config = OmegaConf.create({"child_key": "child_value"}, parent=parent_config)
183
```
184

185
### Empty Configuration Creation
186

187
```python
188
# Create empty configurations
189
empty_dict = OmegaConf.create()  # Empty DictConfig
190
empty_list = OmegaConf.create([])  # Empty ListConfig
191
```