Simple, Elegant, Typed Argument Parsing

simple-parsingallows you to transform your uglyargparsescripts 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! Usingdataclasses,simple-parsingmakes 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
fromdataclassesimportdataclass
fromsimple_parsingimportArgumentParser

parser=ArgumentParser()
parser.add_argument("--foo",type=int,default=123,help="foo help")

@dataclass
classOptions:
"""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)

(new) Simplified API:

For a simple use-case, where you only want to parse a single dataclass, you can use thesimple_parsing.parseorsimple_parsing.parse_known_argsfunctions:

options:Options=simple_parsing.parse(Options)
# or:
options,leftover_args=simple_parsing.parse_known_args(Options)

installation

pip install simple-parsing

Examples

API Documentation(Under construction)

Features

• Automatic "--help" strings

  As developers, we want to make it easy for people coming into our projects to understand how to run them. However, a user-friendly--helpmessage is often hard to write and to maintain, especially as the number of arguments increases.

  Withsimple-parsing,your arguments and their descriptions are defined in the same place, making your code easier to read, write, and maintain.

• Modular, Reusable, Cleanly Grouped Arguments

  (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 ofargparsecode and renaming variables, you can reuse your argument class, and let theArgumentParsertake 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 thePrefi xing Guide

• Argument subgroups

  It's easy to choose between different argument groups of arguments, with thesubgroups function!

• Setting defaults from Configuration files

  Default values for command-line arguments can easily be read from many different formats, including json/yaml!

• Easy serialization:

  Easily save/load configs tojsonoryaml!.

• Inheritance!

  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 theinheritance example

• Nesting!:

  Dataclasses can be nested within dataclasses, as deep as you need!

• Easier parsing of lists and tuples:

  This is sometimes tricky to do with regularargparse,butsimple-parsingmakes 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-parsingallows you to parse nested lists or tuples, as can be seen inthis example

• Enums support

• (More to come!)

Examples:

Additional examples for all the features mentioned above can be found in theexamples folder