tessl/pypi-jsonargparse
Implement minimal boilerplate CLIs derived from type hints and parse from command line, config files and environment variables.
—
Pending
core-parser.mddocs/
Core Parser Functionality
The ArgumentParser class serves as the foundation of jsonargparse, extending Python's argparse.ArgumentParser with support for configuration files, environment variables, advanced type handling, and nested configurations. It provides the core parsing and validation capabilities that power all other jsonargparse features.
Capabilities
ArgumentParser Class
The main parser class that handles argument parsing from multiple sources including command line, configuration files, and environment variables.
class ArgumentParser:
def __init__(self,
prog: Optional[str] = None,
usage: Optional[str] = None,
description: Optional[str] = None,
epilog: Optional[str] = None,
formatter_class: Type = DefaultHelpFormatter,
prefix_chars: str = "-",
fromfile_prefix_chars: Optional[str] = None,
argument_default: Any = None,
conflict_handler: str = "error",
add_help: bool = True,
allow_abbrev: bool = True,
exit_on_error: bool = True,
env_prefix: Union[bool, str] = True,
logger: Union[bool, str, dict, logging.Logger] = False,
version: Optional[str] = None,
print_config: Optional[str] = "--print_config",
parser_mode: str = "yaml",
dump_header: Optional[List[str]] = None,
default_config_files: Optional[List[Union[str, os.PathLike]]] = None,
default_env: bool = False,
default_meta: bool = True,
**kwargs
):
"""
Create a new argument parser.
Args:
env_prefix: Prefix for environment variables (True for prog name)
logger: Logger configuration for the parser
version: Version string to display with --version
print_config: Option name for printing current config
parser_mode: Default parsing mode ('yaml', 'json', etc.)
default_config_files: List of default config file paths
default_env: Whether to parse environment variables by default
default_meta: Whether to include metadata in parsed configs
"""Parsing Methods
Core methods for parsing arguments from different sources with comprehensive configuration merging.
def parse_args(self, args: Optional[List[str]] = None, namespace: Optional[Namespace] = None) -> Namespace:
"""
Parse command line arguments, config files, and environment variables.
Args:
args: List of arguments to parse (defaults to sys.argv)
namespace: Namespace object to populate
Returns:
Namespace: Parsed configuration namespace
"""
def parse_object(self, cfg_obj: Any, cfg_path: str = "") -> Namespace:
"""
Parse configuration from a nested object (dict, namespace, etc.).
Args:
cfg_obj: Configuration object to parse
cfg_path: Path identifier for error messages
Returns:
Namespace: Parsed configuration namespace
"""
def parse_path(self, cfg_path: Union[str, os.PathLike], ext_vars: Optional[Dict[str, str]] = None) -> Namespace:
"""
Parse configuration from a file path.
Args:
cfg_path: Path to configuration file
ext_vars: External variables for jsonnet files
Returns:
Namespace: Parsed configuration namespace
"""
def parse_string(self, cfg_str: str, cfg_path: str = "", ext_vars: Optional[Dict[str, str]] = None) -> Namespace:
"""
Parse configuration from a string.
Args:
cfg_str: Configuration string to parse
cfg_path: Path identifier for error messages
ext_vars: External variables for jsonnet strings
Returns:
Namespace: Parsed configuration namespace
"""
def parse_env(self, env: Optional[Dict[str, str]] = None, defaults: bool = True) -> Namespace:
"""
Parse configuration from environment variables.
Args:
env: Environment variables dict (defaults to os.environ)
defaults: Whether to include default values
Returns:
Namespace: Parsed configuration namespace
"""Configuration Output Methods
Methods for serializing and saving parsed configurations in various formats.
def dump(self, cfg: Optional[Namespace] = None, format: Optional[str] = None, **kwargs) -> str:
"""
Generate configuration string from namespace.
Args:
cfg: Configuration namespace to dump
format: Output format ('yaml', 'json', etc.)
Returns:
str: Serialized configuration string
"""
def save(self, cfg: Namespace, path: Union[str, os.PathLike], format: Optional[str] = None, **kwargs) -> None:
"""
Save configuration to file.
Args:
cfg: Configuration namespace to save
path: Output file path
format: Output format (inferred from extension if not provided)
"""Configuration Management
Methods for handling default values, merging configurations, and managing parser state.
def get_defaults(self) -> Namespace:
"""
Get default values for all arguments.
Returns:
Namespace: Default configuration values
"""
def set_defaults(self, **kwargs) -> None:
"""
Set default values for arguments.
Args:
**kwargs: Argument names and their default values
"""
def merge_config(self, cfg_from: Namespace, cfg_to: Namespace) -> Namespace:
"""
Merge two configuration namespaces.
Args:
cfg_from: Source configuration namespace
cfg_to: Target configuration namespace
Returns:
Namespace: Merged configuration namespace
"""Validation and Processing
Methods for validating configurations and processing parsed values.
def validate(self, cfg: Namespace) -> Namespace:
"""
Validate a configuration namespace.
Args:
cfg: Configuration namespace to validate
Returns:
Namespace: Validated configuration namespace
Raises:
ArgumentError: If validation fails
"""
def instantiate_classes(self, cfg: Namespace) -> Namespace:
"""
Instantiate classes from configuration.
Args:
cfg: Configuration namespace with class specifications
Returns:
Namespace: Configuration with instantiated classes
"""
def strip_unknown(self, cfg: Namespace) -> Namespace:
"""
Remove unknown keys from configuration.
Args:
cfg: Configuration namespace to process
Returns:
Namespace: Configuration with unknown keys removed
"""
def add_subcommands(self, **kwargs) -> None:
"""
Add subcommands to the parser.
Args:
**kwargs: Subcommand configuration options including:
dest: Destination attribute name for selected subcommand
help: Help text for subcommands
parser_class: Parser class to use for subcommands
"""ActionsContainer
Base container class that provides argument management functionality used by ArgumentParser.
class ActionsContainer:
def add_argument(self, *args, **kwargs) -> Action:
"""
Add an argument to the parser.
Args:
*args: Positional argument names or flags
**kwargs: Argument configuration options
Returns:
Action: The created argument action
"""
def add_argument_group(self, title: Optional[str] = None, description: Optional[str] = None) -> ArgumentGroup:
"""
Create a new argument group.
Args:
title: Group title
description: Group description
Returns:
ArgumentGroup: New argument group
"""Usage Examples
Basic Parser Setup
from jsonargparse import ArgumentParser
# Create parser with environment support
parser = ArgumentParser(
prog="myapp",
description="My application",
env_prefix="MYAPP_", # Environment variables like MYAPP_NAME
default_config_files=["~/.myapp.yaml", "./config.yaml"]
)
# Add arguments
parser.add_argument("--name", type=str, required=True)
parser.add_argument("--age", type=int, default=30)
parser.add_argument("--verbose", action="store_true")Multi-Source Parsing
# Parse from multiple sources with precedence:
# 1. Command line arguments (highest priority)
# 2. Configuration files
# 3. Environment variables
# 4. Default values (lowest priority)
config = parser.parse_args()
# Access parsed values
print(f"Name: {config.name}")
print(f"Age: {config.age}")
print(f"Verbose: {config.verbose}")Configuration File Handling
# Save current configuration
parser.save(config, "current_config.yaml")
# Load configuration from file
file_config = parser.parse_path("config.yaml")
# Parse configuration string
yaml_str = "name: Alice\nage: 25\nverbose: true"
string_config = parser.parse_string(yaml_str)Validation and Processing
# Validate configuration
validated_config = parser.validate(config)
# Merge configurations
merged_config = parser.merge_config(default_config, user_config)
# Generate configuration output
yaml_output = parser.dump(config, format="yaml")
json_output = parser.dump(config, format="json")Install with Tessl CLI
npx tessl i tessl/pypi-jsonargparse@4.41.1