Plac: Parsing the Command Line the Easy Way ¶

Author:: Michele Simionato
E-mail:: michele.simionato@gmail.com
Version:: 1.3.4
Date:: December 2021
Download page:: https://pypi.org/project/plac/
Project page:: https://github.com/ialbert/plac
Requires:: Python from 2.6 up
Installation:: pip install plac
License:: BSD license

For the impatient ¶

Here is how you would write a command-line script with plac, taken from a real life machine learning script that I found on the net:

import plac
try:
    from pathlib import Path
except ImportError:  # in Python 2.7
    Path = str


@plac.pos('model', "Model name", choices=['A', 'B', 'C'])
@plac.opt('output_dir', "Optional output directory", type=Path)
@plac.opt('n_iter', "Number of training iterations", type=int)
@plac.flg('debug', "Enable debug mode")
def main(model, output_dir='.', n_iter=100, debug=False):
    """A script for machine learning"""


if __name__ == '__main__':
    plac.call(main)

Running the script with $ python example_all.py -h will give you the following help message:

usage: example_all.py [-h] [-o .] [-n 100] [-d] {A,B,C}

A script for machine learning

positional arguments:
  {A,B,C}               Model name

options:
  -h, --help            show this help message and exit
  -o ., --output-dir .  Optional output directory
  -n 100, --n-iter 100  Number of training iterations
  -d, --debug           Enable debug mode

The patient readers will find all the explanations in the sections below.

The importance of scaling down ¶

There is no want of command-line arguments parsers in the Python world. The standard library alone contains three different modules: getopt (from the stone age), optparse (from Python 2.3) and argparse (from Python 2.7). All of them are quite powerful and especially argparse is an industrial strength solution; unfortunately, all of them feature a non-negligible learning curve and a certain verbosity. They do not scale down well enough, at least in my opinion.

It should not be necessary to stress the importance of scaling down; nevertheless, a lot of people are obsessed with features and concerned with the possibility of scaling up, forgetting the equally important issue of scaling down. This is an old meme in the computing world: programs should address the common cases simply and simple things should be kept simple, while at the same time keeping difficult things possible. plac adhere as much as possible to this philosophy and it is designed to handle well the simple cases, while retaining the ability to handle complex cases by relying on the underlying power of argparse.

Technically plac is just a simple wrapper over argparse which hides most of its complexity by using a declarative interface: the argument parser is inferred rather than written down by imperatively. Still, plac is surprisingly scalable upwards, even without using the underlying argparse. I have been using Python for 9 years and in my experience it is extremely unlikely that you will ever need to go beyond the features provided by the declarative interface of plac: they should be more than enough for 99.9% of the use cases.

plac is targeting especially unsophisticated users, programmers, sys-admins, scientists and in general people writing throw-away scripts for themselves, choosing the command-line interface because it is quick and simple. Such users are not interested in features, they are interested in a small learning curve: they just want to be able to write a simple command line tool from a simple specification, not to build a command-line parser by hand. Unfortunately, the modules in the standard library forces them to go the hard way. They are designed to implement power user tools and they have a non-trivial learning curve. On the contrary, plac is designed to be simple to use and extremely concise, as the examples below will show.

Scripts with required arguments ¶

Let me start with the simplest possible thing: a script that takes a single argument and does something to it. It cannot get simpler than that, unless you consider the case of a script without command-line arguments, where there is nothing to parse. Still, it is a use case extremely common: I need to write scripts like that nearly every day, I wrote hundreds of them in the last few years and I have never been happy. Here is a typical example of code I have been writing by hand for years:

# example1.py
def main(dsn):
    "Do something with the database"
    print("ok")

if __name__ == '__main__':
    import sys
    n = len(sys.argv[1:])
    if n == 0:
        sys.exit('usage: python %s dsn' % sys.argv[0])
    elif n == 1:
        main(sys.argv[1])
    else:
        sys.exit('Unrecognized arguments: %s' % ' '.join(sys.argv[2:]))

As you see the whole if __name__ == '__main__' block (nine lines) is essentially boilerplate that should not exist. Actually I think the language should recognize the main function and pass the command-line arguments automatically; unfortunately this is unlikely to happen. I have been writing boilerplate like this in hundreds of scripts for years, and every time I hate it. The purpose of using a scripting language is convenience and trivial things should be trivial. Unfortunately the standard library does not help for this incredibly common use case. Using getopt and optparse does not help, since they are intended to manage options and not positional arguments; the argparse module helps a bit and it is able to reduce the boilerplate from nine lines to six lines:

# example2.py
def main(dsn):
    "Do something on the database"
    print(dsn)
    # ...

if __name__ == '__main__':
    import argparse
    p = argparse.ArgumentParser()
    p.add_argument('dsn')
    arg = p.parse_args()
    main(arg.dsn)

However, it just feels too complex to instantiate a class and to define a parser by hand for such a trivial task.

The plac module is designed to manage well such use cases, and it is able to reduce the original nine lines of boiler plate to two lines. With the plac module all you need to write is

# example3.py
def main(dsn):
    "Do something with the database"
    print(dsn)
    # ...

if __name__ == '__main__':
    import plac; plac.call(main)

The plac module provides for free (actually the work is done by the underlying argparse module) a nice usage message:

$ python example3.py -h

usage: example3.py [-h] dsn

Do something with the database

positional arguments:
  dsn

options:
  -h, --help  show this help message and exit

Moreover plac manages the case of missing arguments and of too many arguments. This is only the tip of the iceberg: plac is able to do much more than that.

Scripts with default arguments ¶

The need to have suitable defaults for command-line scripts is quite common. For instance I have encountered this use case at work hundreds of times:

# example4.py
from datetime import datetime

def main(dsn, table='product', today=datetime.today()):
    "Do something on the database"
    print(dsn, table, today)

if __name__ == '__main__': # manual management before argparse
    import sys
    args = sys.argv[1:]
    if not args:
        sys.exit('usage: python %s dsn' % sys.argv[0])
    elif len(args) > 2:
        sys.exit('Unrecognized arguments: %s' % ' '.join(argv[2:]))
    main(*args)

Here I want to perform a query on a database table, by extracting the most recent data: it makes sense for today to be a default argument. If there is a most used table (in this example a table called 'product') it also makes sense to make it a default argument. Performing the parsing of the command-line arguments by hand takes 8 ugly lines of boilerplate (using argparse would require about the same number of lines). With plac the entire __main__ block reduces to the usual two lines:

if __name__ == '__main__':
    import plac; plac.call(main)

In other words, six lines of boilerplate have been removed, and we get the usage message for free:

usage: example5.py [-h] dsn [table] [today]

Do something on the database

positional arguments:
  dsn
  table       [product]
  today       [YYYY-MM-DD]

options:
  -h, --help  show this help message and exit

Notice that by default plac prints the string representation of the default values (with square brackets) in the usage message. plac manages transparently even the case when you want to pass a variable number of arguments. Here is an example, a script running on a database a series of SQL scripts:

# example7.py
from datetime import datetime

def main(dsn, *scripts):
    "Run the given scripts on the database"
    for script in scripts:
        print('executing %s' % script)
        # ...

if __name__ == '__main__':
    import plac; plac.call(main)

Here is the usage message:

usage: example7.py [-h] dsn [scripts ...]

Run the given scripts on the database

positional arguments:
  dsn
  scripts

options:
  -h, --help  show this help message and exit

The examples here should have made clear that plac is able to figure out the command-line arguments parser to use from the signature of the main function. This is the whole idea behind plac: if the intent is clear, let’s the machine take care of the details.

plac is inspired to an old Python Cookbook recipe of mine (optionparse), in the sense that it delivers the programmer from the burden of writing the parser, but is less of a hack: instead of extracting the parser from the docstring of the module, it extracts it from the signature of the main function.

The idea comes from the function annotations concept, a new feature of Python 3. An example is worth a thousand words, so here it is:

# example7_.py
from datetime import datetime

def main(dsn: "Database dsn", *scripts: "SQL scripts"):
    "Run the given scripts on the database"
    for script in scripts:
        print('executing %s' % script)
        # ...

if __name__ == '__main__':
    import plac; plac.call(main)

Here the arguments of the main function have been annotated with strings which are intended to be used in the help message:

usage: example7_.py [-h] dsn [scripts ...]

Run the given scripts on the database

positional arguments:
  dsn         Database dsn
  scripts     SQL scripts

options:
  -h, --help  show this help message and exit

plac is able to recognize much more complex annotations, as I will show in the next paragraphs.

Scripts with options (and smart options)¶

It is surprising how few command-line scripts with options I have written over the years (probably less than a hundred), compared to the number of scripts with positional arguments I wrote (certainly more than a thousand of them). Still, this use case cannot be neglected. The standard library modules (all of them) are quite verbose when it comes to specifying the options and frankly I have never used them directly. Instead, I have always relied on the optionparse recipe, which provides a convenient wrapper over argparse. Alternatively, in the simplest cases, I have just performed the parsing by hand. In plac the parser is inferred by the function annotations. Here is an example:

# example8.py
def main(command: ("SQL query", 'option', 'c'), dsn):
    if command:
        print('executing %s on %s' % (command, dsn))
        # ...

if __name__ == '__main__':
    import plac; plac.call(main)

Here the argument command has been annotated with the tuple ("SQL query", 'option', 'c'): the first string is the help string which will appear in the usage message, the second string tells plac that command is an option and the third string that there is also a short form of the option -c, the long form being --command. The usage message is the following:

usage: example8.py [-h] [-c COMMAND] dsn

positional arguments:
  dsn

options:
  -h, --help            show this help message and exit
  -c COMMAND, --command COMMAND
                        SQL query

Here are two examples of usage:

$ python3 example8.py -c "select * from table" dsn
executing select * from table on dsn

$ python3 example8.py --command="select * from table" dsn
executing select * from table on dsn

The third argument in the function annotation can be omitted: in such case it will be assumed to be None. The consequence is that the usual dichotomy between long and short options (GNU-style options) disappears: we get smart options, which have the single character prefix of short options and behave like both long and short options, since they can be abbreviated. Here is an example featuring smart options:

# example6.py
def main(dsn, command: ("SQL query", 'option')='select * from table'):
    print('executing %r on %s' % (command, dsn))

if __name__ == '__main__':
    import plac; plac.call(main)

usage: example6.py [-h] [-command select * from table] dsn

positional arguments:
  dsn

options:
  -h, --help            show this help message and exit
  -command select * from table
                        SQL query

The following are all valid invocations of the script:

$ python3 example6.py -c "select" dsn
executing 'select' on dsn
$ python3 example6.py -com "select" dsn
executing 'select' on dsn
$ python3 example6.py -command="select" dsn
executing 'select' on dsn

Notice that the form -command=SQL (with the = sign) is recognized only for the full option, not for its abbreviations:

$ python3 example6.py -com="select" dsn
usage: example6.py [-h] [-command COMMAND] dsn
example6.py: error: unrecognized arguments: -com=select

If the option is not passed, the variable command will get the value None. However, it is possible to specify a non-trivial default. Here is an example:

# example8_.py
def main(dsn, command: ("SQL query", 'option', 'c')='select * from table'):
    print('executing %r on %s' % (command, dsn))

if __name__ == '__main__':
    import plac; plac.call(main)

Notice that the default value appears in the help message:

usage: example8_.py [-h] [-c select * from table] dsn

positional arguments:
  dsn

options:
  -h, --help            show this help message and exit
  -c select * from table, --command select * from table
                        SQL query

When you run the script and you do not pass the -command option, the default query will be executed:

$ python3 example8_.py dsn
executing 'select * from table' on dsn

Scripts with flags ¶

plac is able to recognize flags, i.e. boolean options which are True if they are passed to the command line and False if they are absent. Here is an example:

# example9.py

def main(verbose: ('prints more info', 'flag', 'v'), dsn: 'connection string'):
    if verbose:
        print('connecting to %s' % dsn)
    # ...

if __name__ == '__main__':
    import plac; plac.call(main)

usage: example9.py [-h] [-v] dsn

positional arguments:
  dsn            connection string

options:
  -h, --help     show this help message and exit
  -v, --verbose  prints more info

$ python3 example9.py -v dsn
connecting to dsn

Notice that it is an error trying to specify a default for flags: the default value for a flag is always False. If you feel the need to implement non-boolean flags, you should use an option with two choices, as explained in the “more features” section.

For consistency with the way the usage message is printed, I suggest you to follow the Flag-Option-Required-Default (FORD) convention: in the main function write first the flag arguments, then the option arguments, then the required arguments and finally the default arguments. This is just a convention and you are not forced to use it, except for the default arguments (including the varargs) which must stay at the end as it is required by the Python syntax.

I also suggests to specify a one-character abbreviation for flags: in this way you can use the GNU-style composition of flags (i.e. -zxvf is an abbreviation of -z -x -v -f). I usually do not provide the one-character abbreviation for options, since it does not make sense to compose them.

Starting from plac 0.9.1 underscores in options and flags are automatically turned into dashes. This feature was implemented at user request, to make it possible to use a more traditional naming. For instance now you can have a --dry-run flag, whereas before you had to use --dry_run.

def main(dry_run: ('Dry run', 'flag', 'd')):
    if dry_run:
        print('Doing nothing')
    else:
        print('Doing something')

if __name__ == '__main__':
    import plac; plac.call(main)

Here is an example of usage:

$ python3.2 dry_run.py -h
usage: dry_run.py [-h] [-d]

optional arguments:
  -h, --help     show this help message and exit
  -d, --dry-run  Dry run

plac for Python 2.X users ¶

Even if Python 2 has reached its end of life, plac still provides a way to work with function annotations by means of decorators. For instance the annotated function declaration

def main(dsn: "Database dsn", *scripts: "SQL scripts"):
    ...

is equivalent to the following code:

@plac.annotations(
    dsn="Database dsn",
    scripts="SQL scripts")
def main(dsn, *scripts):
    ...

In the rest of this article I will assume that you are using Python 2.X with X >= 4 and I will use the plac.annotations decorator. Notice however that the core features of plac run even on Python 2.3.

More features ¶

One of the goals of plac is to have a learning curve of minutes for its core features, compared to the learning curve of hours of argparse. In order to reach this goal, I have not sacrificed all the features of argparse. Actually a lot of the argparse power persists in plac. Until now, I have only showed simple annotations, but in general an annotation is a 6-tuple of the form

(help, kind, abbrev, type, choices, metavar)

where help is the help message, kind is a string in the set { "flag", "option", "positional"}, abbrev is a one-character string or None, type is a callable taking a string in input, choices is a discrete sequence of values and metavar is a string.

type is used to automagically convert the command line arguments from the string type to any Python type; by default there is no conversion and type=None.

choices is used to restrict the number of the valid options; by default there is no restriction i.e. choices=None.

metavar has two meanings. For a positional argument it is used to change the argument name in the usage message (and only there). By default the metavar is None and the name in the usage message is the same as the argument name. For an option the metavar is used differently in the usage message, which has now the form [--option-name METAVAR]. If the metavar is None, then it is equal to the uppercased name of the argument, unless the argument has a default: then it is equal to the stringified form of the default.

Here is an example showing all of the features, including the metavar, copied from the argparse documentation:

# example10.py
import plac


# example with full annotations (help, kind, abbrev, type, choices, metavar)
@plac.annotations(
    operator=("The name of an operator", 'positional', None, str,
              ['add', 'mul']),
    numbers=("Zero or more numbers", 'positional', None, float, None, 'n'))
def main(operator, *numbers):
    "A script to add and multiply numbers"
    if operator == 'mul':
        op = float.__mul__
        result = 1.0
    else:  # operator == 'add'
        op = float.__add__
        result = 0.0
    for n in numbers:
        result = op(result, n)
    return result


if __name__ == '__main__':
    print(plac.call(main))

If you cannot remember the order of the annotations you can use the plac.Annotation class (there is an example in the next section) or the alternative decoration syntax introduced in version 1.2:

@plac.pos('operator', "The name of an operator", choices=['add', 'mul'])
@plac.pos('numbers', "Zero or more numbers", float, metavar='n')
def main(operator, *numbers):
    ...

which is more compact. There are also a plac.opt decorator for options and plac.flg decorator for flags and they can be stacked together at will.

Here is the usage:

usage: example10.py [-h] {add,mul} [n ...]

A script to add and multiply numbers

positional arguments:
  {add,mul}   The name of an operator
  n           Zero or more numbers

options:
  -h, --help  show this help message and exit

Notice that the docstring of the main function has been automatically added to the usage message. Here are a couple of examples of usage:

$ python example10.py add 1 2 3 4
10.0
$ python example10.py mul 1 2 3 4
24.0
$ python example10.py ad 1 2 3 4 # a misspelling error
usage: example10.py [-h] {add,mul} [n ...]
example10.py: error: argument operator: invalid choice: 'ad' (choose from 'add', 'mul')

plac.call can also be used in doctests like this:

>>> import plac, example10
>>> plac.call(example10.main, ['add', '1', '2'])
3.0

plac.call works for generators too:

>>> def main(n):
...     for i in range(int(n)):
...         yield i
>>> plac.call(main, ['3'])
[0, 1, 2]

Internally plac.call tries to convert the output of the main function into a list, if possible. If the output is not iterable or it is a string, it is left unchanged, but if it is iterable it is converted. In particular, generator objects are exhausted by plac.call.

This behavior avoids mistakes like forgetting of applying list(result) to the result of plac.call; moreover it makes errors visible early, and avoids mistakes in code like the following:

try:
    result = plac.call(main, args)
except:
   # do something

Without eagerness, a main function returning a generator object would not raise any exception until the generator is iterated over. If you are a fan of laziness, you can still have it by setting the eager flag to False, as in the following example:

for line in plac.call(main, args, eager=False):
    print(line)

If main returns a generator object this example will print each line as soon as available, whereas the default behaviour is to print all the lines together and the end of the computation.

What to do if an argument name clashes with a Python builtin/keyword?¶

Since version 1.3, thanks to a contribution of Istvan Albert, plac manages such cases easily. The trick is to add one (or more) trailing underscores to the arguments that would clash; plac will automatically strip the underscores:

# example13.py
import plac


@plac.flg('list_')  # avoid clash with builtin
@plac.flg('yield_')  # avoid clash with keyword
@plac.opt('sys_')  # avoid clash with a very common name
def main(list_, yield_=False, sys_=100):
    print(list_)
    print(yield_)
    print(sys_)


if __name__ == '__main__':
    plac.call(main)

The usage message will be as you would expect:

$ python doc/example13.py -h
usage: example13.py [-h] [-l] [-y] [-s 100]

optional arguments:
  -h, --help         show this help message and exit
  -l, --list
  -y, --yield        [False]
  -s 100, --sys 100  [100]

Keyword arguments ¶

Starting from release 0.4, plac supports keyword arguments. In practice that means that if your main function has keyword arguments, plac treats specially arguments of the form "name=value" in the command line. Here is an example:

# example12.py
import plac


@plac.annotations(
   opt=('some option', 'option'),
   args='default arguments',
   kw='keyword arguments')
def main(opt, *args, **kw):
    if opt:
       yield 'opt=%s' % opt
    if args:
       yield 'args=%s' % str(args)
    if kw:
       yield 'kw=%s' % kw

if __name__ == '__main__':
    for output in plac.call(main):
       print(output)

Here is the generated usage message:

usage: example12.py [-h] [-opt OPT] [args ...] [kw ...]

positional arguments:
  args        default arguments
  kw          keyword arguments

options:
  -h, --help  show this help message and exit
  -opt OPT    some option

Here is how you call the script:

$ python example12.py -o X a1 a2 name=value
opt=X
args=('a1', 'a2')
kw={'name': 'value'}

When using keyword arguments, one must be careful to use names which are not already taken; for instance in this examples the name opt is taken:

$ python example12.py 1 2 kw1=1 kw2=2 opt=0
usage: example12.py [-h] [-o OPT] [args ...] [kw ...]
example12.py: error: colliding keyword arguments: opt

The names taken are the names of the flags, of the options, and of the positional arguments, excepted varargs and keywords. This limitation is a consequence of the way the argument names are managed in function calls by the Python language.

plac vs argparse ¶

plac is opinionated and by design it does not try to make available all of the features of argparse in an easy way. In particular you should be aware of the following limitations/differences (the following assumes knowledge of argparse):

plac does not support the destination concept: the destination coincides with the name of the argument, always. This restriction has some drawbacks. For instance, suppose you want to define a long option called --yield. In this case the destination would be yield, which is a Python keyword, and since you cannot introduce an argument with that name in a function definition, it is impossible to implement it. Your choices are to change the name of the long option, or to use argparse with a suitable destination.
plac does not support “required options”. As the argparse documentation puts it: Required options are generally considered bad form - normal users expect options to be optional. You should avoid the use of required options whenever possible. Notice that since argparse supports them, plac can manage them too, but not directly.
plac supports only regular boolean flags. argparse has the ability to define generalized two-value flags with values different from True and False. An earlier version of plac had this feature too, but since you can use options with two choices instead, and in any case the conversion from {True, False} to any couple of values can be trivially implemented with a ternary operator (value1 if flag else value2), I have removed it (KISS rules!).
plac does not support nargs options directly (it uses them internally, though, to implement flag recognition). The reason it that all the use cases of interest to me are covered by plac and I did not feel the need to increase the learning curve by adding direct support for nargs.
plac does support subparsers, but you must read the section :ref:`Implementing subcommands`_ to see how it works.
plac does not support actions directly. This also looks like a feature too advanced for the goals of plac. Notice, however, that the ability to define your own annotation objects (again, see the section :ref:`Implementing subcommand`_) may mitigate the need for custom actions.

On the plus side, plac can directly leverage a number of argparse features.

For instance, you can use argparse.FileType directly. Moreover, it is possible to pass options to the underlying argparse.ArgumentParser object (currently it accepts the default arguments description, epilog, prog, usage, add_help, argument_default, parents, prefix_chars, fromfile_prefix_chars, conflict_handler, formatter_class). It is enough to set such attributes on the main function. For instance writing

def main(...):
    pass

main.add_help = False

disables the recognition of the help flag -h, --help. This mechanism does not look particularly elegant, but it works well enough. I assume that the typical user of plac will be happy with the defaults and would not want to change them; still it is possible if she wants to.

For instance, by setting the description attribute, it is possible to add a comment to the usage message (by default the docstring of the main function is used as description).

It is also possible to change the option prefix; for instance if your script must run under Windows and you want to use “/” as option prefix you can add the line:

main.prefix_chars='/-'

The first prefix char (/) is used as the default for the recognition of options and flags; the second prefix char (-) is kept to keep the -h/--help option working: however you can disable it and reimplement it, if you like.

It is possible to access directly the underlying ArgumentParser object, by invoking the plac.parser_from utility function:

>>> import plac
>>> def main(arg):
...     pass
...
>>> print(plac.parser_from(main))
ArgumentParser(prog=...)

Internally plac.call uses plac.parser_from. Notice that when plac.call(func) is invoked multiple time, the parser is re-used and not rebuilt from scratch again.

I use plac.parser_from in the unit tests of the module, but regular users should not need to use it, unless they want to access all of the features of argparse directly without calling the main function.

Interested readers should read the documentation of argparse to understand the meaning of the other options. If there is a set of options that you use very often, you may consider writing a decorator adding such options to the main function for you. For simplicity, plac does not perform any magic.

Final example: a shelve interface ¶

Here is a nontrivial example showing off many plac feature, including keyword arguments recognition. The use case is the following: suppose we have stored the configuration parameters of a given application into a Python shelve and we need a command-line tool to edit the shelve. A possible implementation using plac could be the following:

# ishelve.py
import os
import shelve
import plac

DEFAULT_SHELVE = 'conf.shelve'


@plac.annotations(
    help=('show help', 'flag'),
    showall=('show all parameters in the shelve', 'flag'),
    clear=('clear the shelve', 'flag'),
    delete=('delete an element', 'option'),
    filename=('filename of the shelve', 'option'),
    params='names of the parameters in the shelve',
    setters='setters param=value')
def main(help, showall, clear, delete, filename=DEFAULT_SHELVE,
         *params, **setters):
    "A simple interface to a shelve. Use .help to see the available commands."
    sh = shelve.open(filename)
    try:
        if not any([help, showall, clear, delete, params, setters]):
            yield ('no arguments passed, use .help to see the '
                   'available commands')
        elif help:  # custom help
            yield 'Commands: .help, .showall, .clear, .delete'
            yield '<param> ...'
            yield '<param=value> ...'
        elif showall:
            for param, name in sh.items():
                yield '%s=%s' % (param, name)
        elif clear:
            sh.clear()
            yield 'cleared the shelve'
        elif delete:
            try:
                del sh[delete]
            except KeyError:
                yield '%s: not found' % delete
            else:
                yield 'deleted %s' % delete
        for param in params:
            try:
                yield sh[param]
            except KeyError:
                yield '%s: not found' % param
        for param, value in setters.items():
            sh[param] = value
            yield 'setting %s=%s' % (param, value)
    finally:
        sh.close()


main.add_help = False  # there is a custom help, remove the default one
main.prefix_chars = '.'  # use dot-prefixed commands

if __name__ == '__main__':
    for output in plac.call(main):
        print(output)

A few notes are in order:

I have disabled the ordinary help provided by argparse and I have implemented a custom help command.
I have changed the prefix character used to recognize the options to a dot.
Keyword arguments recognition (in the **setters) is used to make it possible to store a value in the shelve with the syntax param_name=param_value.
*params are used to retrieve parameters from the shelve and some error checking is performed in the case of missing parameters
A command to clear the shelve is implemented as a flag (.clear).
A command to delete a given parameter is implemented as an option (.delete).
There is an option with default (.filename=conf.shelve) to set the filename of the shelve.
All things considered, the code looks like a poor man’s object oriented interface implemented with a chain of elifs instead of methods. Of course, plac can do better than that, but let me start from a low-level approach first.

If you run ishelve.py without arguments you get the following message:

$ python ishelve.py
no arguments passed, use .help to see the available commands

If you run ishelve.py with the option .h (or any abbreviation of .help) you get:

$ python ishelve.py .h
Commands: .help, .showall, .clear, .delete
<param> ...
<param=value> ...

You can check by hand that the tool works:

$ python ishelve.py .clear # start from an empty shelve
cleared the shelve
$ python ishelve.py a=1 b=2
setting a=1
setting b=2
$ python ishelve.py .showall
b=2
a=1
$ python ishelve.py .del b # abbreviation for .delete
deleted b
$ python ishelve.py a
1
$ python ishelve.py b
b: not found
$ python ishelve.py .cler # misspelled command
usage: ishelve.py [.help] [.showall] [.clear] [.delete DELETE]
                  [.filename conf.shelve]
                  [params ...] [setters ...]
ishelve.py: error: unrecognized arguments: .cler

plac vs the rest of the world ¶

Originally plac boasted about being “the easiest command-line arguments parser in the world”. Since then, people started pointing out to me various projects which are based on the same idea (extracting the parser from the main function signature) and are arguably even easier than plac:

opterator by Dusty Phillips
CLIArgs by Pavel Panchekha
commandline by David Laban

Luckily for me none of such projects had the idea of using function annotations and argparse; as a consequence, they are no match for the capabilities of plac.

Of course, there are tons of other libraries to parse the command line. For instance Clap by Matthew Frazier which appeared on PyPI just the day before plac; Clap is fine but it is certainly not easier than plac.

plac can also be used as a replacement of the cmd module in the standard library and as such it shares many features with the module cmd2 by Catherine Devlin. However, this is completely coincidental, since I became aware of the cmd2 module only after writing plac.

Command-line argument parsers keep coming out; between the newcomers I will notice marrow.script by Alice Bevan-McGregor, which is quite similar to plac in spirit, but does not rely on argparse at all. Argh by Andrey Mikhaylenko is also worth mentioning: it is based on argparse, it came after plac and I must give credit to the author for the choice of the name, much funnier than plac!

The future ¶

Currently the core of plac is around 200 lines of code, not counting blanks, comments and docstrings. I do not plan to extend the core much in the future. The idea is to keep the module short: it is and it should remain a little wrapper over argparse. Actually I have thought about contributing the core back to argparse if plac becomes successful and gains a reasonable number of users. For the moment it should be considered in a frozen status.

Notice that even if plac has been designed to be simple to use for simple stuff, its power should not be underestimated; it is actually a quite advanced tool with a domain of applicability which far exceeds the realm of command-line arguments parsers.

Version 0.5 of plac doubled the code base and the documentation: it is based on the idea of using plac to implement command-line interpreters, i.e. something akin to the cmd module in the standard library, only better. The new features are implemented in a separated module (plac_ext.py), since they require Python 2.5 to work, whereas plac_core.py only requires Python 2.3.

Trivia: the story behind the name ¶

The plac project started very humbly: I just wanted to make my old optionparse recipe easy_installable, and to publish it on PyPI. The original name of plac was optionparser and the idea behind it was to build an OptionParser object from the docstring of the module. However, before doing that, I decided to check out the argparse module, since I knew it was going into Python 2.7 and Python 2.7 was coming out. Soon enough I realized two things:

the single greatest idea of argparse was unifying the positional arguments and the options in a single namespace object;
parsing the docstring was so old-fashioned, considering the existence of functions annotations in Python 3.

Putting together these two observations with the original idea of inferring the parser I decided to build an ArgumentParser object from function annotations. The optionparser name was ruled out, since I was now using argparse; a name like argparse_plus was also ruled out, since the typical usage was completely different from the argparse usage.

I made a research on PyPI and the name clap (Command Line Arguments Parser) was not taken, so I renamed everything to clap. After two days a Clap module appeared on PyPI <expletives deleted>!

Having little imagination, I decided to rename everything again to plac, an anagram of clap: since it is a non-existing English name, I hope nobody will steal it from me!

That concludes the section about the basic usage of plac. You are now ready to read about the advanced usage.