Подробное сравнение setup.py и pyproject.toml для управления пакетами Python, охватывающее лучшие практики, стратегии миграции и современные инструменты.
Структура пакетов Python: Setup.py против Pyproject.toml — Подробное руководство
На протяжении многих лет файл setup.py был краеугольным камнем управления пакетами Python. Однако ландшафт изменился, и pyproject.toml стал современной альтернативой. Это подробное руководство исследует различия между этими двумя подходами, помогая вам понять, какой из них подходит для вашего проекта и как эффективно управлять вашими пакетами Python.
Понимание основ
Что такое пакет Python?
Пакет Python — это способ организации и распространения вашего кода на Python. Он позволяет группировать связанные модули в иерархию каталогов, делая ваш код более модульным, многоразовым и поддерживаемым. Пакеты необходимы для обмена кодом с другими и для управления зависимостями в ваших проектах.
Роль метаданных пакета
Метаданные пакета предоставляют важную информацию о вашем пакете, такую как его имя, версия, автор, зависимости и точки входа. Эти метаданные используются менеджерами пакетов, такими как pip, для установки, обновления и управления вашими пакетами. Исторически setup.py был основным способом определения этих метаданных.
Setup.py: Традиционный подход
Что такое Setup.py?
setup.py — это скрипт Python, который использует библиотеку setuptools для определения структуры и метаданных вашего пакета. Это динамически выполняемый файл, что означает, что он запускает код Python для настройки пакета.
Ключевые компоненты Setup.py
Типичный файл setup.py включает следующие компоненты:
- Имя пакета: Имя вашего пакета (например,
my_package). - Версия: Номер версии вашего пакета (например,
1.0.0). - Информация об авторе и сопровождающем: Подробная информация об авторе и сопровождающем пакета.
- Зависимости: Список других пакетов, от которых зависит ваш пакет (например,
requests >= 2.20.0). - Точки входа: Определения для скриптов командной строки или других точек входа в ваш пакет.
- Данные пакета: Файлы, не являющиеся кодом (например, файлы конфигурации, файлы данных), которые должны быть включены в пакет.
Пример Setup.py
```python from setuptools import setup, find_packages setup( name='my_package', version='1.0.0', author='John Doe', author_email='john.doe@example.com', description='A simple Python package', packages=find_packages(), install_requires=[ 'requests >= 2.20.0', ], entry_points={ 'console_scripts': [ 'my_script = my_package.module:main', ], }, classifiers=[ 'Programming Language :: Python :: 3', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', ], ) ```Преимущества Setup.py
- Привычность: Это традиционный и хорошо известный подход, поэтому многие разработчики уже знакомы с ним.
- Гибкость: Поскольку это скрипт Python, он предлагает высокую степень гибкости. Вы можете выполнять сложную логику и настраивать процесс сборки по мере необходимости.
- Расширяемость: Setuptools предоставляет богатый набор функций и может быть расширен пользовательскими командами и расширениями.
Недостатки Setup.py
- Динамическое выполнение: Динамический характер
setup.pyможет представлять угрозу безопасности, поскольку он выполняет произвольный код во время процесса сборки. - Неявные зависимости:
setup.pyчасто опирается на неявные зависимости, такие как сам setuptools, что может привести к несоответствиям и ошибкам. - Сложность: Для сложных проектов
setup.pyможет стать большим и трудным для поддержки. - Ограниченная декларативная конфигурация: Большая часть метаданных пакета определяется императивно, а не декларативно, что затрудняет их понимание.
Pyproject.toml: Современная альтернатива
Что такое Pyproject.toml?
pyproject.toml — это файл конфигурации, который использует формат TOML (Tom's Obvious, Minimal Language) для определения системы сборки и метаданных вашего пакета. Это декларативный подход, что означает, что вы указываете, что вы хотите достичь, а не как это сделать.
Ключевые разделы Pyproject.toml
Типичный файлpyproject.toml включает следующие разделы:
[build-system]: Определяет используемую систему сборки (например,setuptools,poetry,flit).[project]: Содержит метаданные о проекте, такие как его имя, версия, описание, авторы и зависимости.[tool.poetry]или[tool.flit]: Разделы для конфигураций, специфичных для инструментов (например, Poetry, Flit).
Пример Pyproject.toml (с Setuptools)
```toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = [ { name = "John Doe", email = "john.doe@example.com" } ] dependencies = [ "requests >= 2.20.0", ] [project.scripts] my_script = "my_package.module:main" [project.optional-dependencies] dev = [ "pytest", "flake8", ] [project.classifiers] classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.urls] homepage = "https://example.com" repository = "https://github.com/example/my_package" ```Пример Pyproject.toml (с Poetry)
```toml [tool.poetry] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = ["John DoeПреимущества Pyproject.toml
- Декларативная конфигурация:
pyproject.tomlпредоставляет декларативный способ определения метаданных вашего пакета, что упрощает понимание и поддержку. - Стандартизированная система сборки: Она указывает используемую систему сборки, обеспечивая согласованные сборки в различных средах.
- Улучшенное управление зависимостями: Такие инструменты, как Poetry и Pipenv, легко интегрируются с
pyproject.toml, предоставляя надежные функции управления зависимостями. - Снижение рисков безопасности: Поскольку это статический файл конфигурации, он устраняет риски безопасности, связанные с динамическим выполнением кода во время процесса сборки.
- Интеграция с современными инструментами:
pyproject.tomlявляется стандартом для современных инструментов упаковки Python, таких как Poetry, Pipenv и Flit.
Недостатки Pyproject.toml
- Кривая обучения: Разработчикам может потребоваться изучить новый синтаксис (TOML) и новый подход к управлению пакетами.
- Ограниченная гибкость: Он может не подходить для сильно настраиваемых процессов сборки, требующих сложной логики.
- Зависимость от инструментов: Вам придется выбрать и научиться использовать определенную систему сборки (например, Setuptools, Poetry, Flit).
Сравнение Setup.py и Pyproject.toml
Вот таблица, обобщающая основные различия между setup.py и pyproject.toml:
| Особенность | Setup.py | Pyproject.toml |
|---|---|---|
| Стиль конфигурации | Императивный (код Python) | Декларативный (TOML) |
| Система сборки | Неявная (Setuptools) | Явная (указывается в [build-system]) |
| Безопасность | Потенциально менее безопасный (динамическое выполнение) | Более безопасный (статическая конфигурация) |
| Управление зависимостями | Базовое (install_requires) |
Продвинутое (интеграция с Poetry, Pipenv) |
| Инструментарий | Традиционный (Setuptools) | Современный (Poetry, Pipenv, Flit) |
| Гибкость | Высокая | Умеренная |
| Сложность | Может быть высокой для сложных проектов | Обычно ниже |
Стратегии миграции: От Setup.py к Pyproject.toml
Миграция от setup.py к pyproject.toml может показаться сложной, но это стоящая инвестиция для долгосрочной поддерживаемости и согласованности. Вот несколько стратегий, которые вы можете использовать:
1. Начните с минимального Pyproject.toml
Создайте базовый файл pyproject.toml, который определяет систему сборки, а затем постепенно перенесите метаданные из setup.py в pyproject.toml.
2. Использование Setuptools с Pyproject.toml
Продолжайте использовать Setuptools в качестве вашей системы сборки, но определяйте метаданные проекта в pyproject.toml. Это позволит вам использовать преимущества pyproject.toml, при этом продолжая работать с привычным инструментом.
3. Миграция на современный инструмент, такой как Poetry
Рассмотрите возможность миграции на современный инструмент, такой как Poetry или Pipenv. Эти инструменты предоставляют обширные функции управления зависимостями и легко интегрируются с pyproject.toml.
Пример: Миграция на Poetry
- Установите Poetry:
pip install poetry - Инициализируйте Poetry в вашем проекте:
poetry init(Это поможет вам создать файлpyproject.toml) - Добавьте ваши зависимости:
poetry add requests(или любые другие зависимости) - Соберите ваш пакет:
poetry build
4. Используйте инструменты для автоматической миграции
Некоторые инструменты могут помочь автоматизировать процесс миграции. Например, вы можете использовать инструменты для преобразования файла setup.py в файл pyproject.toml.
Лучшие практики управления пакетами Python
1. Используйте виртуальное окружение
Всегда используйте виртуальное окружение для изоляции зависимостей вашего проекта от общесистемной установки Python. Это предотвращает конфликты и гарантирует, что ваш проект имеет правильные зависимости.
Пример использования venv:
Пример использования conda:
2. Точно указывайте зависимости
Используйте ограничения версий для указания совместимых версий ваших зависимостей. Это предотвращает неожиданное поведение, вызванное несовместимыми обновлениями библиотек. Используйте такие инструменты, как pip-tools, для управления вашими зависимостями.
Пример спецификации зависимости:
``` requests >= 2.20.0, < 3.0.0 ```3. Используйте согласованную систему сборки
Выберите систему сборки (например, Setuptools, Poetry, Flit) и придерживайтесь ее. Это обеспечивает согласованные сборки в различных средах и упрощает процесс упаковки.
4. Документируйте ваш пакет
Напишите четкую и краткую документацию для вашего пакета. Это поможет пользователям понять, как использовать ваш пакет, и упростит для других вклад в ваш проект. Используйте такие инструменты, как Sphinx, для генерации документации из вашего кода.
5. Используйте непрерывную интеграцию (CI)
Настройте систему CI (например, GitHub Actions, Travis CI, GitLab CI) для автоматической сборки, тестирования и развертывания вашего пакета всякий раз, когда в ваш код вносятся изменения. Это помогает гарантировать, что ваш пакет всегда находится в рабочем состоянии.
Пример конфигурации GitHub Actions:
```yaml name: Python Package on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 uses: actions/setup-python@v4 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install poetry poetry install - name: Lint with flake8 run: | poetry run flake8 . - name: Test with pytest run: | poetry run pytest ```6. Опубликуйте ваш пакет на PyPI
Поделитесь своим пакетом со всем миром, опубликовав его в индексе пакетов Python (PyPI). Это упрощает установку и использование вашего пакета другими.
Шаги для публикации на PyPI:
- Зарегистрируйте аккаунт на PyPI и TestPyPI.
- Установите
twine:pip install twine. - Соберите ваш пакет:
poetry buildилиpython setup.py sdist bdist_wheel. - Загрузите ваш пакет на TestPyPI:
twine upload --repository testpypi dist/*. - Загрузите ваш пакет на PyPI:
twine upload dist/*.
Примеры из реального мира
Давайте рассмотрим, как некоторые популярные проекты Python используют pyproject.toml:
- Poetry: Использует
pyproject.tomlдля собственного управления пакетами. - Black: Бескомпромиссный форматтер кода также использует
pyproject.toml. - FastAPI: Современный, быстрый (высокопроизводительный) веб-фреймворк для создания API на Python также использует его.
Заключение
pyproject.toml представляет собой современный стандарт для управления пакетами Python, предлагая декларативный и безопасный способ определения метаданных вашего пакета и управления зависимостями. Хотя setup.py хорошо послужил нам, миграция на pyproject.toml является стоящей инвестицией для долгосрочной поддерживаемости, согласованности и интеграции с современными инструментами. Применяя лучшие практики и используя правильные инструменты, вы можете оптимизировать свой рабочий процесс упаковки Python и создавать высококачественные, многократно используемые пакеты.