The Artima Developer Community
Sponsored Link

Weblogs Forum
plac, the easiest command line arguments parser in the Python world

12 replies on 1 page. Most recent reply: Jul 11, 2010 1:01 AM by Michele Simionato

Welcome Guest
  Sign In

Go back to the topic listing  Back to Topic List Click to reply to this topic  Reply to this Topic Click to search messages in this forum  Search Forum Click for a threaded view of the topic  Threaded View   
Previous Topic   Next Topic
Flat View: This topic has 12 replies on 1 page
Michele Simionato

Posts: 222
Nickname: micheles
Registered: Jun, 2008

plac, the easiest command line arguments parser in the Python world (View in Weblogs)
Posted: Jun 2, 2010 1:47 AM
Reply to this message Reply
Summary
Announcing the first public release of plac, a declarative command line arguments parser designed for simplicity and concision.
Advertisement

I would like to announce to the world the first public release of plac:

http://pypi.python.org/pypi/plac

Plac is a wrapper over argparse and works in all versions of Python starting from Python 2.3 up to Python 3.1.

With blatant immodesty, plac claims to be the easiest to use command line arguments parser module in the Python world. Its goal is to reduce the learning curve of argparse from hours to minutes. It does so by removing the need to build a command line arguments parser by hand: actually it is smart enough to infer the parser from function annotations.

Here is a simple example (in Python 3) to whet your appetite:

$ cat example.py
def main(arg: "required argument"):
    "do something with arg"
    print('Got %s' % arg)

if __name__ == '__main__':
    import plac; plac.call(main) # passes sys.argv[1:] to main

$ python example.py -h
usage: example.py [-h] arg

do something with arg

positional arguments:
  arg         required argument

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


$ python example.py
usage: example.py [-h] arg
example.py: error: too few arguments

$  python example.py arg
Got arg

$  python example.py arg1 arg2
usage: example.py [-h] arg
example.py: error: unrecognized arguments: arg2

You can find in the documentation a lot of other simple and not so simple examples:

http://micheles.googlecode.com/hg/plac/doc/plac.html

Enjoy!

Michele Simionato

P.S. answering an unspoken question: yes, we really needed yet another command line arguments parser! ;)


Pavel Panchekha

Posts: 1
Nickname: pavpan
Registered: Jun, 2010

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 2, 2010 7:28 AM
Reply to this message Reply
Have you seen http://pypi.python.org/pypi/CLIArgs ? Your module looks surprisingly similar in intent, though perhaps the feature sets don't exactly correspond.

Michele Simionato

Posts: 222
Nickname: micheles
Registered: Jun, 2008

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 2, 2010 8:45 AM
Reply to this message Reply
I did not known about CLIargs. The underlying philosophy is the same, to infer the parser from the function signature. Only the implementation is different. Since plac relies on function annotations it has more power, but I guess I must
concede that it cannot boast anymore about being the easiest command line argument parser in the world! ;-)

Frank Tobin

Posts: 1
Nickname: ftobin
Registered: Jun, 2010

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 2, 2010 2:35 PM
Reply to this message Reply
I think your approach with plac is a good one, as it eliminates an intermediate language for options, reusing the Python language's function syntax.

I notice that plac does not support required options, citing the "options should not be required" argument. I suggest that the name "option" is getting in the way for things passed in on the command line that are prefixed with dashes. Think of them just being named parameters. Certainly, Python has named parameters to functions, and they can be required if not specified in the positional manner.

Consider a function/command-line program with 5 arguments. Each argument is required, but as a human, you prefer not to have to remember the order in which they are specified -- you would rather just name each argument. Python supports this concept, as you can just use named parameters for each argument, but plac, optparse, and argprase do not support the same concept for command line program calls, even though they are conceptually equivalent.

Michele Simionato

Posts: 222
Nickname: micheles
Registered: Jun, 2008

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 3, 2010 12:00 AM
Reply to this message Reply
> Consider a function/command-line program with 5 arguments.
> Each argument is required, but as a human, you prefer not
> t to have to remember the order in which they are
> specified -- you would rather just name each argument.
> Python supports this concept, as you can just use named
> d parameters for each argument, but plac, optparse, and
> argprase do not support the same concept for command line
> program calls, even though they are conceptually
> equivalent.

I have two observations.

#1. There is a matter of opinions about the concept of
"required options" vs "required named parameters". Everybody is free to have his opinion; personally I would not want to have 5 required named arguments on a command line tool: in
that case I would start using a configuration file.

#2. Then there is matter of technical merit. Argparse *do* support required options and therefore plac supports them too:

$ cat required_flag.py
def main(f: ('required', 'flag', 'f')):
pass

if __name__ == '__main__':
import plac
parser = plac.parser_from(main)
parser._option_string_actions ['-f'].required = True
parser.parse_args()


$ python3 plac_required_flag.py
usage: plac_required_flag.py [-h] -f
plac_required_args.py: error: argument -f/--f is required

As you see, the feature is there I am not interested in making it easy to use.

Matt Gerrans

Posts: 1152
Nickname: matt
Registered: Feb, 2002

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 3, 2010 6:54 PM
Reply to this message Reply
I wrote my own simple lightweight command line parser for Python (and something similar for several other languages) that I've been using for years. Named items are prefixed with a dash or slash and separated from optional values by a colon or equal sign (eg. "/quiet", "-f:filename" or "/language=en-US") are "options" and all other undecorated things are "parameters." The options go into an object that has an attribute for each option and the paramters go into a list. So for the command line

test.py /c test.txt /r /displayname:Testing


You could have the following code:

from options import opts,params

if params:
filename = params[0]
caseSensitive = opts.c
recurse = opts.r
displayName = 'NoName'
if opts.DisplayName: displayName = opts.DisplayName
else:
ShowHelp()

. . .


The nice thing about this scheme is that it is very lightweight and has a learning curve of about 1 millisecond.

(The only built-in special case is that if you specify /? or -?, it is equivalent to "help" so opts.help will return True)

John Zabroski

Posts: 272
Nickname: zbo
Registered: Jan, 2007

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 4, 2010 4:49 PM
Reply to this message Reply
> As you see, the feature is there I am not interested in
> making it easy to use.

I could care less about Python or a library written in it, but when your first post claims this tool is written with concision and simplicity in mind, as well as aiming to be declarative? You do not seem to be consistent.

How is easy to use separate from your design objectives? As a library designer, defend yourself.

Michele Simionato

Posts: 222
Nickname: micheles
Registered: Jun, 2008

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 4, 2010 11:53 PM
Reply to this message Reply
I believe that a library (or a language for that matter) should be opinionated. In other words, the library should not try to be everything to everybody. Making things easy to use means offering a preferred path for using the library, decided by the library designer: only the preferred path should be kept easy to follow, not every possible usage of the library.

Notice that I do not believe the preferred path should be forced, i.e. there should always be a backdoor to do things which were not anticipated by the library author (which is a fallible human).

The feature requested by Matt Gerrans is not in the preferred path of plac: I do not like the concept of required options and I am not interested in making them easy to use. Still, plac offers a way to implement them, but that way is not guaranteed to be nice.

It is just impossible to make everything easy to use. Aiming to simplicity means making tradeoffs; and the difficult thing is to make the right ones, the ones that will satisfy most users. No tradeoff will satisfy *all* users, but okay, library authors can't perform miracles.
I think the alternative of trying to please everybody (typical of libraries/languages designed by committee) is much worse, since simplicity of use is nearly guaranteed to be lost.

Michele Simionato

Posts: 222
Nickname: micheles
Registered: Jun, 2008

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 5, 2010 12:36 AM
Reply to this message Reply
Ops, I confused Frank Tobin with Matt Gerrans, sorry about that.

John Zabroski

Posts: 272
Nickname: zbo
Registered: Jan, 2007

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 7, 2010 11:41 AM
Reply to this message Reply
I agree; programmers do have a habit of having an "engineer's mentality" when designing systems and ultimately compromise "usability" because they want to make everything programmable and give no thought into avoiding hours writing code people should probably avoid using anyway.

I also agree that "required options" are a bad idea; guards are always a bad idea and indicate lack of understanding about what a program should do (IMHO).

As an aside, I like the way PowerShell handles options, but it uses objects as parameters rather than textual parameters. Setting a default value for a parameter n for some program as (Read-Host "Enter a value for n: ") is very productive when prototyping scripts you ideally want to run non-interactively, but need to test interactively in the shell REPL to get a good feel for what it should do.

Michele Simionato

Posts: 222
Nickname: micheles
Registered: Jun, 2008

Re: plac, the easiest command line arguments parser in the Python world Posted: Jun 20, 2010 8:23 AM
Reply to this message Reply
UPDATE: I have just released plac 0.5.
This release is *huge*: the size of plac and of its documentation doubled.

Now plac is much more than a simple command-line arguments parser: it is also a generic tool to write command languages, similar to the cmd module in the standard library, only better.

You define plac commands from Python functions: plac will build a parser from the function signature and interpret the command line accordingly.

There is also a runner to run plac scripts and plac tests, which are pretty similar to Python doctests.

Oz DiGennaro

Posts: 2
Nickname: z4dtext
Registered: Jul, 2010

Re: plac, the easiest command line arguments parser in the Python world Posted: Jul 9, 2010 1:56 PM
Reply to this message Reply
I'm comfortable with immodesty. I have to be.

I'm happy with the stone-age module, but I do like your proposition about the need to "scale down" gracefully. I use slightly different terms to describe it: "graceful degradation" is the path to increased complexity and power, which often results in "degradation" of the developer experience. "Scale down" is the flip side and much to be desired.

Michele Simionato

Posts: 222
Nickname: micheles
Registered: Jun, 2008

Re: plac, the easiest command line arguments parser in the Python world Posted: Jul 11, 2010 1:01 AM
Reply to this message Reply
Release 0.6 is out: it provides full readline support (bye bye cmd module) and asynchronous commands usings threads or processes.

Flat View: This topic has 12 replies on 1 page
Topic: Article-Recommendation Service? Previous Topic   Next Topic Topic: Using Groovy Builders to Simplify Complex Object Hierarchy Creation


Sponsored Links



Google
  Web Artima.com   

Copyright © 1996-2014 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use - Advertise with Us