Полное руководство по настройке setup.py

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

Содержание

• Что такое setup.py?
• Базовая конфигурация setup.py
• Основные параметры и опции
• Требования к структуре проекта
• Современные альтернативы: setup.cfg и pyproject.toml
• Сборка и распространение пакетов
• Лучшие практики и миграция

Что такое setup.py?

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

Скрипт использует функцию setup() из модуля setuptools для указания всей необходимой информации для упаковки. Как объясняет Xebia, это может быть даже пустой пакет; просто убедитесь, что папка пакета существует и содержит файл с именем __init__.py (который может быть пустым).

setup.py традиционно использовался для настройки Python-пакетов, хотя экосистема продолжает развиваться. Как отмечено в Python Developer Tooling Handbook, раньше проекты на setuptools требовали наличия скрипта setup.py в корне проекта. Однако это больше не так в соответствии с современными стандартами упаковки.

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

Базовый файл setup.py обычно импортирует необходимые компоненты и вызывает функцию setup() с ключевыми параметрами. Вот основная структура:

from setuptools import setup, find_packages

setup(
    name="my_package",
    version="0.1.0",
    author="Your Name",
    author_email="your.email@example.com",
    description="Краткое описание вашего пакета",
    packages=find_packages(),
    install_requires=[
        # Перечислите ваши зависимости здесь
        "requests>=2.25.1",
    ],
)

Как демонстрирует разработчик Medium Томас Зиллиокс, параметр install_requires — это место, где вы перечисляете зависимости вашего пакета. В руководстве GeeksforGeeks подчеркивается, что сначала вам нужно создать папку с именем ‘my_package’ с файлом Python с именем ‘init.py’ внутри нее, который будет корнем вашего пакета.

Основные параметры и опции

Функция setup() принимает множество параметров для комплексной настройки вашего пакета. Вот наиболее часто используемые из них:

Основные метаданные

• name: Имя вашего пакета
• version: Номер версии (рекомендуется семантическое версионирование)
• description: Краткое описание пакета
• long_description: Подробное описание (часто из README)
• author: Имя автора
• author_email: Email автора
• url: URL-адрес домашней страницы проекта
• license: Тип лицензии (MIT, Apache и т.д.)

Конфигурация пакета

• packages: Список пакетов для включения
• find_packages(): Автоматически обнаруживает все пакеты
• package_dir: Сопоставление имен пакетов с каталогами
• py_modules: Список отдельных модулей для включения
• package_data: Дополнительные файлы данных для включения

Зависимости и требования

• install_requires: Зависимости времени выполнения
• setup_requires: Зависимости времени сборки
• tests_require: Зависимости для тестирования
• extras_require: Необязательные зависимости

Как показывает практическое руководство Xebia, вы также можете создать файл setup.cfg, чтобы дополнить setup.py дополнительными деталями конфигурации, такими как конфигурация flake8 или настройки тестирования.

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

Для правильного Python-пакета с использованием setup.py требуется определенная структура каталогов. Согласно Xebia, ваш проект должен выглядеть примерно так:

example_project/
├── exampleproject/    # Python-пакет с исходным кодом
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── setup.py
├── README.md
├── LICENSE
└── setup.cfg          # Необязательный файл конфигурации

В руководстве GeeksforGeeks объясняется, что папка пакета должна содержать файл __init__.py, который может быть пустым, чтобы сделать его правильным Python-пакетом. Этот файл может содержать все функции и классы вашего модуля пакета.

Для более сложных проектов Xebia предлагает, что в структуре могут быть другие файлы или папки, такие как папка tests/, файл .gitignore или файл LICENSE, но они не являются строго обязательными.

Современные альтернативы: setup.cfg и pyproject.toml

Хотя setup.py был традиционным подходом, экосистема Python эволюционировала с более современными вариантами конфигурации.

setup.cfg

Как объясняет Иан Хопкинсон, setup.cfg дополняет setup.py, служа файлом конфигурации, который определяет метаданные пакета и другие важные параметры, обычно передаваемые функции setup(). Эта декларативная конфигурация, используемая в setup.cfg, удобнее, чем подход на основе скриптов.

pyproject.toml

Согласно Towards Data Science, начиная с PEP-517 и PEP-518, setuptools больше не является де-факто инструментом, который следует использовать при упаковке Python-проектов. Файл pyproject.toml следует формату TOML и может определять требования к сборке и другие метаданные проекта.

Современный пример pyproject.toml выглядит так:

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

[project]
name = "example"
version = "0.1.0"
description = "Пример пакета"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.25.0",
]

Как отмечено в обновленном руководстве Xebia, указание данных конфигурации в файле pyproject.toml вместо отдельного файла позволяет проектам консолидировать свои конфигурации, уменьшая общее количество файлов конфигурации в проекте.

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

Как только ваш setup.py настроен, вы можете собирать и распространять ваши пакеты с помощью нескольких команд:

Сборка пакетов

• Распространение исходного кода: python setup.py sdist
• Распространение wheel: python setup.py bdist_wheel
• Оба варианта (рекомендуется): python -m build или python -m build --sdist --wheel

Как объясняет Xebia, команда python -m build создаст каталог dist/ и создаст как распределение исходного кода (sdist, с именем example-0.0.1.tar.gz), так и двоичное распределение (wheel, с именем example-0.0.1-py3-none-any.whl).

Установка

Чтобы установить ваш пакет, используйте:

pip install dist/your_package-0.1.0.tar.gz
# или
pip install dist/your_package-0.1.0-py3-none-any.whl

В Python Developer Tooling Handbook подчеркивается, что для установки пакета следует использовать pip install, а не python setup.py install.

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

Как показывает Xebia, вы можете запускать тесты с помощью python setup.py test, если у вас настроены необходимые зависимости в setup.cfg или в скрипте.

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

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

1. Используйте современные инструменты сборки: Предпочитайте python -m build прямым командам python setup.py
2. Контроль версий: Включите ваш пакет в системы контроля версий, такие как Git
3. Семантическое версионирование: Следуйте семантическому версионированию (МАЖОР.МИНОР.ПАТЧ)
4. Полные метаданные: Предоставляйте полную документацию и метаданные
5. Тестирование: Включайте комплексные тесты и требования к тестам

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

Как показывают обсуждения Python.org, многие проекты мигрируют с setup.py на pyproject.toml. Эта миграция включает:

1. Создание файла pyproject.toml с конфигурацией системы сборки
2. Перенос параметров setup() в соответствующие разделы TOML
3. Удаление или минимизация setup.py (может быть пустым для совместимости)

CodeRivers отмечает, что pyproject.toml может определять требования к сборке и другие метаданные проекта и становится все более популярным, так как он следует emerging тенденции использования TOML для конфигурации проекта в экосистеме Python.

Источники

1. A Practical Guide To Using Setup.py | Xebia
2. How to Create Python Package with setup.py | VPK Technologies
3. What is setup.py in Python? - GeeksforGeeks
4. Understanding setup.py, setup.cfg and pyproject.toml in Python – SomeBeans
5. Should I run python setup.py? – Python Developer Tooling Handbook
6. How to Build a Python package? - GeeksforGeeks
7. A Practical Guide To Setuptools And Pyproject.toml | Xebia
8. How to Use Python setup.py | Delft Stack
9. setuptools – Python Developer Tooling Handbook
10. Python Packaging Demystified: Practical Tips for Every Developer | Medium

Заключение

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