tessl/pypi-jsonargparse

Implement minimal boilerplate CLIs derived from type hints and parse from command line, config files and environment variables.

—

Pending

Overview

Eval results

Files

Settings

Name: tessl/pypi-jsonargparse
Author: tessl

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.

Capabilities

Parsing Settings

Global configuration function for customizing parsing behavior across all parsers.

def set_parsing_settings(
    validation: Optional[bool] = None,
    docstring_parser: Optional[Union[str, bool]] = None,
    parse_as_dict: Optional[bool] = None,
    urls_enabled: Optional[bool] = None,
    fsspec_enabled: Optional[bool] = None,
    **kwargs
) -> None:
    """
    Set global parsing settings that affect all ArgumentParser instances.
    
    Args:
        validation: Enable/disable argument validation
        docstring_parser: Docstring parser to use ('google', 'sphinx', 'numpy', or False)
        parse_as_dict: Whether to parse config files as dictionaries instead of objects
        urls_enabled: Enable/disable URL support for configuration files
        fsspec_enabled: Enable/disable fsspec filesystem support
        **kwargs: Additional parsing settings
    """

File Format Loaders

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

def set_loader(format_name: str, loader: Callable[[str], Any]) -> None:
    """
    Set custom loader function for a file format.
    
    Args:
        format_name: Name of the format (e.g., 'yaml', 'json', 'toml')
        loader: Function that takes a string and returns parsed data
    """

def get_loader(format_name: str) -> Callable[[str], Any]:
    """
    Get the current loader function for a file format.
    
    Args:
        format_name: Name of the format to get loader for
        
    Returns:
        Callable[[str], Any]: Current loader function for the format
        
    Raises:
        ValueError: If format is not supported
    """

File Format Dumpers

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

def set_dumper(format_name: str, dumper: Callable[[Any], str]) -> None:
    """
    Set custom dumper function for a file format.
    
    Args:
        format_name: Name of the format (e.g., 'yaml', 'json', 'toml')
        dumper: Function that takes data and returns a string
    """

def get_dumper(format_name: str) -> Callable[[Any], str]:
    """
    Get the current dumper function for a file format.
    
    Args:
        format_name: Name of the format to get dumper for
        
    Returns:
        Callable[[Any], str]: Current dumper function for the format
        
    Raises:
        ValueError: If format is not supported
    """

Configuration Reading

Functions for controlling how configuration files are read and processed.

def _get_config_read_mode() -> str:
    """
    Get the current configuration reading mode.
    
    Returns:
        str: Current config reading mode ('fr', 'fc', etc.)
    """

Usage Examples

Customizing Parsing Behavior

from jsonargparse import set_parsing_settings, ArgumentParser

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

def train_model(
    data_path: str,
    epochs: int = 100,
    learning_rate: float = 0.001
) -> None:
    """
    Train a machine learning model.
    
    Args:
        data_path: Path to training data directory
        epochs: Number of training epochs
        learning_rate: Learning rate for optimizer
    """
    print(f"Training with {epochs} epochs at lr={learning_rate}")

parser = ArgumentParser()
parser.add_function_arguments(train_model)

# Parser will use the global settings configured above
config = parser.parse_args()
train_model(**config.as_dict())

Custom File Format Loaders

from jsonargparse import set_loader, get_loader, ArgumentParser
import configparser
import json

# Define custom INI file loader
def load_ini(ini_string: str) -> dict:
    """Load INI format configuration."""
    config = configparser.ConfigParser()
    config.read_string(ini_string)
    
    # Convert to nested dictionary
    result = {}
    for section_name in config.sections():
        result[section_name] = dict(config[section_name])
    
    return result

# Register custom loader
set_loader("ini", load_ini)

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

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

print(f"Name: {config.name}")
print(f"DB Host: {config.database.host}")
print(f"DB Port: {config.database.port}")

With INI config file config.ini:

[DEFAULT]
name = MyApp

[database]
host = localhost
port = 5432

Usage:

python script.py --config config.ini

Custom File Format Dumpers

from jsonargparse import set_dumper, ArgumentParser
import configparser
from io import StringIO

# Define custom INI dumper
def dump_ini(data: dict) -> str:
    """Dump data to INI format."""
    config = configparser.ConfigParser()
    
    # Handle nested dictionaries
    for key, value in data.items():
        if isinstance(value, dict):
            config[key] = value
        else:
            if 'DEFAULT' not in config:
                config['DEFAULT'] = {}
            config['DEFAULT'][key] = str(value)
    
    # Write to string
    output = StringIO()
    config.write(output)
    return output.getvalue()

# Register custom dumper
set_dumper("ini", dump_ini)

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

config = parser.parse_args()

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

# Or get as string
ini_string = parser.dump(config, format="ini")
print(ini_string)

Advanced Docstring Parsing

from jsonargparse import set_parsing_settings, ArgumentParser

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

def process_data(
    input_file: str,
    output_file: str,
    batch_size: int = 32,
    normalize: bool = True
) -> None:
    """
    Process data files with optional normalization.
    
    This function reads data from the input file, processes it in batches,
    and writes the results to the output file.
    
    Args:
        input_file: Path to the input data file. Must be readable.
        output_file: Path where processed data will be written.
        batch_size: Number of items to process in each batch. Must be positive.
        normalize: Whether to normalize the data values to [0, 1] range.
        
    Returns:
        None: Results are written to the output file.
        
    Raises:
        FileNotFoundError: If input file doesn't exist.
        PermissionError: If output file cannot be written.
    """
    print(f"Processing {input_file} -> {output_file}")
    print(f"Batch size: {batch_size}, Normalize: {normalize}")

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

# Help text will include detailed descriptions from docstring
config = parser.parse_args()

Custom Configuration Validation

from jsonargparse import set_parsing_settings, ArgumentParser
import logging

# Enable strict validation
set_parsing_settings(validation=True)

class ValidatedConfig:
    def __init__(self, 
                 name: str,
                 port: int,
                 debug: bool = False):
        # Custom validation
        if not name or len(name) < 3:
            raise ValueError("Name must be at least 3 characters")
        if not (1024 <= port <= 65535):
            raise ValueError("Port must be between 1024 and 65535")
            
        self.name = name
        self.port = port
        self.debug = debug
        
        if debug:
            logging.basicConfig(level=logging.DEBUG)

parser = ArgumentParser()
parser.add_class_arguments(ValidatedConfig, "config")

try:
    config = parser.parse_args()
    app_config = ValidatedConfig(**config.config.as_dict())
    print(f"Valid config: {app_config.name}:{app_config.port}")
except ValueError as e:
    print(f"Configuration validation failed: {e}")

URL Configuration Support

from jsonargparse import set_parsing_settings, ArgumentParser

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

parser = ArgumentParser()
parser.add_argument("--config", action="config_file")
parser.add_argument("--name", type=str)
parser.add_argument("--version", type=str)

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

print(f"Loaded config: {config.name} v{config.version}")

Usage:

# Load config from URL
python script.py --config https://example.com/config.yaml

# Load config from local file
python script.py --config file:///path/to/config.json

Multiple Format Support

from jsonargparse import set_loader, set_dumper, ArgumentParser
import xml.etree.ElementTree as ET
import json

# Add XML support
def load_xml(xml_string: str) -> dict:
    """Simple XML to dict loader."""
    root = ET.fromstring(xml_string)
    
    def element_to_dict(element):
        result = {}
        for child in element:
            if len(child) == 0:
                result[child.tag] = child.text
            else:
                result[child.tag] = element_to_dict(child)
        return result
    
    return {root.tag: element_to_dict(root)}

def dump_xml(data: dict) -> str:
    """Simple dict to XML dumper."""
    def dict_to_element(name, value):
        elem = ET.Element(name)
        if isinstance(value, dict):
            for k, v in value.items():
                elem.append(dict_to_element(k, v))
        else:
            elem.text = str(value)
        return elem
    
    root_name = list(data.keys())[0]
    root = dict_to_element(root_name, data[root_name])
    return ET.tostring(root, encoding='unicode')

# Register XML format
set_loader("xml", load_xml)
set_dumper("xml", dump_xml)

parser = ArgumentParser()
parser.add_argument("--config", action="config_file")
parser.add_argument("--name", type=str)
parser.add_argument("--database.host", type=str)
parser.add_argument("--database.port", type=int)

config = parser.parse_args()

# Save in different formats
parser.save(config, "config.json", format="json")
parser.save(config, "config.yaml", format="yaml") 
parser.save(config, "config.xml", format="xml")

print(f"Configuration saved in multiple formats")

Debugging Configuration Loading

from jsonargparse import get_loader, ArgumentParser
import logging

# Setup debug logging
logging.basicConfig(level=logging.DEBUG)

# Check available loaders
for format_name in ["json", "yaml", "toml"]:
    try:
        loader = get_loader(format_name)
        print(f"{format_name}: {loader.__name__}")
    except ValueError:
        print(f"{format_name}: not available")

parser = ArgumentParser()
parser.add_argument("--config", action="config_file")
parser.add_argument("--debug", action="store_true")

config = parser.parse_args()

if config.debug:
    print("Debug mode enabled")
    # Additional debug output here

Available Settings

Parsing Settings Options

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