captain 2.0.3

python cli scripts for humans

Easy python cli scripts for people that just want get things done.

Captain was lovingly crafted for First Opinion and powers all our command line scripts.

Usage

A valid captain cli script needs just two things:

1. A main function

   def main(foo, bar):
       return 0

2. Calling exit using captain.exit()

   import captain
   
   def main(foo, bar):
       return 0
   
   captain.exit()

That’s it! Whatever arguments you define in the main function will be options on the command line. A captain script is called just like any other python command line script, so to run the above example you could do:

$ python path/to/script.py --foo=1 --bar=2

Argument Decorator

The captain.decorators.arg() decorator provides a nice passthrough api to the full argparse module if you need to really customize how arguments are passed into your script:

from captain import exit
from captain import echo
from captain.decorators import arg


@arg('--foo', '-f')
@arg('arg', metavar='ARG')
def main(*args, **kwargs):
    '''this is the help description'''
    echo.out(args)
    echo.out(kwargs)

exit()

Would print a help string like this:

usage: script.py [-h] [--foo FOO] ARG

this is the help description

positional arguments:
  ARG

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

If you want another nifty way to define arguments, take a look at docopt.

Echo

This small module makes it easy to print stuff in your script while still giving you full control by being able to configure the logger if you need to. It also will obey the global --quiet flag.

from captain import echo

var1 = "print"

var2 = "stdout"
echo.out("this will {} to {}", var1, var2)

var2 = "stderr"
echo.err("this will {} to {}", var1, var2)

e = ValueError("this will print with stacktrace and everything")
echo.exception(e)

The echo module has a lot of nice little helper features but Captain also can work with modules like clint if you need to do more advanced cli output.

Examples

A typical standard python cli script

import argparse

if __name__ == u'__main__':
    parser = argparse.ArgumentParser(description='fancy script description')
    parser.add_argument("--foo", action='store_true')
    parser.add_argument("--bar", default=0, type=int)
    parser.add_argument("args", nargs='*')
    args = parser.parse_args()

would become:

import captain

def main(foo=False, bar=0, *args):
    '''fancy script description'''
    return 0

captain.exit()

Subcommands

Captain supports multiple subcommands defined in the script using the format main_subcommand.

# cli.py

import captain

def main_foo():
    pass

def main_bar():
    pass

captain.exit()

So foo could be called using:

$ python cli.py foo

And bar could be called using:

$ python cli.py bar

Embedding captain in another package

If you want a script from you package to be usable using both python -m example and maybe a console_scripts entry point, you can set up your package’s __main__.py module like this:

# example/__main__.py

from captain import exit as console

def main():
    pass

console()

And then in your setup.py script you can add:

entry_points = {
    'console_scripts': [
        'example = example.__main__:console'
    ],
}

That’s all there is to it.

Easy listing of all captain scripts in a directory

You can get a list of all available scripts in a directory by running captain with no arguments:

$ captain

Install

Use pip:

$ pip install captain