Noah Gift - Python Command Line Tools

Alfredo Deza

Building command-line tools is fun. For me, though, and for the longest time, it meant struggling with the different types of libraries Python had to offer. It all began with optparse, which is deprecated since Python 2.7, and it is unfortunately still in the standard library after all these years. It was replaced with argparse which, as you will see soon, it is still complicated to deal with. It is crucial to understand what Python has to offer to grasp why the alternative (the Click framework) is better.

Click is a project created by Armin Ronacher. If you havent heard of him before, you probably have heard about projects he created or co-authored:

- Pygments: Syntax highlighter
- Jinja: Templating engine
- Sphinx: Documentation framework
- Werkzeug: Server and web utility
- Babel: Internationalization library
- MarkupSafe: Safely cleans up HTML strings
- Flask: Web framework
- itsdangerous: Cryptographic library

Ive used most of these before, and have had nothing but great experiences with them. What brings us to this chapter is Click and how to get started creating powerful tooling with it.

The standard library offerings (via optparse and argparse) work fine. From this point forward, Ill briefly touch on argparse only since optparse is deprecated (I strongly suggest you avoid it). My problem with argparse is that it is tough to reason about, and it wasnt created to support some of the use cases the Click supports. One of these examples is sub-commands. Lets build a command-line

Crafting the tool requires dealing with a class called ArgumentParser and then adding to it. I dont have anything against classes, but this reads convoluted, to say the least. Save it as sub-commands.py and run it to see how it behaves:

What are positional arguments ? I explicitly followed the documentation to add sub-commands (called sub_parsers in the code), why are these referred to as positional arguments? They arent! These are sub-commands. If you use them as a sub-command in the terminal you can verify this:

This is not good. Aside from how complex it is to deal with an instantiated class that grows with sub-commands, the implementation doesnt match what it advertises. In essence, the sub-command is calling add_subparsers(), and they display in the help output as positional arguments which are sub-commands.

It is entirely possible to change the help output to force it to say something else, but this misses the point. I found the sub-command handling of argparse so rough that I ended up creating a small library that attempts to make it a bit easier. Even though that little library is in a few production tools, I would recommend you take a close look to Click, because it does everything that argparse does, and makes it simpler - including sub-commands.

Even if you arent going to use sub-commands at all, the interface to the class and objects that configure the command-line application creates much friction. It has taken me a while to find a suitable alternative, and although Click has been around for quite some time, it hasnt been until recently that Ive acknowledged how good it is.

The simplest use case for Click has a caveat: it doesnt handle the help menu in a way that I prefer when building command-line tools. Have you ever tried a tool that doesnt allow -h? How about it does allow -h but doesnt like --help? What about one that doesnt like -h, --help, or help?

Perhaps Im raising the bar too high and find is too old of a tool? Lets try with some modern ones:

Do you think this level of helpfulness is over the top? Some tools do work with all three of them, like Skopeo and Coverage.py. Not only is it possible to be that helpful, but it should also be a priority if you are creating a new tool. As I mentioned, Click doesnt do all three by default, but it doesnt take much effort to get them all working. There are lots of basic examples for Click, and in this section, Ill concentrate on creating one that allows all these help menus to show.

Starting with the most basic example so that we can check what is missing and then go fix it up, save the example as cli.py: