Поглиблене порівняння 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 та створювати високоякісні, придатні для повторного використання пакети.