<commit_before>optfunc
=======

Parse command line options in Python using function introspection.

Post feedback here: http://simonwillison.net/2009/May/28/optfunc/

I can never remember how to use any of Python's regular command line parsing
libraries.

optfunc uses introspection to make a Python function available as a command
line utility. It's syntactic sugar around optparse from the standard library.

Here's what the API looks like so far:

    import optfunc
    
    def upper(filename, verbose = False):
        "Usage: %prog <file> [--verbose] - output file content in uppercase"
        s = open(filename).read()
        if verbose:
            print "Processing %s bytes..." % len(s)
        print s.upper()
    
    if __name__ == '__main__':
        optfunc.run(upper)

And here's the resulting command-line interface:

    $ ./demo.py --help
    Usage: demo.py <file> [--verbose] - output file content in uppercase
    
    Options:
      -h, --help     show this help message and exit
      -v, --verbose  
    $ ./demo.py README.txt 
    OPTFUNC
    ...
    $ ./demo.py README.txt -v
    Processing 2049 bytes...
    OPTFUNC
    ...

optfunc also supports two decorators for stuff I couldn't work out how to 
shoehorn in to a regular function definition. geocode.py shows them in action:

    @optfunc.notstrict
    @optfunc.arghelp('list_geocoders', 'list available geocoders and exit')
    def geocode(s, api_key='', geocoder='google', list_geocoders=False):
        # ...

@notstrict means "don't throw an error if one of the required positional 
arguments is missing" - in the above example we use this because we still want
the list_geocoders argument to work even if a string has not been provided.

@arghelp('arg-name', 'help text') allows you to provide help on individual 
arguments, which will then be displayed when --help is called.

TODO:

* Support for different argument types (int, string, filehandle, choices)
* Special handling for 'stdin' as an argument name
* Proper unix error semantics (sys.exit(1) etc)
* Allow the function to be a generator, print iterations to stdout
* Support for *args (I don't think **kwargs makes sense for optfunc)<commit_msg>Added documentation of how arguments are treated, and how option names are derived from function parameter names<commit_after>optfunc
=======

Parse command line options in Python using function introspection.

Post feedback here: http://simonwillison.net/2009/May/28/optfunc/

I can never remember how to use any of Python's regular command line parsing
libraries.

optfunc uses introspection to make a Python function available as a command
line utility. It's syntactic sugar around optparse from the standard library.

Here's what the API looks like so far:

    import optfunc
    
    def upper(filename, verbose = False):
        "Usage: %prog <file> [--verbose] - output file content in uppercase"
        s = open(filename).read()
        if verbose:
            print "Processing %s bytes..." % len(s)
        print s.upper()
    
    if __name__ == '__main__':
        optfunc.run(upper)

And here's the resulting command-line interface:

    $ ./demo.py --help
    Usage: demo.py <file> [--verbose] - output file content in uppercase
    
    Options:
      -h, --help     show this help message and exit
      -v, --verbose  
    $ ./demo.py README.txt 
    OPTFUNC
    ...
    $ ./demo.py README.txt -v
    Processing 2049 bytes...
    OPTFUNC
    ...

How arguments work
------------------

Non-keyword arguments are treated as required arguments - optfunc.run will 
throw an error if they number of arguments provided on the command line 
doesn't match the number expected by the function (unless @notstrict is used, 
see below).

Keyword arguments with defaults are treated as options. At the moment, only 
string and boolean arguments are supported. Other types are planned.

Consider the following:

    def geocode(s, api_key='', geocoder='google', list_geocoders=False):

's' is a required argument. api_key, geocoder and list_geocoders are all 
options, with defaults provided. Since list_geocoders has a boolean as its 
default it will be treated slightly differently (in optparse terms, it will 
store True if the flag is provided on the command line and False otherwise).

The command line options are derived from the parameter names like so:

    Options:
      -h, --help            show this help message and exit
      -l, --list-geocoders
      -a API_KEY, --api-key=API_KEY
      -g GEOCODER, --geocoder=GEOCODER

Note that the boolean --list-geocoders is a flag, not an option that sets a
value.

The short option is derived from the first letter of the parameter. If that 
character is already in use, the second character will be used and so on.

The long option is the full name of the parameter with underscores converted 
to hyphens.

If you want complete control over the name of the options, simply name your 
parameter as follows:

    def foo(q_custom_name=False):

This will result in a short option of -q and a long option of --custom-name.

Decorators
----------

optfunc also supports two decorators for stuff I couldn't work out how to 
shoehorn in to a regular function definition. geocode.py shows them in action:

    @optfunc.notstrict
    @optfunc.arghelp('list_geocoders', 'list available geocoders and exit')
    def geocode(s, api_key='', geocoder='google', list_geocoders=False):
        # ...

@notstrict means "don't throw an error if one of the required positional 
arguments is missing" - in the above example we use this because we still want
the list_geocoders argument to work even if a string has not been provided.

@arghelp('arg-name', 'help text') allows you to provide help on individual 
arguments, which will then be displayed when --help is called.

TODO
----

* Support for different argument types (int, string, filehandle, choices)
* Special handling for 'stdin' as an argument name
* Proper unix error semantics (sys.exit(1) etc)
* Allow the function to be a generator, print iterations to stdout
* Support for *args (I don't think **kwargs makes sense for optfunc)
{'fraction_non_alphanumeric': 0.081363117560737, 'fraction_numerical': 0.0035871514756236752, 'mean_word_length': 3.184174624829468, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6902165', 'n_tokens_mistral': 1754, 'n_tokens_neox': 1690, 'n_words': 794}