Writing a Python Click CLI without decorators

Introduction

Click is my favourite Python CLI library. Click simplifies the process of writing a command-line app: it handles argument parsing, subcommand structuring, and creating help text.

I’ve found that the standard library’s argparse works well for simple, zero-dependency scripts but if I’m writing a script which requires dependencies or if my script is starting to scale beyond a single command, I switch to Click.

Here’s a Hello World example of Click. For a more in-depth introduction see the official documentation.

Click example

To get started, you must first install Click by running the following command.

pip install click

Then, create a file containing our example script (e.g. script.py).

import click


@click.command()
@click.option("--count", default=1, help="Number of greetings.")
@click.option("--name", prompt="Your name", help="The person to greet.")
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for x in range(count):
        click.echo(f"Hello {name}!")


if __name__ == "__main__":
    hello()

Finally, you can run the script by invoking the Python file.

python script.py

This simple example follows Click’s recommended style of using decorators. Some people would consider this a very Pythonic interface.

This example also shows that Click requires much less effort compared to argparse and allows you to focus on the functionality of your script, not the CLI.

However, from my experience using the recommended style of decorators for groups and commands doesn’t scale well. I found the complexity increases greatly in the following situations:

Restructuring your CLI into entrypoints and services
Injecting dependencies
Providing more fine-grained error handling
Composing commands out of other commands

Click does provide solutions to these issues, however this requires using more Click-specific techniques. The documentation explains how to do this, but personally this is starting to get a bit too magic, and I’d prefer to explicitly handle this myself.

To implement this, I use higher-order-functions, this is a functional programming technique where functions are treated as first class values and can be given to, and returned from, methods. This is opposite to Click’s decorator approach as the decorators don’t let you modify the functions being wrapped or access the function created by the decorator. To fix this, I use the underlying Click functions to explicitly create and register my commands.

Explicitly creating commands

This snippet shows how the Hello World example from the start of this article can be rewritten to explicitly create the command.

import click


def hello(count, name):
    for x in range(count):
        click.echo(f"Hello {name}!")


hello_cmd = click.Command(
    name=None,
    callback=hello,
    params=[
        click.Option(["--count"], default=1, help="Number of greetings."),
        click.Option(["--name"], prompt="Your name", help="The person to greet."),
    ],
    help="Simple program that greets NAME for a total of COUNT times",
)

if __name__ == "__main__":
    hello_cmd()

This works by creating an instance of the click.Command class and providing it with a function to invoke, options for the command, help text, and an empty name as we don’t need to give top-level commands names.

This allows you to start manipulating the callback function of commands allowing a more flexible programming style. For example, from here you can wrap the command implementation with dependency injections and error handling.

Extra tips

There are more lessons I’ve learnt from using this approach in a few projects, so I’ll share a few of them here.

Command factory pattern

In order to keep complexity down as the application scales, I like to to use the factory pattern to produce an instance of click.Group. This is similar to Flask’s (another excellent pallets project) blueprints. Different parts of the application know how to produce their own CLIs and the compositional root can combine them into one CLI, this reduces complexity.

import click


def hello(count, name):
    for x in range(count):
        click.echo(f"Hello {name}!")


def make_cli() -> click.Group:
    parent_cmd = click.Group()

    parent_cmd.add_command(
        click.Command(
            name="greet",
            callback=hello,
            params=[
                click.Option(["--count"], default=1, help="Number of greetings."),
                click.Option(
                    ["--name"], prompt="Your name", help="The person to greet."
                ),
            ],
            help="Simple program that greets NAME for a total of COUNT times",
        )
    )

    return parent_cmd


if __name__ == "__main__":
    command_group = make_cli()
    command_group()

You can arbitrary add instances of click.Command to the click.Group instance and combine multiple groups into one by using the click.CommandCollection([group1, group2, ...]) function.

This helps you split your application into smaller, more understandable parts.

Manually registering help text

In all of our examples we’ve used a string literal to specify what a command’s help text should be. However the click.command decorator automatically creates help text from the wrapped function’s docstring. In order to replicate this functionality we can manually set the help text for a command to be the callback function’s __doc__ attribute.

import click


def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times"""
    for x in range(count):
        click.echo(f"Hello {name}!")


hello_cmd = click.Command(
    name=None,
    callback=hello,
    params=[
        click.Option(["--count"], default=1, help="Number of greetings."),
        click.Option(["--name"], prompt="Your name", help="The person to greet."),
    ],
    help=hello.__doc__,
)

if __name__ == "__main__":
    hello_cmd()

Conclusion

When I was working on larger CLIs, I couldn’t find any well-documented alternatives to Click’s suggested decorator style. Hopefully this short article provides that alternative, and helps you write more scalable command line applications.

Looking beyond the techniques in this article, this approach is starting to resemble Scott Wlaschin’s Railway Oriented Programming which inspired the Giraffe F# web framework. Using the Result monad we would be able to define our application’s layers (validation, service logic, presentation layer) as Result[T, Error] -> Result[T, Error] functions. This would allow arbitrary composition and short-circuiting on errors. This is something I’d like to explore in a later post.

Introduction#

Click example#

Explicitly creating commands#

Extra tips#

Command factory pattern#

Manually registering help text#

Conclusion#