A small utility for simplifying and cleaning up argument parsing scripts.
simple-parsing
allows you to transform your ugly argparse
scripts into beautifully structured, strongly typed little works of art. This isn't a fancy, complicated new command-line tool either, this simply adds new features to plain-old argparse!
Using dataclasses, simple-parsing
makes it easier to share and reuse command-line arguments - no more copy pasting!
Supports inheritance, nesting, easy serialization to json/yaml, automatic help strings from comments, and much more!
# examples/demo.py
from dataclasses import dataclass
from simple_parsing import ArgumentParser
parser = ArgumentParser()
parser.add_argument("--foo", type=int, default=123, help="foo help")
@dataclass
class Options:
""" Help string for this group of command-line arguments """
log_dir: str # Help string for a required str argument
learning_rate: float = 1e-4 # Help string for a float argument
parser.add_arguments(Options, dest="options")
args = parser.parse_args()
print("foo:", args.foo)
print("options:", args.options)
$ python examples/demo.py --log_dir logs --foo 123
foo: 123
options: Options(log_dir='logs', learning_rate=0.0001)
$ python examples/demo.py --help
usage: demo.py [-h] [--foo int] --log_dir str [--learning_rate float]
optional arguments:
-h, --help show this help message and exit
--foo int foo help (default: 123)
Options ['options']:
Help string for this group of command-line arguments
--log_dir str Help string for a required str argument (default:
None)
--learning_rate float
Help string for a float argument (default: 0.0001)
For a simple use-case, where you only want to parse a single dataclass, you can use the simple_parsing.parse
or simple_parsing.parse_known_args
functions:
options: Options = simple_parsing.parse(Options)
# or:
options, leftover_args = simple_parsing.parse_known_args(Options)
pip install simple-parsing
As developers, we want to make it easy for people coming into our projects to understand how to run them. However, a user-friendly --help
message is often hard to write and to maintain, especially as the number of arguments increases.
With simple-parsing
, your arguments and their descriptions are defined in the same place, making your code easier to read, write, and maintain.
(no more copy-pasting)
When you need to add a new group of command-line arguments similar to an existing one, instead of copy-pasting a block of argparse
code and renaming variables, you can reuse your argument class, and let the ArgumentParser
take care of adding relevant prefixes to the arguments for you:
parser.add_arguments(Options, dest="train")
parser.add_arguments(Options, dest="valid")
args = parser.parse_args()
train_options: Options = args.train
valid_options: Options = args.valid
print(train_options)
print(valid_options)
$ python examples/demo.py \
--train.log_dir "training" \
--valid.log_dir "validation"
Options(log_dir='training', learning_rate=0.0001)
Options(log_dir='validation', learning_rate=0.0001)
These prefixes can also be set explicitly, or not be used at all. For more info, take a look at the Prefixing Guide
It's easy to choose between different argument groups of arguments, with the subgroups
function!
Default values for command-line arguments can easily be read from many different formats, including json/yaml!
Easily save/load configs to json
or yaml
!.
You can easily customize an existing argument class by extending it and adding your own attributes, which helps promote code reuse across projects. For more info, take a look at the inheritance example
Dataclasses can be nested within dataclasses, as deep as you need!
This is sometimes tricky to do with regular argparse
, but simple-parsing
makes it a lot easier by using the python's builtin type annotations to automatically convert the values to the right type for you.
As an added feature, by using these type annotations, simple-parsing
allows you to parse nested lists or tuples, as can be seen in this example
(More to come!)
Additional examples for all the features mentioned above can be found in the examples folder