Skip to main content

Easy, powerful access to Python functions from the command line

Project description

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 functions
using a simple decorator, to create scripts with "sub-commands", similar to
Django'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 the
command line interface, using ``optparse``-style options::

$ script.py set alfa bravo
Set alfa to bravo

$ script.py set --overwrite alfa charlie
Set alfa to charlie

$ script.py get alfa
charlie

$ 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.py set --help

Usage: script.py set <name> [<value>]

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.

Options:

--overwrite


Arguments
=========

Baker maps command line options to function parameters in the most natural way
available.

Bare arguments are used to fill in required parameters::

@baker.command
def test(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.py test
In the key of: C
$ script.py test --key A
In the key of: A
$ script.py test --key=Gb
In the key of: Gb

Function parameters where the default is ``None`` are considered optional
arguments and will be filled if extra arguments are available. Otherwise,
extra bare arguments never fill in keyword parameters::

@baker.command
def test(start, end=None, sortby="time"):
print "start=", start, "end=", end, "sort=", sortby

$ script.py --sortby name 1
start= 1 end= sortby= name
$ script.py 1 2
start= 1 end= 2 sortby= time

If a keyword parameter's default is an int or float, Baker will try to
convert the option's string to the same type::

@baker.command
def test(limit=10):
print type(limit)

$ script.py test --limit 10
<type 'int'>

If the default of a parameter is a boolean, the corresponding command line
option is a flag that sets the opposite of the default::

@baker.command
def test(name, verbose=False):
if verbose: print "Opening", name

$ script.py test --verbose alfa
Opening alfa

If the function takes ``*`` and/or ``**`` parameters, any leftover arguments
and options will fill them in.


Parameter help
==============

Baker lets you specify help for parameters in three ways.

In the decorator::

@baker.command(params={"force": "Delete even if the file exists"})
def delete(filename, force=False):
"Deletes a file."
if force or not os.path.exists(filename):
os.remove(filename)

In Python 3.x, you can use parameter annotations to associate doc strings
with parameters::

@baker.command
def delete(filename, force:"Delete even if the file exists."=False):
"Deletes a file."
if force or not os.path.exists(filename):
os.remove(filename)

Baker can parse the function's docstring for Sphinx-style ``:param`` blocks::

@baker.command
def delete(filename, force=False):
"""Deletes a file.

:param force: Delete even if the file exists.
"""
if force or not os.path.exists(filename):
os.remove(filename)


Short options
=============

To allow single-character short options (e.g. ``-v`` for ``--verbose``), use
the ``shortopts`` keyword on the decorator::

@baker.command(shortopts={"verbose": "v"}, params={"verbose", "Spew lots"})
def test(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 also
optionally not put a space between a short option and its argument, for
example ``-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 help
programmatically::

# 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 how
Baker 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 as
options, 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 the
decorator. This is especially useful when the command name you want
isn't a valid Python identifier::

@baker.command(name="track-all")
def trackall():
pass

You can specify a "default" command that is used when the first argument
to 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 you
don'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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Baker-1.2.tar.gz (13.1 kB view details)

Uploaded Source

Built Distribution

Baker-1.2-py27-none-any.whl (13.3 kB view details)

Uploaded Python 2.7

File details

Details for the file Baker-1.2.tar.gz.

File metadata

  • Download URL: Baker-1.2.tar.gz
  • Upload date:
  • Size: 13.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for Baker-1.2.tar.gz
Algorithm Hash digest
SHA256 17b344f45387535b000357965ac11619b3381704ffddcfa7df46661901385cc6
MD5 892866d002cc70fdfb1bd24eeb15eacf
BLAKE2b-256 b60f5bdec418f9ebd0183f63b2040813f33d688bd7e9f170d77b00cc006f477c

See more details on using hashes here.

File details

Details for the file Baker-1.2-py27-none-any.whl.

File metadata

  • Download URL: Baker-1.2-py27-none-any.whl
  • Upload date:
  • Size: 13.3 kB
  • Tags: Python 2.7
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for Baker-1.2-py27-none-any.whl
Algorithm Hash digest
SHA256 63c6617a0cd82f5f8f79d93734f283b67b9442dfb9bdfb1c179ab6951399290d
MD5 55c6288481c78fd70aefbc19a2d455b5
BLAKE2b-256 d73c020dab77464653c221e04ef2177c548fb5ddedaab1fe7799679ad2fcf1d8

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page