In software engineering, we talk a lot about creating intuitive and delightful user interfaces, which is to say, graphical user interfaces. But what about the command-line? At Ginkgo, our users are scientists and biological engineers, so some of the software that we write are best presented as command-line tools rather than web apps. Click is a powerful and easy-to-use Python library that you can use to create rich command-line interfaces, and I’ll be going over some of its basic features.
The Basics
Getting Started
One of the nice things about Click is that it’s easy to get started, and you can realize a lot of power without much boiler plate at all.
#!/usr/bin/env python3
# hello_world.py
import click
@click.command()
def hello_world():
click.echo('Hello, world!')
if __name__ == '__main__':
hello_world()
The @click.command() decorator is not terrifically useful on its own — it’s a starting point from which we will add more features to our command-line UI. click.echo is very much like print, but the result is more consistent across different terminal environments.
Arguments
We enrich the behavior of our command-line user interface by adding decorators to our main function. For example, we can use the @click.argument() decorator to specify that our “Hello, World!” tool takes an argument name, which will form a part of the greeting:
#!/usr/bin/env python3
import click
@click.argument('name')
@click.command()
def hello_world(name):
click.echo(f'Hello, {name}!')
if __name__ == '__main__':
hello_world()
Now, we can run the tool with the argument:
> ./hello_world.py Ray Hello, Ray!
The decorator @click.argument('name') specifies that the command-line interface takes a single argument, which is passed to the main function as the named argument name.
Options
Specify command-line options also with a decorator:
#!/usr/bin/env python3
import click
@click.option('--punctuation', default='!')
@click.option('--greeting', default='Hello')
@click.argument('name')
@click.command()
def hello_world(name, greeting, punctuation):
click.echo(f'{greeting}, {name}{punctuation}')
if __name__ == '__main__':
hello_world()
Here, we have added two command-line options: --greeting and --punctuation. These options are passed into the command function as keyword arguments greeting and punctuation respectively (where Click generated the keyword argument names by parsing names of the options). We have set default values for both options, in case either option is left out when the command is invoked:
> ./hello_world.py Ray --greeting Bonjour Bonjour, Ray!
We can also set an option as required:
#!/usr/bin/env python3
import click
@click.option('--punctuation', default='!')
@click.option('--greeting', required=True)
@click.argument('name')
@click.command()
def hello_world(name, greeting, punctuation):
click.echo(f'{greeting}, {name}{punctuation}')
if __name__ == '__main__':
hello_world()
So, this time, if we were to leave out the --greeting option:
> ./hello_world.py Ray Usage: hello_world.py [OPTIONS] NAME Try 'hello_world.py --help' for help. Error: Missing option '--greeting'.
As you can see, the command function will not run, and the script quits with an error message and suggestion to invoke the --help option, which brings us to the next feature of Click that we will discuss.
Help Documentation
Click makes it easy to create rich and informative help documentation. Click automatically adds a --help option to all commands (which can be disabled by passing add_help_option=False to @click.command()).
Docstring Integration
Click integrates with Python docstrings to generate descriptions of commands for the help screen:
#!/usr/bin/env python3
import click
@click.option('--punctuation', default='!')
@click.option('--greeting', default='Hello')
@click.argument('name')
@click.command()
def hello_world(name, greeting, punctuation):
"""
Prints a polite, customized greeting to the console.
"""
click.echo(f'{greeting}, {name}{punctuation}')
if __name__ == '__main__':
hello_world()
> ./hello_world.py --help Usage: hello_world.py [OPTIONS] NAME Prints a polite, customized greeting to the console. Options: --greeting TEXT --punctuation TEXT --help Show this message and exit.
Here, by adding a docstring to the command function, we are simultaneously helping developers by documenting our source code, as well as our end-users by providing a useful help screen message.
Documenting Options and Arguments
Document your options by using the help argument:
#!/usr/bin/env python3
import click
@click.option('--punctuation', default='!', help="Punctuation to use to end our greeting.")
@click.option('--greeting', default='Hello', help="Word or phrase to use to greet our friend.")
@click.argument('name')
@click.command()
def hello_world(name, greeting, punctuation):
"""
Prints a polite, customized greeting to the console.
"""
click.echo(f'{greeting}, {name}{punctuation}')
if __name__ == '__main__':
hello_world()
> ./hello_world.py --help Usage: hello_world.py [OPTIONS] NAME Prints a polite, customized greeting to the console. Options: --greeting TEXT Word or phrase to use to greet our friend. --punctuation TEXT Punctuation to use to end our greeting. --help Show this message and exit.
Note that you cannot specify help text for arguments — only options. You can, however, provide a more descriptive help screen by tweaking the metavars:
#!/usr/bin/env python3
import click
@click.option('--punctuation',
default='!',
metavar='PUNCTUATION_MARK',
help="Punctuation to use to end our greeting.")
@click.option('--greeting',
default='Hello',
help="Word or phrase to use to greet our friend.")
@click.argument('name', metavar='NAME_OF_OUR_FRIEND')
@click.command()
def hello_world(name, greeting, punctuation):
"""
Prints a polite, customized greeting to the console.
"""
click.echo(f'{greeting}, {name}{punctuation}')
if __name__ == '__main__':
hello_world()
> ./hello_world.py --help Usage: hello_world.py [OPTIONS] NAME_OF_OUR_FRIEND Prints a polite, customized greeting to the console. Options: --greeting TEXT Word or phrase to use to greet our friend. --punctuation PUNCTUATION_MARK Punctuation to use to end our greeting. --help Show this message and exit.
Types
Click gives us some validation right out of the box with types. For example, you can specify that an argument or option must be an integer:
#!/usr/bin/env python3
import click
@click.option('--punctuation',
default='!',
metavar='PUNCTUATION_MARK',
help="Punctuation to use to end our greeting.")
@click.option('--greeting',
default='Hello',
help="Word or phrase to use to greet our friend.")
@click.option('--number',
default=1,
type=click.INT,
help="The number of times to greet our friend.")
@click.argument('name', metavar='NAME_OF_OUR_FRIEND')
@click.command()
def hello_world(name, greeting, punctuation, number):
"""
Prints a polite, customized greeting to the console.
"""
for _ in range(0, number):
click.echo(f'{greeting}, {name}{punctuation}')
if __name__ == '__main__'
hello_world()
> ./hello_world.py --help Usage: hello_world.py [OPTIONS] NAME_OF_OUR_FRIEND Prints a polite, customized greeting to the console. Options: --number INTEGER The number of times to greet our friend. --greeting TEXT Word or phrase to use to greet our friend. --punctuation PUNCTUATION_MARK Punctuation to use to end our greeting. --help Show this message and exit. > ./hello_world.py --number five Ray Usage: hello_world.py [OPTIONS] NAME_OF_OUR_FRIEND Try 'hello_world.py --help' for help. Error: Invalid value for '--number': 'five' is not a valid integer. > ./hello_world.py --number 5 Ray Hello, Ray! Hello, Ray! Hello, Ray! Hello, Ray! Hello, Ray!
Click gives types that are beyond the primitives like integer, string, etc. You can specify that an argument or option must be a file:
#!/usr/bin/env python3
import click
@click.option('--punctuation',
default='!',
metavar='PUNCTUATION_MARK',
help="Punctuation to use to end our greeting.")
@click.option('--greeting',
default='Hello',
help="Word or phrase to use to greet our friend.")
@click.argument('fh', metavar='FILE_WITH_LIST_OF_NAMES', type=click.File())
@click.command()
def hello_world(greeting, punctuation, fh):
"""
Prints a polite, customized greeting to the console.
"""
for name in fh.readlines():
click.echo(f'{greeting}, {name.strip()}{punctuation}')
if __name__ == '__main__':
hello_world()
The user enters a path to a file for FILE_WITH_LIST_OF_NAMES argument, and click will automatically open the file and pass the handle into the command function. (By default, the file will be open for read, but you can pass other arguments to click.File() to open the file in other ways.) Click fails gracefully if it cannot open the file at the specified path.
> ./hello_world.py ./wrong_file.txt Usage: hello_world.py [OPTIONS] FILE_WITH_LIST_OF_NAMES Try 'hello_world.py --help' for help. Error: Invalid value for 'FILE_WITH_LIST_OF_NAMES': './wrong_file.txt': No such file or directory > ./hello_world.py ./names.txt Hello, Ray! Hello, Ben! Hello, Julia! Hello, Patrick! Hello, Taylor! Hello, David!
Click provides many useful types, and you can even implement your own custom types by subclassing click.ParamType.
Multiple and Nested Commands
Command Groups
The examples so far have included just a single command in our command-line tool, but you can implement several commands to create a more robust tool and richer command-line experience. We can use the click.group() decorator create a “command group”, and then assign several Click “commands” to that group. The main script invokes the command group rather than the command:
#!/usr/bin/env python3
import click
@click.group()
def hello_world():
"""
Engage in a polite conversation with our friend.
"""
pass
@click.option('--punctuation',
default='!',
metavar='PUNCTUATION_MARK',
help="Punctuation to use to end our greeting.")
@click.option('--greeting',
default='Hello',
help="Word or phrase to use to greet our friend.")
@click.argument('name', metavar='NAME_OF_OUR_FRIEND')
@hello_world.command()
def hello(name, greeting, punctuation):
"""
Prints a polite, customized greeting to the console.
"""
click.echo(f'{greeting}, {name}{punctuation}')
@hello_world.command()
def goodbye():
"""
Prints well-wishes for our departing friend.
"""
click.echo('Goodbye, and safe travels!')
if __name__ == '__main__':
hello_world()
In this example, we have moved the functionality of our greeting functionality to a command hello and implemented a new command goodbye. hello_world is now a command group containing these two commands. Click implements a help option for our command group much in the way that it implements them for commands:
> ./hello_world.py --help Usage: hello_world.py [OPTIONS] COMMAND [ARGS]... Engage in a polite conversation with our friend. Options: --help Show this message and exit. Commands: goodbye Prints well-wishes for our departing friend. hello Prints a polite, customized greeting to the console.
The hello command preserves the options, arguments, and documentation that it had when it was the root command.
> ./hello_world.py hello --help Usage: hello_world.py hello [OPTIONS] NAME_OF_OUR_FRIEND Prints a polite, customized greeting to the console. Options: --greeting TEXT Word or phrase to use to greet our friend. --punctuation PUNCTUATION_MARK Punctuation to use to end our greeting. --help Show this message and exit. > ./hello_world.py hello --punctuation . Ray Hello, Ray.
Nesting
We can arbitrarily nest command groups and commands by putting command groups inside of other command groups:
#!/usr/bin/env python3
import click
@click.group()
def hello_world():
"""
Engage in a polite conversation with our friend.
"""
pass
@click.option('--punctuation',
default='!',
metavar='PUNCTUATION_MARK',
help="Punctuation to use to end our greeting.")
@click.option('--greeting',
default='Hello',
help="Word or phrase to use to greet our friend.")
@click.argument('name', metavar='NAME_OF_OUR_FRIEND')
@hello_world.command()
def hello(name, greeting, punctuation):
"""
Prints a polite, customized greeting to the console.
"""
click.echo(f'{greeting}, {name}{punctuation}')
@hello_world.group(name='other-phrases')
def other():
"""
Further conversation with our friend.
"""
pass
@other.command()
def goodbye():
"""
Prints well-wishes for our departing friend.
"""
click.echo('Goodbye, and safe travels!')
@other.command(name='how-are-you')
def how():
"""
Prints a polite inquiry into the well-being of our friend.
"""
click.echo('How are you?')
if __name__ == '__main__':
hello_world()
> ./hello_world.py --help Usage: hello_world.py [OPTIONS] COMMAND [ARGS]... Engage in a polite conversation with our friend. Options: --help Show this message and exit. Commands: hello Prints a polite, customized greeting to the console. other-phrases Further conversation with our friend. > ./hello_world.py other-phrases --help Usage: hello_world.py other-phrases [OPTIONS] COMMAND [ARGS]... Further conversation with our friend. Options: --help Show this message and exit. Commands: goodbye Prints well-wishes for our departing friend. how-are-you Prints a polite inquiry into the well-being of our friend. > ./hello_world.py other-phrases how-are-you How are you?
Notice also that we can give our command groups and commands custom names, if we wish to name our commands and command groups something different from the Python functions that implement them.
Context
You can define options for command groups just as you can for commands. You can then use the Click context object to apply a command group’s options to its commands:
#!/usr/bin/env python3
import click
@click.option('--punctuation',
default='!',
metavar='PUNCTUATION_MARK',
help="Punctuation to use to end our sentences.")
@click.group()
@click.pass_context
def hello_world(ctx, punctuation):
"""
Engage in a polite conversation with our friend.
"""
ctx.ensure_object(dict)
ctx.obj['punctuation'] = punctuation
pass
@click.option('--greeting',
default='Hello',
help="Word or phrase to use to greet our friend.")
@click.argument('name', metavar='NAME_OF_OUR_FRIEND')
@hello_world.command()
@click.pass_context
def hello(ctx, name, greeting):
Prints a polite, customized greeting to the console.
"""
click.echo(f'{greeting}, {name}{ctx.obj["punctuation"]}')
@hello_world.group(name='other-phrases')
def other():
"""
Further conversation with our friend.
"""
pass
@other.command()
@click.pass_context
def goodbye(ctx):
"""
Prints well-wishes for our departing friend.
"""
click.echo(f'Goodbye, and safe travels{ctx.obj["punctuation"]}')
@other.command(name='how-are-you')
@click.pass_context
def how(ctx):
"""
Prints a polite inquiry into the well-being of our friend.
"""
click.echo(f'How are you{ctx.obj["punctuation"]}')
if __name__ == '__main__':
hello_world()
Here, we initialize our context object to a dict, which we can then use to store and retrieve context values (such as the value for the punctuation option of the root command group).
./hello_world.py --help Usage: hello_world.py [OPTIONS] COMMAND [ARGS]... Engage in a polite conversation with our friend. Options: --punctuation PUNCTUATION_MARK Punctuation to use to end our sentences. --help Show this message and exit. Commands: hello Prints a polite, customized greeting to the console. other-phrases Further conversation with our friend > ./hello_world.py --punctuation . hello Ray Hello, Ray. > ./hello_world.py --punctuation ?! other-phrases how-are-you How are you?!
Conclusion
We are really only scratching the surface of what Click can do. For more, check out the Click documentation! I hope this helps you get started in building robust command-line interfaces.
(Feature photo by Sai Kiran Anagani on Unsplash)
