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

A minimal library to make your option-parsing easier.

Project description

Lethargy - Option parsing, for simple apps

Released version Python versions MIT License Size

Lethargy takes care of option parsing in your scripts, so you can be more productive when writing the important stuff. It's simple, concise, explicit, and Pythonic.

Unlike Click and Argparse, Lethargy is succinct, can be implemented without changing the structure of a program, and requires no boilerplate code. This makes it especially suited to scripting and prototyping.

By design, it is not a full argument parser. If you're building a complete CLI application, you're probably better off using Click.


Lethargy only depends on the standard library. You can use pip to install lethargy.

pip install lethargy


from lethargy import Opt, argv

# --use-headers
headers = Opt("use headers").take_flag(argv)

# -f|--file <value>
output_file = Opt("f", "file").takes(1).take_args(argv)

Lethargy returns values appropriate to the option, safely mutating the list.

Getting Started

The default argv

To save you an additional import, lethargy provides lethargy.argv - a clone of the original argument list. Mutating it will not affect sys.argv.


Options will automatically convert their names to the appropriate format (-o or --option). Casing will be preserved.

>>> from lethargy import Opt
>>> args = ["-", "--debug", "file.txt"]
>>> Opt("debug").take_flag(args)
>>> args
['-', 'file.txt']

To take arguments, use the Opt.takes method.

>>> args = ["-", "--height", "185cm", "people.csv"]
>>> Opt("height").takes(1).take_args(args)
>>> args
['-', 'people.csv']

Taking 1 argument will return a single value. Taking multiple will return a list (see the Argument unpacking section for details).

You can also use a "greedy" value, to take every remaining argument. The canonical way to do this is using the Ellipsis literal (...).

>>> args = ["--exclude", ".zshrc", ".bashrc"]
>>> Opt("exclude").takes(...).take_args(args)
['.zshrc', '.bashrc']

Argument unpacking

lethargy.Opt makes sure it's safe to unpack a returned list of values, unless you override the default parameter.

>>> Opt("x").takes(2).take_args(["-x", "1", "2"])
['1', '2']
>>> Opt("y").takes(2).take_args([])
[None, None]

If there are fewer arguments than expected, lethargy.ArgsError will be raised and no mutation will occur. Lethargy has clear and readable error messages.

>>> args = ["-z", "bad"]
>>> Opt("z").takes(2).take_args(args)
Traceback (most recent call last):
lethargy.ArgsError: expected 2 arguments for '-z <value> <value>', found 1 ('bad')
>>> args
['-z', 'bad']

--debug and -v/--verbose

As these are such common options, lethargy includes functions out of the box to take these options.

>>> import lethargy
>>> args = ["-", "--debug", "--verbose", "sheet.csv"]
>>> lethargy.take_verbose(args)  # -v or --verbose
>>> lethargy.take_debug(args)
>>> args
['-', 'sheet.csv']

By convention, passing --verbose will cause a program to output more information. To make implementing this behaviour easier, lethargy has the print_if function, which will return print if its input is true and a dummy function if not.

from lethargy import take_verbose, print_if, argv

debug_print = print_if(take_verbose(argv))

debug_print("This will only print if `--debug` was passed to the script!")

Using str and repr

Opt instances provide a logical and consistent string form.

>>> str(Opt("flag"))
>>> str(Opt("e", "example").takes(1))
'-e|--example <value>'
>>> str(Opt("xyz").takes(...))
'--xyz [value]...'

The repr form makes debugging easy. Note that the order of the names is not guaranteed.

>>> Opt("f", "flag")
<Opt('f', 'flag') at 0x106d73f70>
>>> Opt("example").takes(2)
<Opt('example').takes(2) at 0x106ce35e0>
>>> Opt("test").takes(1, int)
<Opt('test').takes(1, int) at 0x106d73f70>
>>> Opt("x").takes(..., lambda s: s.split())
<Opt('x').takes(Ellipsis, <function <lambda> at 0x106ddd9d0>) at 0x106ec0a30>

Raising instead of defaulting

If Opt.take_args is called with raises=True, lethargy.MissingOption will be raised instead of returning a default, even if the default is set explicitly.

This behaviour makes it easy to implement mandatory options.

from lethargy import Opt, argv, MissingOption

opt = Opt('example').takes(1)

    value = opt.take_args(argv, raises=True)
except MissingOption:
    print(f'Missing required option: {opt}')

Value conversion

Opt.takes can optionally take a callable object which will be used to convert the result of Opt.take_args. No additional error handling is performed, and the default value will not be converted.

>>> Opt('n').takes(1, int).take_args(['-n', '28980'])
>>> Opt('f').takes(2, float).take_args(['-f', '1', '3.1415'])
[1.0, 3.1415]
>>> Opt('chars').takes(1, set).take_args([])
>>> Opt('chars').takes(1, set).take_args([], default='Default')

Disabling mutation

Opt.take_args and Opt.take_flag both take the optional keyword argument mut. Setting mut to False disables mutation.

>>> lst = ["--name", "test",  "example"]
>>> Opt("name").takes(2).take_args(lst, mut=False)
['test', 'example']
>>> lst  # It hasn't changed!
['--name', 'test', 'example']


Any contributions and feedback are welcome! I'd appreciate it if you could open an issue to discuss changes before submitting a PR, but it's not enforced.


Lethargy is released under the MIT license.

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 lethargy, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size lethargy-1.0.0-py3-none-any.whl (8.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size lethargy-1.0.0.tar.gz (9.7 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