We now have a branch[5] of argparse that supports an ``argparse.run``
function[6] which does
some function introspection to build a command line parser from a
function definition:

------------------------------ prog.py ------------------------------
import argparse

def func(foo, bar, baz):
   """A function that foo's a bar with a baz.
   foo - The foo
   bar - The bar to be foo'd
   baz - The baz with which to foo.
   """
   print foo, bar, baz

if __name__ == '__main__':
   argparse.run(func)
------------------------------ cmdline ------------------------------
$ prog.py -h
usage: prog.py [-h] foo bar baz

A function that foo's a bar with a baz.

positional arguments:
 foo         The foo
 bar         The bar to be foo'd
 baz         The baz with which to foo.

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

I'd love to hear some feedback on this. At the moment, the code can
introspect argument names, types from defaults, types from annotations
(in Python 3), help messages from docstrings, and knows how to convert
multiple functions into subcommands. The code's compatible and tested
on python 2.3 - 3.1. There are probably more things we could support
[7], but I'd like to get some feedback on what we have so
far. Some specific questions:

* Do you think this is worth including in argparse?
* Would you use the current ``argparse.run`` API in your own code?
* If you wouldn't use it as-is, what additional features/modifications
would you require?

--Steve and Yuv

PS: The authors of pyopt[1], opster[2], optfunc[3] and simpleopt[4]
were CC'd, in the hopes that we can converge to a common API, but they
didn't reply other than the pyopt guy (me) who wrote the patch.
[0] SVN branch at: http://argparse.googlecode.com/svn/branches/function-arguments/
[1] http://code.google.com/p/pyopt/
[2] http://hg.piranha.org.ua/opster/
[3] http://github.com/simonw/optfunc/
[4] http://pypi.python.org/pypi/simpleopt/
[5] http://argparse.googlecode.com/svn/branches/function-arguments/
[6] The branch also adds ``ArgumentParser.add_function_arguments``
which ``argparse.run`` is built on top of. This method allows you to
match function based arguments with other arguments as necessary,
e.g.::
   def items(n=10):
       return range(n)

   parser = argparse.ArgumentParser()
   parser.add_function_arguments(items)
   parser.add_argument('output_file')
   args = parser.parse_args()
   with open(args.output_file, 'w') as output_file:
       for item in args.items():
           output_file.write("%d\n" % item)

I am not sure I like the name "run", seems to short and innocent for a
function this magical.

Is the docstring expected to be formatted according to some
convention?  I don't recognize a docstring convention in the example,
but then I don't bother with them much in my own code, that's why I
ask.

    The parsing algorithm currently looks for lines that start with a
parameter
    name immediately followed by any amount of whitespace, hyphens or
colons.
    The rest of the line following the colon/hyphen/whitespace is the
help.

    Keyword Arguments:
        function - the function whose docstring is parsed.

    Returns a (description, help_dict) tuple:
        description - all text before the first documented parameter
        help_dict - a dictionary mapping parameter names to their help
strings
    """

We tried to comply to PEP 257 and we're open to suggestions on this.

Chris