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 many 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

To bundle your script with setuptools, all you need is the script in a Python package and a setup.py file.

Imagine this directory structure:

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