Skip to main content

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

Project description

Build Status PyPI version

Simple, Elegant, Typed Argument Parsing

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)

(new) Simplified API:

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)

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 --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.

  • 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 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

  • Argument subgroups

    It's easy to choose between different argument groups of arguments, with the subgroups 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 to json or yaml!.

  • 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 the inheritance 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 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

  • Enums support

  • (More to come!)

Examples:

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

Project details


Release history Release notifications | RSS feed

Download files

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

Source Distribution

simple_parsing-0.1.7.tar.gz (96.4 kB view details)

Uploaded Source

Built Distribution

simple_parsing-0.1.7-py3-none-any.whl (112.8 kB view details)

Uploaded Python 3

File details

Details for the file simple_parsing-0.1.7.tar.gz.

File metadata

  • Download URL: simple_parsing-0.1.7.tar.gz
  • Upload date:
  • Size: 96.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.0.1 CPython/3.12.3 Linux/6.8.0-1017-azure

File hashes

Hashes for simple_parsing-0.1.7.tar.gz
Algorithm Hash digest
SHA256 225e6b35252d68f7894716101fe3bd7e6dd3d30ab7b1c3c023f77a42dbe1336f
MD5 41ac52c0222a078c8a87d051649872bb
BLAKE2b-256 ebc5f1e2fcb3a81085cdf3cfed48b8c8ce0e7cc30c95dee734cbb35d6265336a

See more details on using hashes here.

File details

Details for the file simple_parsing-0.1.7-py3-none-any.whl.

File metadata

  • Download URL: simple_parsing-0.1.7-py3-none-any.whl
  • Upload date:
  • Size: 112.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.0.1 CPython/3.12.3 Linux/6.8.0-1017-azure

File hashes

Hashes for simple_parsing-0.1.7-py3-none-any.whl
Algorithm Hash digest
SHA256 5276e6c90c157362dd0173d1eecebe58361a66b457129cc9bba13b78a4e85092
MD5 f96044659f49b03dd35a9117000aa21a
BLAKE2b-256 4f9ce9ea38750027a6de3e3c5e68a19fda0e7b0cd3db8045f30d0f6bc113b911

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page