Интеграция Setuptools

При написании утилит командной строки рекомендуется писать их в виде модулей, распространяемых с помощью setuptools, вместо использования Unix shebang.

Почему это нужно? Есть несколько причин:

Одна из проблем традиционного подхода заключается в том, что первый модуль, загружаемый интерпретатором Python, имеет неверное имя. Это может показаться незначительной проблемой, но она имеет довольно серьезные последствия.

Первый модуль называется не своим фактическим именем, а интерпретатор переименовывает его в __main__. Хотя это совершенно допустимое имя, это означает, что если другой фрагмент кода захочет импортировать из этого модуля, он вызовет импорт второй раз под своим истинным именем, и внезапно ваш код импортируется дважды.
Не на всех платформах вещи легко исполняются. В Linux и OS X вы можете добавить комментарий в начало файла (#!/usr/bin/env python) и ваш скрипт работает как исполняемый файл (предполагается, что у него установлен исполняемый бит). Однако это не работает в Windows. Хотя в Windows вы можете ассоциировать интерпретаторы с расширениями файлов (например, чтобы все, заканчивающиеся на .py, выполнялись через интерпретатор Python), вы столкнетесь с проблемами, если захотите использовать скрипт в virtualenv.

Фактически, выполнение скрипта в virtualenv является проблемой и для OS X, и для Linux. При традиционном подходе вам необходимо активировать весь virtualenv, чтобы использовать правильный интерпретатор Python. Не очень удобно для пользователя.
Основной трюк работает только если скрипт является модулем Python. Если ваше приложение слишком велико, и вы захотите использовать пакет, вы столкнетесь с проблемами.

Введение

Для объединения вашего скрипта с setuptools вам нужен только скрипт в пакете Python и файл setup.py.

Представьте себе следующую структуру каталогов:

yourscript.py
setup.py

Содержание файла yourscript.py:

import click

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

Содержание файла setup.py:

from setuptools import setup

setup(
    name='yourscript',
    version='0.1.0',
    py_modules=['yourscript'],
    install_requires=[
        'Click',
    ],
    entry_points={
        'console_scripts': [
            'yourscript = yourscript:cli',
        ],
    },
)

Магия заключается в параметре entry_points. Обратитесь к полному спецификации entry_points для получения более подробной информации. Под console_scripts, каждая строка определяет одну консольную утилиту. Первая часть перед знаком равенства (=) - это имя генерируемой утилиты, вторая часть - путь импорта, за которым следует двоеточие (:) с командой Click.

Вот и все.

Тестирование скрипта

Чтобы протестировать скрипт, вы можете создать новую virtualenv, а затем установить свой пакет:

$ python3 -m venv .venv
$ . .venv/bin/activate
$ pip install --editable .

После этого ваша команда должна быть доступна:

$ yourscript
Hello World!

Скрипты в пакетах

Если ваш скрипт растет, и вы хотите переключиться на хранение вашего скрипта в пакете Python, необходимые изменения минимальны. Предположим, ваша структура каталогов изменилась на следующую:

project/
    yourpackage/
        __init__.py
        main.py
        utils.py
        scripts/
            __init__.py
            yourscript.py
    setup.py

В этом случае вместо использования py_modules в вашем файле setup.py вы можете использовать packages и автоматическую поддержку поиска пакетов setuptools. Кроме того, рекомендуется включать и другие данные пакета.

Вот измененное содержимое файла setup.py:

from setuptools import setup, find_packages

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