Полное руководство по setup.py для разработки Python-пакетов

setup.py: Полное руководство по созданию Python-пакетов

setup.py — это скрипт Python, который служит стандартным файлом конфигурации для определения метаданных пакета, зависимостей и инструкций по сборке в разработке Python-пакетов. Он позволяет разработчикам указывать важную информацию о своем пакете, такую как имя, версия, данные автора и требования, а также предоставляет команды для сборки и распространения пакетов в PyPI. Файл работает в conjunction с setuptools для автоматизации процесса упаковки, что упрощает обмен и установку Python-кода в разных средах.

Содержание

• Понимание setup.py
• Базовая конфигурация setup.py
• Расширенные параметры конфигурации
• Требования к структуре проекта
• Современные альтернативы setup.py
• Сборка и распространение пакетов
• Лучшие практики и миграция

Понимание setup.py

setup.py является фундаментальным компонентом в разработке Python-пакетов, который действует как центральный файл конфигурации для определения того, как пакет должен быть собран, какие метаданные он содержит и как он должен распространяться. Согласно VPK Technologies, setup.py — это “стандартный способ определения метаданных о вашем пакете и его зависимостях.”

Основная цель setup.py — предоставить setuptools (библиотеку для упаковки Python) всей необходимой информацией для:

• Обнаружения и упаковки Python-модулей
• Определения зависимостей пакета
• Генерации дистрибутивов
• Обработки требований установки
• Настройки точек входа для командных инструментов

Как объясняется в руководстве Xebia, файл setup.py по сути служит “центром управления” для вашего Python-пакета, координируя весь процесс упаковки и распространения.

Базовая конфигурация setup.py

Минимальный файл setup.py следует стандартной структуре с использованием setuptools. Вот базовый шаблон конфигурации:

from setuptools import setup, find_packages

VERSION = '0.0.1'
DESCRIPTION = 'Мой первый Python-пакет'
LONG_DESCRIPTION = 'Мой первый Python-пакет с немного более длинным описанием'

setup(
    name="verysimplemodule",
    version=VERSION,
    author="Ваше Имя",
    author_email="<youremail@email.com>",
    description=DESCRIPTION,
    long_description=LONG_DESCRIPTION,
    packages=find_packages(),
    install_requires=[]
)

Ключевые базовые параметры:

• name: Имя пакета, которое должно совпадать с именем папки
• version: Номер версии пакета (обычно следует семантическому версионированию)
• author: Имя автора
• author_email: Email автора
• description: Краткое описание пакета
• long_description: Подробное описание
• packages: Автоматически обнаруживает все пакеты с помощью find_packages()
• install_requires: Список зависимостей, которые необходимо установить вместе с пакетом

Как показано в учебнике freeCodeCamp, эта базовая конфигурация достаточна для большинства простых Python-пакетов, которые вы можете создать.

Расширенные параметры конфигурации

Для более комплексного управления пакетом, setup.py поддерживает множество дополнительных параметров:

setup(
    name="my_package",
    version="1.0.0",
    author="Ваше Имя",
    author_email="email@example.com",
    description="Комплексный Python-пакет",
    long_description=open("README.md").read(),
    long_description_content_type="text/markdown",
    url="https://github.com/username/my_package",
    packages=find_packages(),
    classifiers=[
        "Development Status :: 5 - Production/Stable",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: MIT License",
        "Programming Language :: Python :: 3",
        "Programming Language :: Python :: 3.8",
        "Programming Language :: Python :: 3.9",
        "Programming Language :: Python :: 3.10",
        "Programming Language :: Python :: 3.11",
    ],
    python_requires=">=3.8",
    install_requires=[
        "requests>=2.25.1",
        "numpy>=1.21.0",
        "pandas>=1.3.0",
    ],
    extras_require={
        "dev": ["pytest>=6.0", "black", "flake8"],
        "docs": ["sphinx", "sphinx-rtd-theme"],
    },
    entry_points={
        "console_scripts": [
            "my-package=my_package.cli:main",
        ],
    },
    include_package_data=True,
    zip_safe=False,
)

Ключевые расширенные параметры:

• classifiers: Классификаторы PyPI, которые помогают категоризировать ваш пакет
• python_requires: Минимальная требуемая версия Python
• extras_require: Дополнительные зависимости для разных вариантов использования
• entry_points: Определяет командные инструменты и плагины
• include_package_data: Включает непитоновские файлы, указанные в MANIFEST.in
• url: URL-адрес домашней страницы проекта или репозитория
• long_description_content_type: Формат подробного описания

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

Чтобы setup.py работал правильно, ваш проект должен следовать определенной структуре каталогов. Согласно GeeksforGeeks, вам нужно:

1. Создать папку пакета с файлом __init__.py внутри нее
2. Обеспечить правильную организацию ваших Python-модулей
3. Следовать соглашениям об именовании, которые соответствуют вашей конфигурации setup.py

Типичная структура проекта выглядит так:

my_project/
├── setup.py
├── README.md
├── MANIFEST.in
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   ├── module2.py
│   └── subpackage/
│       ├── __init__.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   └── test_module1.py
└── docs/
    └── source/
        ├── conf.py
        └── index.rst

Ключевые структурные требования:

• Папка пакета: Должна содержать __init__.py (даже если он пустой)
• Расположение setup.py: Должно быть в корневом каталоге проекта
• README.md: Обычно ссылается в setup.py для подробного описания
• MANIFEST.in: Указывает дополнительные файлы для включения в дистрибутив

Важно: Файл __init__.py — это то, что делает каталог Python-пакетом. Он может быть пустым или содержать код инициализации пакета, но он должен присутствовать, чтобы find_packages() мог обнаружить ваши модули.

Современные альтернативы setup.py

Хотя setup.py был традиционным стандартом, упаковка Python эволюционирует в сторону более современных подходов. Как отмечено в обновленном руководстве Xebia, “рекомендуемый способ использования Setuptools сместился в сторону использования Pyproject.toml вместо setup.py и setup.cfg.”

pyproject.toml

Современной альтернативой является pyproject.toml, который служит “единственным источником правды для метаданных проекта” согласно PyDevTools.

Вот минимальный пример pyproject.toml:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "mypkg"
description = "действительно крутой пакет."
keywords = ["случайный", "крутой"]
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Environment :: Console",
    "Intended Audience :: Science/Research",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
]
requires-python = ">=3.7"
dynamic = ["version", "readme"]

[tool.setuptools.dynamic]
readme = {file = ["README.md"], content-type = "text/markdown"}
version = {attr = "mypkg.__version__"}

[project.optional-dependencies]
dev = ["pytest>=6.0", "black", "flake8"]
docs = ["sphinx", "sphinx-rtd-theme"]

Ключевые преимущества pyproject.toml:

• Соответствие PEP: Следует современным стандартам упаковки (PEP-517, PEP-518, PEP-621)
• Единая конфигурация: Объединяет метаданные, которые ранее были разбросаны по нескольким файлам
• Лучшая поддержка инструментов: Родная поддержка в современных инструментах сборки Python
• Статический анализ: Легче для инструментов парсить и проверять конфигурацию

Когда использовать setup.py vs pyproject.toml:

Примечание: Согласно Ian Hopkinson, по состоянию на май 2023 года, “параметры проекта, ранее находившиеся в setup.cfg, теперь могут быть в pyproject.toml, в соответствии с PEP-621.”

Сборка и распространение пакетов

Как только ваш setup.py настроен, вы можете использовать его для сборки и распространения вашего Python-пакета. Процесс включает несколько ключевых команд:

Базовые команды сборки

1. Сборка исходного дистрибутива:

   bash

   python setup.py sdist
   

2. Сборка wheel-дистрибутива (рекомендуется):

   bash

   python setup.py bdist_wheel
   

3. Сборка обоих форматов:

   bash

   python setup.py sdist bdist_wheel
   

Загрузка в PyPI

Чтобы опубликовать ваш пакет в Индексе пакетов Python (PyPI):

python setup.py sdist upload -r pypi

Однако современный подход — использовать twine для более безопасной загрузки:

# Сначала соберите дистрибутивы
python setup.py sdist bdist_wheel

# Затем загрузите с помощью twine
twine upload dist/*

Варианты установки

setup.py также включает различные режимы установки:

1. Стандартная установка:

   bash

   pip install .
   

2. Редактируемая установка (режим разработки):

   bash

   pip install -e .
   

   Как упоминается в руководстве Ian Hopkinson, редактируемая установка означает, что “изменения в коде немедленно отразятся в функциональности пакета.”

3. Установка с дополнительными компонентами:

   bash

   pip install .[dev,docs]
   

Лучшая практика: Всегда используйте виртуальные среды при работе с Python-пакетами для избежания конфликтов зависимостей. Как рекомендует Xebia, “Это общепринятая и рекомендуемая практика использовать виртуальные среды для работы в Python.”

Лучшие практики и миграция

При работе с setup.py следует соблюдать несколько лучших практик для обеспечения поддерживаемости и будущей совместимости упаковки:

Текущие лучшие практики

1. Используйте контроль версий: Храните ваш setup.py в системе контроля версий вместе с кодом вашего пакета
2. Автоматизируйте сборки: Используйте CI/CD конвейеры для автоматической сборки и тестирования пакетов
3. Документируйте зависимости: Сохраняйте requirements.txt для разработки вместе с setup.py
4. Тщательно тестируйте: Используйте инструменты вроде tox для тестирования на нескольких версиях Python
5. Следуйте семантическому версионированию: Используйте осмысленные номера версий, отражающие изменения

Миграция на современные стандарты

Для проектов, в настоящее время использующих setup.py, рассмотрите возможность перехода на pyproject.toml:

1. Начните с простого: Начните с базовой конфигурации pyproject.toml
2. Постепенная миграция: Перемещайте конфигурацию частями
3. Сохраняйте совместимость: Сохраняйте setup.py в период перехода, если необходимо
4. Обновите инструменты: Современизируйте ваш конвейер сборки и развертывания
5. Тщательно тестируйте: Убедитесь, что вся функциональность работает с новой конфигурацией

Будущие соображения

По мере продолжения эволюции упаковки Python, учтите эти будущие тенденции:

• PEP 621: Стандартная спецификация метаданных для pyproject.toml
• Бэкенды сборки: Переход за пределы setuptools для специализированных потребностей сборки
• Разрешение зависимостей: Улучшенные инструменты управления зависимостями
• Улучшения безопасности: Лучшие механизмы подписи и проверки

Согласно PyDevTools, “Setuptools можно настроить через pyproject.toml или устаревший файл setup.py”, что указывает на то, что оба подхода останутся поддерживаемыми в обозримом будущем.

Заключение

setup.py остается фундаментальным инструментом в разработке Python-пакетов, служащим традиционным файлом конфигурации, который определяет метаданные пакета, зависимости и инструкции по сборке. Хотя более новые альтернативы, такие как pyproject.toml, набирают популярность, понимание setup.py все еще необходимо для работы с существующими Python-пакетами и поддержания совместимости в разных средах.

Ключевые выводы включают:

• setup.py работает с setuptools для автоматизации упаковки и распространения
• Он использует параметры, такие как name, version, author и dependencies, для определения метаданных пакета
• Требования к структуре проекта включают правильную организацию пакетов с файлами init.py
• Современные альтернативы, такие как pyproject.toml, предлагают улучшенное управление конфигурацией
• Сборка и распространение пакетов включает команды, такие как python setup.py sdist и twine upload
• Виртуальные среды рекомендуются для всей работы по разработке пакетов

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

Источники

1. A Practical Guide To Using Setup.py | Xebia
2. How to Build Your Very First Python Package | freeCodeCamp
3. What is setup.py in Python? | GeeksforGeeks
4. Understanding setup.py, setup.cfg and pyproject.toml in Python | SomeBeans
5. How to Create Python Package with setup.py | VPK Technologies
6. A Practical Guide To Setuptools And Pyproject.toml | Xebia
7. An Updated Guide To Setuptools And Pyproject.toml | Xebia
8. setuptools – Python Developer Tooling Handbook
9. Why Should I Choose pyproject.toml over requirements.txt? | PyDevTools
10. Python minimal package with pyproject.toml | Scientific Computing