3 Python command-line tools

In this month's Python column, learn to write your own command-line apps with the Click, Docopt, and Fire libraries.
309 readers like this.
Tools in a tool box

Photo by Peter (CC BY-SA 2.0), modified by Rikki Endsley

Sometimes the right tool for the job is a command-line application. A command-line application is a program that you interact with and run from something like your shell or Terminal. Git and Curl are examples of command-line applications that you might already be familiar with.

Command-line apps are useful when you have a bit of code you want to run several times in a row or on a regular basis. Django developers run commands like ./manage.py runserver to start their web servers; Docker developers run docker-compose up to spin up their containers. The reasons you might want to write a command-line app are as varied as the reasons you might want to write code in the first place.

For this month's Python column, we have three libraries to recommend to Pythonistas looking to write their own command-line tools.

Click

Click is our favorite Python package for command-line applications. It:

  • Has great documentation filled with examples
  • Includes instructions on packaging your app as a Python application so it's easier to run
  • Automatically generates useful help text
  • Lets you stack optional and required arguments and even several commands
  • Has a Django version (django-click) for writing management commands

Click uses its @click.command() to declare a function as a command and specify required or optional arguments.

# hello.py
import click 

@click.command()
@click.option('--name', default='', help='Your name')
def say_hello(name):
    click.echo("Hello {}!".format(name))

if __name__ == '__main__':
    say_hello()

The @click.option() decorator declares an optional argument, and the @click.argument() decorator declares a required argument. You can combine optional and required arguments by stacking the decorators. The echo() method prints results to the console.

$ python hello.py --name='Lacey'
Hello Lacey!

Docopt

Docopt is a command-line application parser, sort of like Markdown for your command-line apps. If you like writing the documentation for your apps as you go, Docopt has by far the best-formatted help text of the options in this article. It isn't our favorite command-line app library because its documentation throws you into the deep end right away, which makes it a little more difficult to get started. Still, it's a lightweight library that is very popular, especially if exceptionally nice documentation is important to you.

Docopt is very particular about how you format the required docstring at the top of your file. The top element in your docstring after the name of your tool must be "Usage," and it should list the ways you expect your command to be called (e.g., by itself, with arguments, etc.). Usage should include help and version flags.

The second element in your docstring should be "Options," and it should provide more information about the options and arguments you identified in "Usage." The content of your docstring becomes the content of your help text.

"""HELLO CLI

Usage:
    hello.py
    hello.py <name>
    hello.py -h|--help
    hello.py -v|--version

Options:
    <name>  Optional name argument.
    -h --help  Show this screen.
    -v --version  Show version.
"""

from docopt import docopt

def say_hello(name):
    return("Hello {}!".format(name))


if __name__ == '__main__':
    arguments = docopt(__doc__, version='DEMO 1.0')
    if arguments['<name>']:
        print(say_hello(arguments['<name>']))
    else:
        print(arguments)

At its most basic level, Docopt is designed to return your arguments to the console as key-value pairs. If I call the above command without specifying a name, I get a dictionary back:

$ python hello.py 
{'--help': False,
 '--version': False,
 '<name>': None}

This shows me I did not input the help or version flags, and the name argument is None.

But if I call it with a name, the say_hello function will execute.

$ python hello.py Jeff
Hello Jeff!

Docopt allows both required and optional arguments and has different syntax conventions for each. Required arguments should be represented in ALLCAPS or in <carets>, and options should be represented with double or single dashes, like --name. Read more about Docopt's patterns in the docs.

Fire

Fire is a Google library for writing command-line apps. We especially like it when your command needs to take more complicated arguments or deal with Python objects, as it tries to handle parsing your argument types intelligently.

Fire's docs include a ton of examples, but I wish the docs were a bit better organized. Fire can handle multiple commands in one file, commands as methods on objects, and grouping commands.

Its weakness is the documentation it makes available to the console. Docstrings on your commands don't appear in the help text, and the help text doesn't necessarily identify arguments.

import fire


def say_hello(name=''):
    return 'Hello {}!'.format(name)


if __name__ == '__main__':
  fire.Fire()

Arguments are made required or optional depending on whether you specify a default value for them in your function or method definition. To call this command, you must specify the filename and the function name, more like Click's syntax:

$ python hello.py say_hello Rikki
Hello Rikki!

You can also pass arguments as flags, like --name=Rikki.

Bonus: Packaging!

Click includes instructions (and highly recommends you follow them) for packaging your commands using setuptools.

To package our first example, add this content to your setup.py file:

from setuptools import setup

setup(
    name='hello',
    version='0.1',
    py_modules=['hello'],
    install_requires=[
        'Click',
    ],
    entry_points='''
        [console_scripts]
        hello=hello:say_hello
    ''',
)

Everywhere you see hello, substitute the name of your module but omit the .py extension. Where you see say_hello, substitute the name of your function.

Then, run pip install --editable to make your command available to the command line.

You can now call your command like this:

$ hello --name='Jeff'
Hello Jeff!

By packaging your command, you omit the extra step in the console of having to type python hello.py --name='Jeff' and save yourself several keystrokes. These instructions will probably also work for the other libraries we mentioned.

User profile image.
Jeff Triplett is an open source developer and works as a software engineer, consultant, and partner at REVSYS. He is a Board of Director at The Python Software Foundation. He occasionally blogs on his website.
User profile image.
Lacey Williams Henschel is a software engineer with REVSYS and part of the organizing team for DjangoCon US. In the past, she's chaired DjangoCon US, organized several Django Girls workshops, taught courses for Treehouse, and written about accessibility at tech events.

2 Comments

The only thing I would point out is that in its default state, Python is a command line tool. All you need is a text editor and some practice with writing scripts.

I would like to add another tool, similar in spirit to google's Fire.
The is a much simpler library (easier to use, and smaller code base).

mach.py (do in German) allows you to write:

from mach import mach1

@mach1
class Hello:

default = 'greet'

def greet(self, name: str=""):
if not name:
name = input('Your name: ')
print("Hello %s" % name)

if __name__ == '__main__':
Hello().run()

Check http://mach.readthedocs.io/en/latest/ for more extensive examples.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.