Simple-Parsing: Elegant Argument Parsing with Dataclasses

0.1.8 · active · verified Thu Apr 09

Simple-parsing is a Python utility that significantly simplifies and cleans up argument parsing scripts by extending `argparse` with `dataclasses`. It allows developers to define command-line arguments in a structured, strongly typed, and object-oriented manner. Key features include support for inheritance, nesting of argument groups, easy serialization to JSON/YAML, and automatic generation of help strings from docstrings and comments. The library is currently at version 0.1.8 and maintains an active release cadence, with updates typically occurring every few months.

Warnings

breaking Version 0.1.8 drops support for Python 3.8. Users on Python 3.8 or older must upgrade their Python environment to 3.9+ or use an older version of `simple-parsing`.
Fix: Upgrade Python to 3.9 or newer, or pin `simple-parsing<0.1.8`.
gotcha When using `ArgumentParser`, ensure you import `simple_parsing.ArgumentParser` and not `argparse.ArgumentParser`. Only the `simple_parsing` version provides methods like `add_arguments` for dataclass integration.
Fix: Change `from argparse import ArgumentParser` to `from simple_parsing import ArgumentParser`.
deprecated Older versions of simple-parsing (e.g., <0.0.3) used `ParseableFromCommandLine` as a base class for dataclasses. While it might still function, the recommended API for grouping arguments with dataclasses is `parser.add_arguments(YourDataclass, dest="your_dest")` or using the `simple_parsing.parse` function for single dataclass parsing.
Fix: Refactor dataclasses to not inherit from `ParseableFromCommandLine` and use `parser.add_arguments()` or `simple_parsing.parse()` instead.
gotcha When using `parser.add_arguments(Dataclass, dest="attribute_name")`, the `dest` argument is crucial. It specifies the attribute name on the parsed arguments object where the dataclass instance will be stored. Omitting it or using a conflicting `dest` can lead to unexpected argument flattening or overwrites.
Fix: Always explicitly define a unique `dest` for each dataclass added via `add_arguments` to ensure proper grouping and access to the parsed dataclass instance (e.g., `args.attribute_name`).

Install

pip install simple-parsing Install stable version

Imports

ArgumentParser
```
from simple_parsing import ArgumentParser
```
simple-parsing's ArgumentParser is a subclass of argparse.ArgumentParser, providing additional functionality like `add_arguments` for dataclasses.
parse
```
from simple_parsing import parse
```
This provides a simplified API for directly parsing a single dataclass without explicit ArgumentParser instantiation.

Quickstart

This quickstart demonstrates two common ways to use `simple-parsing`: using the `ArgumentParser` for more complex scenarios involving multiple argument groups or standalone arguments, and using the simplified `parse` function for directly obtaining an instance of a single dataclass from command-line arguments. It showcases how dataclasses define arguments and how they are populated.

from dataclasses import dataclass
from simple_parsing import ArgumentParser, parse
import os

@dataclass
class CommonOptions:
    """Common options for a script."""
    seed: int = 42
    log_level: str = "INFO"

@dataclass
class TrainingOptions:
    """Options specific to training."""
    learning_rate: float = 1e-4
    epochs: int = 10
    output_dir: str = os.environ.get('OUTPUT_PATH', './outputs')

# Method 1: Using ArgumentParser (for multiple dataclasses or custom args)
parser = ArgumentParser()
parser.add_arguments(CommonOptions, dest="common")
parser.add_arguments(TrainingOptions, dest="train")

args_parser = parser.parse_args(['--seed', '100', '--learning_rate', '0.01'])
print(f"Parsed with ArgumentParser: Common: {args_parser.common}, Train: {args_parser.train}")

# Method 2: Simplified API (for single dataclass parsing)
args_simplified = parse(TrainingOptions, args=['--epochs', '20'])
print(f"Parsed with simplified API: {args_simplified}")

view raw JSON →