Usage with Setuptools

When writing command line utilities it’s recommended to write them as modules that are distributed with setuptools instead of using UNIX shebangs. There are a bunch of reasons for this.

The first one is that setuptools automatically generates executable wrappers for Windows so your command line utilities work on Windows too.

The second reason is that setuptools scripts work with virtualenv on UNIX without the virtualenv having to be activated. This is a very useful concept which allows you to bundle your scripts with all requirements into a virtualenv.

Introduction

All you need to do to bundle your scripts with setuptools is your script in a python package and a setup.py file.

Imagine this layout:

yourpackage/
    cli.py
setup.py

Contents of cli.py:

import click

@click.command()
def cli():
    """Example script."""
    click.echo('Hello World!')

Contents of setup.py:

from setuptools import setup, find_packages

setup(
    name='yourpackage',
    version='0.1',
    packages=find_packages(),
    include_package_data=True,
    install_requires=[
        'Click',
    ],
    entry_points='''
        [console_scripts]
        yourscript=yourpackage.cli:cli
    ''',
)

The magic is in the entry_points parameter. Below console_scripts each line identifies one console script. The first part before the equals sign (=) is the name of the script that should be generated, the second part is the import path followed by a colon (:) with the click command.

That’s it.

Testing The Script

To test the script you can make a new virtualenv and then install your package:

$ virtualenv venv
$ . venv/bin/activate
$ pip install --editable .

Afterwards your command should be available:

$ yourscript