How to Create Your Own Command Line Programs in Python With Click
Whatsapp Pinterest
Advertisement

Click is a Python package for writing command line interfaces. It produces beautiful documentation for you and lets you build command line interfaces in as little as one line of code. In short: it’s awesome and can help take your programs to the next level.

Here’s how you can use it to liven up your Python projects.

Writing Command Line Programs Without Click

It’s possible to write command line programs without using Click, but doing so requires more effort and lots more code. You need to parse command line arguments, perform validation, develop logic to handle different arguments, and build a custom help menu. Want to add a new option? You’ll be modifying your help function then.

There’s nothing wrong with writing your own code, and doing so is a great way to learn Python, but Click allows you to follow the “Don’t Repeat Yourself” (DRY) principles. Without Click, you’ll write code which is fragile and requires lots of maintenance whenever any changes happen.

Here’s a simple command line interface coded without Click:

import sys
import random

def do_work():
	""" Function to handle command line usage"""
	args = sys.argv
	args = args[1:] # First element of args is the file name

	if len(args) == 0:
		print('You have not passed any commands in!')
	else:
		for a in args:
			if a == '--help':
				print('Basic command line program')
				print('Options:')
				print('    --help -> show this basic help menu.')
				print('    --monty -> show a Monty Python quote.')
				print('    --veg -> show a random vegetable')
			elif a == '--monty':
				print('What\'s this, then? "Romanes eunt domus"? People called Romanes, they go, the house?')
			elif a == '--veg':
				print(random.choice(['Carrot', 'Potato', 'Turnip']))
			else:
				print('Unrecognised argument.')

if __name__ == '__main__':
	do_work()

Python command line interface example

These 27 lines of Python work well but are very fragile. Any change you make to your program will need lots of other supporting code to change. If you change an argument name you’ll need to update the help information. This code can easily grow out of control.

Here’s the same logic with Click:

import click
import random

@click.command()
@click.option('--monty', default=False, help='Show a Monty Python quote.')
@click.option('--veg', default=False, help='Show a random vegetable.')
def do_work(monty, veg):
	""" Basic Click example will follow your commands"""
	if monty:
		print('What\'s this, then? "Romanes eunt domus"? People called Romanes, they go, the house?')

	if veg:
		print(random.choice(['Carrot', 'Potato', 'Turnip']))

if __name__ == '__main__':
	do_work()

This Click example implements the same logic in 16 lines of code. The arguments are parsed for you, and the help screen is generated:

Python Click automatically generated help screen

This basic comparison shows how much time and effort you can save by using programs such as Click. While the command line interface may appear the same to the end user, the underlying code is simpler, and you’ll save lots of time coding. Any changes or updates you write in the future will also see significant development time increases.

Getting Started With Click for Python

Before using Click, you may wish to configure a virtual environment Learn How to Use the Python Virtual Environment Learn How to Use the Python Virtual Environment Whether you are an experienced Python developer, or you are just getting started, learning how to setup a virtual environment is essential for any Python project. Read More . This will stop your Python packages conflicting with your system Python or other projects you may be working on. You could also try Python in your browser Try Python in Your Browser With These Free Online Interactive Shells Try Python in Your Browser With These Free Online Interactive Shells Whether you're going through these Python examples or reviewing the basics of arrays and lists, you can test the code right in your browser. Here are the best online Python interpreters we've found. Read More if you want to play around with Python and Click.

Finally, make sure you’re running Python version 3. It’s possible to use Click with Python version 2, but these examples are in Python 3. Learn more about the differences between Python 2 and Python 3.

Once ready, install Click from the command line using PIP (how to install PIP for Python):

pip install click

Writing Your First Click Program

In a text editor, start by importing Click:

import click

Once imported, create a method and a main entry point. Our Python OOP guide covers these in greater detail, but they provide a place to store your code, and a way for Python to start running it:

import click
import random

def veg():
    """ Basic method will return a random vegetable"""
        print(random.choice(['Carrot', 'Potato', 'Turnip', 'Parsnip']))

if __name__ == '__main__':
    veg()

This very simple script will output a random vegetable. Your code may look different, but this simple example is perfect to combine with Click.

Save this as click_example.py, and then run it in the command line (after navigating to its location):

python click_example.py

You should see a random vegetable name. Let’s improve things by adding Click. Change your code to include the Click decorators and a for loop:

@click.command()
@click.option('--total', default=3, help='Number of vegetables to output.')
def veg(total):
    """ Basic method will return a random vegetable"""
    for number in range(total):
    print(random.choice(['Carrot', 'Potato', 'Turnip', 'Parsnip']))

if __name__ == '__main__':
    veg()

Upon running, you’ll see a random vegetable displayed three times.

Let’s break down these changes. The @click.command() decorator configures Click to work with the function immediately following the decorator. In this case, this is the veg() function. You’ll need this for every method you’d like to use with Click.

The @click.option decorator configures click to accept parameters from the command line, which it will pass to your method. There are three arguments used here:

  1. –total: This is the command line name for the total argument.
  2. default: If you don’t specify the total argument when using your script, Click will use the value from default.
  3. help: A short sentence explaining how to use your program.

Let’s see Click in action. From the command line, run your script, but pass in the total argument like this:

python click_example.py --total 10

By setting –total 10 from the command line, your script will print ten random vegetables.

If you pass in the –help flag, you’ll see a nice help page, along with the options you can use:

python click_example.py --help

Python Click help

Adding More Commands

It’s possible to use many Click decorators on the same function. Add another click option to the veg function:

@click.option('--gravy', default=False, help='Append "with gravy" to the vegetables.')

Don’t forget to pass this into the method:

def veg(total, gravy):

Now when you run your file, you can pass in the gravy flag:

python click_example.py --gravy y

The help screen has also changed:

Python Click help screen

Here’s the whole code (with some minor refactoring for neatness):

import click
import random

@click.command()
@click.option('--gravy', default=False, help='Append "with gravy" to the vegetables.')
@click.option('--total', default=3, help='Number of vegetables to output.')
def veg(total, gravy):
    """ Basic method will return a random vegetable"""
    for number in range(total):
        choice = random.choice(['Carrot', 'Potato', 'Turnip', 'Parsnip'])

        if gravy:
            print(f'{choice} with gravy')
        else:
            print(choice)

if __name__ == '__main__':
    veg()

Even More Click Options

Once you know the basics, you can begin to look at more complex Click options. In this example, you’ll learn how to pass in several values to a single argument, which Click will convert to a tuple. You can learn more about tuples in our guide to the Python dictionary.

Create a new file called click_example_2.py. Here’s the starter code you need:

import click
import random

@click.command()
def add():
    """ Basic method will add two numbers together."""
    pass

if __name__ == '__main__':
    add()

There’s nothing new here. The previous section explains this code in detail. Add a @click.option called numbers:

@click.option('--numbers', nargs=2, type=int, help='Add two numbers together.')

The only new code here are the nargs=2, and the type=int options. This tells Click to accept two values for the numbers option, and that they must both be of type integers. You can change this to any number or (valid) datatype you like.

Finally, change the add method to accept the numbers argument, and do some processing with them:

def add(numbers):
     """ Basic method will add two numbers together."""
     result = numbers[0] + numbers[1]
     print(f'{numbers[0]} + {numbers[1]} = {result}')

Each value you pass in is accessible through the numbers object. Here’s how to use it in the command line:

python click_example_2.py --numbers 1 2

Python Click nargs result

Click Is the Solution for Python Utilities

As you’ve seen, Click is easy to use but very powerful. While these examples only cover the very basics of Click, there are lots more features you can learn about now that you have a solid grasp of the basics.

If you’re looking for some Python projects to practice your new found skills with, why not learn how to control an Arduino with Python How to Program and Control an Arduino With Python How to Program and Control an Arduino With Python Sadly, it is impossible to directly program an Arduino in Python, but you can control it over USB using a Python program. Here's how. Read More , or how about reading and writing to Google Sheets with Python How to Read and Write to Google Sheets With Python How to Read and Write to Google Sheets With Python Python may seem strange and unusual, however it is easy to learn and use. In this article, I'll be showing you how to read and write to Google Sheets using Python. Read More ? Either of these projects would be perfect for converting to Click!

Enjoyed this article? Stay informed by joining our newsletter!

Enter your Email

Leave a Reply

Your email address will not be published. Required fields are marked *

  1. Dave NF2G
    September 29, 2018 at 1:46 pm

    I tried pip install click in Anaconda and it threw several exceptions.

    I tried it in Python and it said "install not defined."

  2. Justin Slay
    September 28, 2018 at 4:26 am

    Someone has never used argparse

  3. Gary Shandling Lives!
    September 27, 2018 at 8:53 pm

    I stopped reading after the overly complex example without click. Either the author isn't familiar with the standard tools at their disposal or they're being intentionally misleading. Either way, I can't trust the rest of the content.

  4. TK
    September 27, 2018 at 3:57 pm

    Argparse is a module in stdlib and can provide almost all of the same functionality as click, but without external dependencies.

    The example "without click" is basically a straw man, there is no good reason to parse args manually like that as opposed to using argparse.

    • Bruce
      September 27, 2018 at 6:32 pm

      I second the use of argparse. It has made my short little utilities cleaner and more complete.

      • Add
        September 28, 2018 at 1:58 am

        I third argparse.
        I also don't like the decorator style of Click. With argparse I define one def that parses in all my args, and then passes those along accordingly. Thus, I only have to look in one spot to update/modify the command line functionality. Also, copy that def into a new project and you have a good base to start with - DRY, as the author said.