Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

A small utility for simplifying and cleaning up argument parsing scripts.

Project description

Build Status

Simple, Elegant Argument Parsing

Do you ever find youself stuck with an endless list of command-line arguments, say, when specifying all the hyper-parameters of your ML model? Well, say no more, here's something to make your life just a little bit easier!

simple-parsing uses python 3.7's amazing dataclasses to allow you to define your arguments in a simple, elegant, and object-oriented way. When applied to a dataclass, the ParseableFromCommandLine base-class enables creating instances of that class automatically from the provided command-line arguments.

Documentation: SimpleParse Wiki


python version >= 3.7:

pip install simple-parsing

python version == 3.6.X:

pip install dataclasses simple-parsing

Basic Usage:

Instead of adding your command-line arguments with parser.add_argument(...), you can instead define your arguments directly in code! Simply create a dataclass to hold your arguments, adding ParseableFromCommandLine as a base class:

"""A basic example of how to use simple-parsing."""
import argparse
from dataclasses import dataclass, field
from typing import List

from simple_parsing import Formatter, ParseableFromCommandLine

parser = argparse.ArgumentParser(formatter_class=Formatter)

class Options(ParseableFromCommandLine):
	""" A class which groups related parameters. """

	some_int: int			# Some required int parameter
	some_float: float = 1.23	# An optional float parameter

	name: str = "default"   	# The name of some important experiment

	log_dir: str = "/logs" 		# an optional string parameter
	flag: bool = False 		# Wether or not we do something

	# This is a list of integers (empty by default)
	some_integers: List[int] = field(default_factory=list)

	# Converting the list items to the right type will be taken care of for you!
	some_floats: List[float] = field(default_factory=list)

# add the arguments

# parse the arguments from stdin
args = parser.parse_args()

# create an instance of Options with the arguments
options = Options.from_args(args)

# Do whatever you want using the Options object here!

Executing the script:

This script is called just like any other argparse script, and the values are stored inside the object:

$ python ./examples/ --some_int 123 --flag true --some_integers 23 45 67
Options(some_int=123, some_float=1.23, name='default', log_dir='/logs', flag=True, some_integers=[23, 45, 67], some_floats=[])

However, we get a lot of nice information for free! For instance, passing the "--help" option displays relevant information for each argument:

$ python ./ --help
usage: [-h] --some_int int [--some_float float] [--name str]
                        [--log_dir str] [--flag [str2bool]]
                        [--some_integers [int [int ...]]]
                        [--some_floats [float [float ...]]]

optional arguments:
  -h, --help            show this help message and exit

  A class which groups related parameters.

  --some_int int        Some required int parameter (default: None)
  --some_float float    An optional float parameter (default: 1.23)
  --name str            The name of some important experiment (default:
  --log_dir str         an optional string parameter (default: /logs)
  --flag [str2bool]     Wether or not we do something (default: False)
  --some_integers [int [int ...]]
                        This is a list of integers (empty by default)
                        (default: [])
  --some_floats [float [float ...]]
                        Converting the list items to the right type will be
                        taken care of for you! (default: [])

Easily convert to/from a dictionary:

# convert the dataclass to a dict
options_dict = options.asdict()

# create an instance from a dict
options_ = Options(**options_dict)
assert options == options_

You can then use whichever library you like (yaml, json, etc.) and save the dict to a file:

import json
with open( + ".json", "w") as f:
	json.dump(options_dict, f, indent=1)
$ cat default.json
 "some_int": 123,
 "some_float": 1.23,
 "name": "default",
 "log_dir": "/logs",
 "flag": true,
 "some_integers": [
 "some_floats": []

Loading from a dictionary or JSON file:

with open("default.json") as f:
	params = json.load(f)
	default_options = Options(**params)
	assert options == default_options

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for simple-parsing, version 0.0.2
Filename, size File type Python version Upload date Hashes
Filename, size simple_parsing-0.0.2-py3-none-any.whl (11.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size simple_parsing-0.0.2.tar.gz (15.4 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page