Подробно сравнение на 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. Използвайте Continuous Integration (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 Package Index (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 и да създадете висококачествени пакети за многократна употреба.