0
# Settings
1

2
Functions for customizing parsing behavior, loader/dumper settings, and global configuration options. These settings control how jsonargparse processes arguments, handles configuration files, and integrates with different data formats and validation systems.
3

4
## Capabilities
5

6
### Parsing Settings
7

8
Global configuration function for customizing parsing behavior across all parsers.
9

10
```python { .api }
11
def set_parsing_settings(
12
    validation: Optional[bool] = None,
13
    docstring_parser: Optional[Union[str, bool]] = None,
14
    parse_as_dict: Optional[bool] = None,
15
    urls_enabled: Optional[bool] = None,
16
    fsspec_enabled: Optional[bool] = None,
17
    **kwargs
18
) -> None:
19
    """
20
    Set global parsing settings that affect all ArgumentParser instances.
21
    
22
    Args:
23
        validation: Enable/disable argument validation
24
        docstring_parser: Docstring parser to use ('google', 'sphinx', 'numpy', or False)
25
        parse_as_dict: Whether to parse config files as dictionaries instead of objects
26
        urls_enabled: Enable/disable URL support for configuration files
27
        fsspec_enabled: Enable/disable fsspec filesystem support
28
        **kwargs: Additional parsing settings
29
    """
30
```
31

32
### File Format Loaders
33

34
Functions for customizing how different file formats are loaded and parsed.
35

36
```python { .api }
37
def set_loader(format_name: str, loader: Callable[[str], Any]) -> None:
38
    """
39
    Set custom loader function for a file format.
40
    
41
    Args:
42
        format_name: Name of the format (e.g., 'yaml', 'json', 'toml')
43
        loader: Function that takes a string and returns parsed data
44
    """
45

46
def get_loader(format_name: str) -> Callable[[str], Any]:
47
    """
48
    Get the current loader function for a file format.
49
    
50
    Args:
51
        format_name: Name of the format to get loader for
52
        
53
    Returns:
54
        Callable[[str], Any]: Current loader function for the format
55
        
56
    Raises:
57
        ValueError: If format is not supported
58
    """
59
```
60

61
### File Format Dumpers
62

63
Functions for customizing how data is serialized to different file formats.
64

65
```python { .api }
66
def set_dumper(format_name: str, dumper: Callable[[Any], str]) -> None:
67
    """
68
    Set custom dumper function for a file format.
69
    
70
    Args:
71
        format_name: Name of the format (e.g., 'yaml', 'json', 'toml')
72
        dumper: Function that takes data and returns a string
73
    """
74

75
def get_dumper(format_name: str) -> Callable[[Any], str]:
76
    """
77
    Get the current dumper function for a file format.
78
    
79
    Args:
80
        format_name: Name of the format to get dumper for
81
        
82
    Returns:
83
        Callable[[Any], str]: Current dumper function for the format
84
        
85
    Raises:
86
        ValueError: If format is not supported
87
    """
88
```
89

90
### Configuration Reading
91

92
Functions for controlling how configuration files are read and processed.
93

94
```python { .api }
95
def _get_config_read_mode() -> str:
96
    """
97
    Get the current configuration reading mode.
98
    
99
    Returns:
100
        str: Current config reading mode ('fr', 'fc', etc.)
101
    """
102
```
103

104
## Usage Examples
105

106
### Customizing Parsing Behavior
107

108
```python
109
from jsonargparse import set_parsing_settings, ArgumentParser
110

111
# Configure global parsing settings
112
set_parsing_settings(
113
    validation=True,           # Enable strict validation
114
    docstring_parser="google", # Use Google-style docstring parsing
115
    parse_as_dict=False,       # Parse as objects, not dictionaries
116
    urls_enabled=True          # Enable loading configs from URLs
117
)
118

119
def train_model(
120
    data_path: str,
121
    epochs: int = 100,
122
    learning_rate: float = 0.001
123
) -> None:
124
    """
125
    Train a machine learning model.
126
    
127
    Args:
128
        data_path: Path to training data directory
129
        epochs: Number of training epochs
130
        learning_rate: Learning rate for optimizer
131
    """
132
    print(f"Training with {epochs} epochs at lr={learning_rate}")
133

134
parser = ArgumentParser()
135
parser.add_function_arguments(train_model)
136

137
# Parser will use the global settings configured above
138
config = parser.parse_args()
139
train_model(**config.as_dict())
140
```
141

142
### Custom File Format Loaders
143

144
```python
145
from jsonargparse import set_loader, get_loader, ArgumentParser
146
import configparser
147
import json
148

149
# Define custom INI file loader
150
def load_ini(ini_string: str) -> dict:
151
    """Load INI format configuration."""
152
    config = configparser.ConfigParser()
153
    config.read_string(ini_string)
154
    
155
    # Convert to nested dictionary
156
    result = {}
157
    for section_name in config.sections():
158
        result[section_name] = dict(config[section_name])
159
    
160
    return result
161

162
# Register custom loader
163
set_loader("ini", load_ini)
164

165
# Now INI files can be used as configuration
166
parser = ArgumentParser()
167
parser.add_argument("--config", action="config_file")
168
parser.add_argument("--name", type=str)
169
parser.add_argument("--database.host", type=str)
170
parser.add_argument("--database.port", type=int)
171

172
# Can now load INI files
173
config = parser.parse_args()
174

175
print(f"Name: {config.name}")
176
print(f"DB Host: {config.database.host}")
177
print(f"DB Port: {config.database.port}")
178
```
179

180
With INI config file `config.ini`:
181
```ini
182
[DEFAULT]
183
name = MyApp
184

185
[database]
186
host = localhost
187
port = 5432
188
```
189

190
Usage:
191
```bash
192
python script.py --config config.ini
193
```
194

195
### Custom File Format Dumpers
196

197
```python
198
from jsonargparse import set_dumper, ArgumentParser
199
import configparser
200
from io import StringIO
201

202
# Define custom INI dumper
203
def dump_ini(data: dict) -> str:
204
    """Dump data to INI format."""
205
    config = configparser.ConfigParser()
206
    
207
    # Handle nested dictionaries
208
    for key, value in data.items():
209
        if isinstance(value, dict):
210
            config[key] = value
211
        else:
212
            if 'DEFAULT' not in config:
213
                config['DEFAULT'] = {}
214
            config['DEFAULT'][key] = str(value)
215
    
216
    # Write to string
217
    output = StringIO()
218
    config.write(output)
219
    return output.getvalue()
220

221
# Register custom dumper
222
set_dumper("ini", dump_ini)
223

224
parser = ArgumentParser()
225
parser.add_argument("--name", type=str, default="MyApp")
226
parser.add_argument("--database.host", type=str, default="localhost")
227
parser.add_argument("--database.port", type=int, default=5432)
228

229
config = parser.parse_args()
230

231
# Save configuration in INI format
232
parser.save(config, "output.ini", format="ini")
233

234
# Or get as string
235
ini_string = parser.dump(config, format="ini")
236
print(ini_string)
237
```
238

239
### Advanced Docstring Parsing
240

241
```python
242
from jsonargparse import set_parsing_settings, ArgumentParser
243

244
# Enable Google-style docstring parsing
245
set_parsing_settings(docstring_parser="google")
246

247
def process_data(
248
    input_file: str,
249
    output_file: str,
250
    batch_size: int = 32,
251
    normalize: bool = True
252
) -> None:
253
    """
254
    Process data files with optional normalization.
255
    
256
    This function reads data from the input file, processes it in batches,
257
    and writes the results to the output file.
258
    
259
    Args:
260
        input_file: Path to the input data file. Must be readable.
261
        output_file: Path where processed data will be written.
262
        batch_size: Number of items to process in each batch. Must be positive.
263
        normalize: Whether to normalize the data values to [0, 1] range.
264
        
265
    Returns:
266
        None: Results are written to the output file.
267
        
268
    Raises:
269
        FileNotFoundError: If input file doesn't exist.
270
        PermissionError: If output file cannot be written.
271
    """
272
    print(f"Processing {input_file} -> {output_file}")
273
    print(f"Batch size: {batch_size}, Normalize: {normalize}")
274

275
# Parser automatically extracts detailed help from docstring
276
parser = ArgumentParser()
277
parser.add_function_arguments(process_data)
278

279
# Help text will include detailed descriptions from docstring
280
config = parser.parse_args()
281
```
282

283
### Custom Configuration Validation
284

285
```python
286
from jsonargparse import set_parsing_settings, ArgumentParser
287
import logging
288

289
# Enable strict validation
290
set_parsing_settings(validation=True)
291

292
class ValidatedConfig:
293
    def __init__(self, 
294
                 name: str,
295
                 port: int,
296
                 debug: bool = False):
297
        # Custom validation
298
        if not name or len(name) < 3:
299
            raise ValueError("Name must be at least 3 characters")
300
        if not (1024 <= port <= 65535):
301
            raise ValueError("Port must be between 1024 and 65535")
302
            
303
        self.name = name
304
        self.port = port
305
        self.debug = debug
306
        
307
        if debug:
308
            logging.basicConfig(level=logging.DEBUG)
309

310
parser = ArgumentParser()
311
parser.add_class_arguments(ValidatedConfig, "config")
312

313
try:
314
    config = parser.parse_args()
315
    app_config = ValidatedConfig(**config.config.as_dict())
316
    print(f"Valid config: {app_config.name}:{app_config.port}")
317
except ValueError as e:
318
    print(f"Configuration validation failed: {e}")
319
```
320

321
### URL Configuration Support
322

323
```python
324
from jsonargparse import set_parsing_settings, ArgumentParser
325

326
# Enable URL support for configuration files
327
set_parsing_settings(urls_enabled=True)
328

329
parser = ArgumentParser()
330
parser.add_argument("--config", action="config_file")
331
parser.add_argument("--name", type=str)
332
parser.add_argument("--version", type=str)
333

334
# Can now load configuration from URLs
335
config = parser.parse_args()
336

337
print(f"Loaded config: {config.name} v{config.version}")
338
```
339

340
Usage:
341
```bash
342
# Load config from URL
343
python script.py --config https://example.com/config.yaml
344

345
# Load config from local file
346
python script.py --config file:///path/to/config.json
347
```
348

349
### Multiple Format Support
350

351
```python
352
from jsonargparse import set_loader, set_dumper, ArgumentParser
353
import xml.etree.ElementTree as ET
354
import json
355

356
# Add XML support
357
def load_xml(xml_string: str) -> dict:
358
    """Simple XML to dict loader."""
359
    root = ET.fromstring(xml_string)
360
    
361
    def element_to_dict(element):
362
        result = {}
363
        for child in element:
364
            if len(child) == 0:
365
                result[child.tag] = child.text
366
            else:
367
                result[child.tag] = element_to_dict(child)
368
        return result
369
    
370
    return {root.tag: element_to_dict(root)}
371

372
def dump_xml(data: dict) -> str:
373
    """Simple dict to XML dumper."""
374
    def dict_to_element(name, value):
375
        elem = ET.Element(name)
376
        if isinstance(value, dict):
377
            for k, v in value.items():
378
                elem.append(dict_to_element(k, v))
379
        else:
380
            elem.text = str(value)
381
        return elem
382
    
383
    root_name = list(data.keys())[0]
384
    root = dict_to_element(root_name, data[root_name])
385
    return ET.tostring(root, encoding='unicode')
386

387
# Register XML format
388
set_loader("xml", load_xml)
389
set_dumper("xml", dump_xml)
390

391
parser = ArgumentParser()
392
parser.add_argument("--config", action="config_file")
393
parser.add_argument("--name", type=str)
394
parser.add_argument("--database.host", type=str)
395
parser.add_argument("--database.port", type=int)
396

397
config = parser.parse_args()
398

399
# Save in different formats
400
parser.save(config, "config.json", format="json")
401
parser.save(config, "config.yaml", format="yaml") 
402
parser.save(config, "config.xml", format="xml")
403

404
print(f"Configuration saved in multiple formats")
405
```
406

407
### Debugging Configuration Loading
408

409
```python
410
from jsonargparse import get_loader, ArgumentParser
411
import logging
412

413
# Setup debug logging
414
logging.basicConfig(level=logging.DEBUG)
415

416
# Check available loaders
417
for format_name in ["json", "yaml", "toml"]:
418
    try:
419
        loader = get_loader(format_name)
420
        print(f"{format_name}: {loader.__name__}")
421
    except ValueError:
422
        print(f"{format_name}: not available")
423

424
parser = ArgumentParser()
425
parser.add_argument("--config", action="config_file")
426
parser.add_argument("--debug", action="store_true")
427

428
config = parser.parse_args()
429

430
if config.debug:
431
    print("Debug mode enabled")
432
    # Additional debug output here
433
```
434

435
## Available Settings
436

437
### Parsing Settings Options
438

439
- `validation`: Boolean to enable/disable strict argument validation
440
- `docstring_parser`: String specifying docstring format ("google", "sphinx", "numpy", or False)
441
- `parse_as_dict`: Boolean to control whether configs are parsed as dicts or objects
442
- `urls_enabled`: Boolean to enable loading configuration files from URLs
443
- `fsspec_enabled`: Boolean to enable fsspec filesystem support for remote files
444

445
### Supported File Formats
446

447
Built-in support for:
448
- **JSON**: `.json` files
449
- **YAML**: `.yaml`, `.yml` files (requires PyYAML)
450
- **TOML**: `.toml` files (requires toml or tomli)
451
- **Jsonnet**: `.jsonnet` files (requires jsonnet)
452

453
Custom formats can be added using `set_loader()` and `set_dumper()`.
454

455
### Docstring Parser Options
456

457
- `"google"`: Google-style docstrings
458
- `"sphinx"`: Sphinx/reStructuredText style
459
- `"numpy"`: NumPy/SciPy style  
460
- `False`: Disable docstring parsing