Baker 1.3

Description:

Baker 1.3

History=======Version 1.3 * Better Python 3 support. * Improved test coverage. * Fixed #22: *varargs are now displayed in command help. * Fixed annoying beavhior of *varargs help when no keyword arguments are present.Version 1.2 * Python 3 support! * Runs from Python 2.6 up to 3.2. * More unit tests. * Code coverage to 89%. * Single-letter arguments are now automatically added to shortopts. * Fixed #14: Unable to mix varargs and kwargs.Version 1.1 * ``baker.run()`` now prints the return value of the command function. * Command usage help now shows help for optional arguments. * Added options to ``baker.run()``. * Added ``baker.usage([commandname])``. * Added unit tests. * Fixed bugs.Overview========Baker lets you easily add a command line interface to your Python functionsusing a simple decorator, to create scripts with "sub-commands", similar toDjango's ``manage.py``, ``svn``, ``hg``, etc.:: #!python import baker # An imaginary script full of useful Python functions @baker.command def set(name, value=None, overwrite=False): """Sets the value of a key in the database. If you don't specify a value, the named key is deleted. Overwriting a value may not be visible to all clients until the next full sync. """ db = get_database() if overwrite or name not in db: if value is None: db.delete(name) print "Deleted %s" % name else: db.set(name, value) print "Set %s to %s" % (name, value) else: print "Key exists!" @baker.command def get(name): "Prints the value of a key in the database." db = get_database() print db.get(name) baker.run()You can then run the script and use your function names and parameters as thecommand line interface, using ``optparse``-style options:: script.pysetalfabravoSetalfatobravo script.py set --overwrite alfa charlie Set alfa to charlie script.pygetalfacharlie script.py --help Available commands: get Prints the value of a key in the database. set Sets the value of a key in the database Use "script.py <command> --help" for individual command help. script.pyset−−helpUsage:script.pyset<name>[<value>]Setsthevalueofakeyinthedatabase.Ifyoudon′tspecifyavalue,thenamedkeyisdeleted.Overwritingavaluemaynotbevisibletoallclientsuntilthenextfullsync.Options:−−overwriteArguments=========Bakermapscommandlineoptionstofunctionparametersinthemostnaturalwayavailable.Bareargumentsareusedtofillinrequiredparameters::@baker.commanddeftest(a,b,c):print"a=",a,"b=",b,"c=",c script.py test 1 2 3 a= 1 b= 2 c= 3``--option`` arguments are used to fill in keyword parameters. You can use``--option value`` or ``--option=value``, as in optparse:: @baker.command def test(key="C"): print "In the key of:", key script.pytestInthekeyof:C script.py test --key A In the key of: A script.pytest−−key=GbInthekeyof:GbFunctionparameterswherethedefaultis‘‘None‘‘areconsideredoptionalargumentsandwillbefilledifextraargumentsareavailable.Otherwise,extrabareargumentsneverfillinkeywordparameters::@baker.commanddeftest(start,end=None,sortby="time"):print"start=",start,"end=",end,"sort=",sortby script.py --sortby name 1 start= 1 end= sortby= name script.py12start=1end=2sortby=timeIfakeywordparameter′sdefaultisanintorfloat,Bakerwilltrytoconverttheoption′sstringtothesametype::@baker.commanddeftest(limit=10):printtype(limit) script.py test --limit 10 <type 'int'>If the default of a parameter is a boolean, the corresponding command lineoption is a flag that sets the opposite of the default:: @baker.command def test(name, verbose=False): if verbose: print "Opening", name script.pytest−−verbosealfaOpeningalfaIfthefunctiontakes‘‘∗‘‘and/or‘‘∗∗‘‘parameters,anyleftoverargumentsandoptionswillfillthemin.Parameterhelp==============Bakerletsyouspecifyhelpforparametersinthreeways.Inthedecorator::@baker.command(params="force":"Deleteevenifthefileexists")defdelete(filename,force=False):"Deletesafile."ifforceornotos.path.exists(filename):os.remove(filename)InPython3.x,youcanuseparameterannotationstoassociatedocstringswithparameters::@baker.commanddefdelete(filename,force:"Deleteevenifthefileexists."=False):"Deletesafile."ifforceornotos.path.exists(filename):os.remove(filename)Bakercanparsethefunction′sdocstringforSphinx−style‘‘:param‘‘blocks::@baker.commanddefdelete(filename,force=False):"""Deletesafile.:paramforce:Deleteevenifthefileexists."""ifforceornotos.path.exists(filename):os.remove(filename)Shortoptions=============Toallowsingle−charactershortoptions(e.g.‘‘−v‘‘for‘‘−−verbose‘‘),usethe‘‘shortopts‘‘keywordonthedecorator::@baker.command(shortopts="verbose":"v",params="verbose","Spewlots")deftest(verbose=False):pass script.py test --help Usage: script.py test Options: -v --verbose Spew lots You can group multiple short flag options together (``-xvc``). You can alsooptionally not put a space between a short option and its argument, forexample ``-nCASE`` instead of ``-n CASE``.``run()`` function==================The ``run()`` function has a few useful options.* ``argv``: the list of options to parse. Default is ``sys.argv``.* ``main``: if True (the default), this function acts like the main function of the module -- it prints errors instead of raising exceptions, prints the return value of the command function, and exits with an error code on errors.* ``help_on_error``: if True, when an error occurs, automatically prints the usage help after the error message. Default is False.* ``outfile``, ``errorfile``, ``helpfile``: the files to use for output, errors, and usage help. Defaults are stdout, stderr, and stdout.* ``errorcode``: if main=True and this value is not 0, calls ``sys.exit()`` with this code in the event of an error``usage()`` function====================Use the ``usage()`` function if you need to print the usage helpprogrammatically:: # Print overall help baker.usage() # Print help for a command baker.usage("commandname") # Print to a file baker.usage("commandname", file=sys.stdout)Miscellaneous=============Instead of ``baker.run()``, you can use ``baker.test()`` to print out howBaker will call your function based on the given command line.As in many UNIX command line utilities, if you specify a single hyphen(``-``) as a bare argument, any subsequent arguments will not parsed asoptions, even if they start with ``--``. Commands are automatically given the same name as the decorated function.To give a command a different name, use the ``name`` keyword on thedecorator. This is especially useful when the command name you wantisn't a valid Python identifier:: @baker.command(name="track-all") def trackall(): passYou can specify a "default" command that is used when the first argumentto the script doesn't look like a command name:: @baker.command(default=True) def here(back=False): print "here! back=", back @baker.command def there(back=False): print "there! back=", back $ script.py --back here! back= True The ``baker`` module contains a ``Baker`` class you can instantiate if youdon't want to use the global functions:: mybaker = baker.Baker() @mybaker.command def test(): print "hello" mybaker.run()About Baker===========Created by Matt Chaput.Released under the`Apache 2.0 license <http://www.apache.org/licenses/LICENSE-2.0>`_Please file bugs in the BitBucket issue tracker.http://bitbucket.org/mchaput/baker