Python Build Tools: настройка и использование в среде разработки
Инструменты сборки Python: современные подходы и настройка
Как подготовить пакет Python к сборке и публикации, используя стандартизированную конфигурацию?
Наиболее эффективным речением сегодня является использование pyproject.toml в сочетании с утилитой build и бэкендом setuptools. Этот подход рекомендован PyPA (Python Packaging Authority) и поддерживается всеми современными IDE, включая PyCharm и VS Code, без дополнительных плагинов.
# pyproject.toml
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
[project]
name = "mypackage"
version = "0.1.0"
description = "Пример пакета"
authors = [{name = "Автор", email = "author@example.com"}]
dependencies = [
"requests>=2.28.0",
"numpy",
]
Pip tools python (pip tools в python)
После создания файла в корне проекта достаточно выполнить команду:
python -m buildPython build tools (python build tools (инструменты сборки))
В результате в каталоге dist/ появятся .tar.gz (sdist) и .whl (wheel). Эти артефакты можно загрузить на PyPI или установить локально.
Типичная ошибка: отсутствие setuptools или устаревшая версия. Решение – обновить через pip install --upgrade setuptools. Другая проблема – конфликт зависимостей в [project.dependencies]; рекомендуется указывать версии с диапазонами (например >=2.28.0,<3).
Как объединить управление зависимостями и сборку в одном инструменте с автоматическим созданием виртуального окружения?
Для этого подходит Poetry. Он не только собирает пакет, но и управляет зависимостями, виртуальными окружениями и публикацией. Файл pyproject.toml здесь же используется, но с другим бэкендом.
# pyproject.toml (Poetry)
[tool.poetry]
name = "mypackage"
version = "0.1.0"
description = "Пример для Poetry"
authors = ["Автор"]
[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28"
numpy = "^1.24"
[tool.poetry.dev-dependencies]
pytest = "^7.0"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Python packaging tools (python packaging tools (инструменты сборки))
Инициализация проекта и создание сборки:
poetry init
poetry add requests
poetry build
Python online код (онлайн редактор python)
Poetry создаёт виртуальное окружение автоматически при выполнении poetry install. В IDE, таких как PyCharm, достаточно указать interpreter от Poetry.
Проблема: при использовании Poetry в CI/CD может возникнуть необходимость установки самого Poetry. Решение – использовать официальный образ python:3.11-slim и установить через pip install poetry. Другая ошибка – несовместимость версий зависимостей; для диагностики применяется poetry check.
Как быстро создавать, собирать и публиковать проекты Python с поддержкой нескольких версий Python?
Инструмент Hatch предлагает встроенные шаблоны проектов, управление окружениями и автоматическую сборку. Он особенно удобен для исследователей и разработчиков, часто работающих с разными версиями Python.
# pyproject.toml (Hatch)
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "mypackage"
version = "0.1.0"
[tool.hatch.version]
path = "mypackage/__init__.py"
[tool.hatch.envs.default]
dependencies = [
"requests",
"numpy",
]
Find python script (поиск python скрипта)
Создание нового проекта и сборка:
hatch new mypackage
cd mypackage
hatch build
Hatch автоматически определяет версию из файла __init__.py и создаёт дистрибутивы. Кроме того, можно задать несколько окружений для разных Python версий в одном проекте.
Типичная ошибка: Hatch требует наличие hatchling в списке requires. Если бэкенд указан неверно, сборка завершится с ошибкой ModuleNotFoundError: No module named 'hatchling'. Решение – проверить поле build-system.
Расширенные примеры работы с инструментами сборки
Пример 1: сборка с C расширением (Cython) через setuptools
Для включения Cython-модуля в пакет необходимо добавить setup.py (хотя основная конфигурация в pyproject.toml).
# pyproject.toml
[build-system]
requires = ["setuptools>=61.0", "wheel", "Cython"]
build-backend = "setuptools.build_meta"
# setup.py (дополнительно)
from setuptools import setup
from Cython.Build import cythonize
setup(
ext_modules = cythonize("mypackage/fast_math.pyx")
)
Выполните сборку:
python -m buildРезультат: в dist/ появится wheel, включающий скомпилированный .so/.pyd файл. Если Cython не установлен, возникает ошибка ModuleNotFoundError – добавьте Cython в requires.
Пример 2: использование Poetry для группировки зависимостей
Создайте проект Poetry с группами для тестирования и документации.
# pyproject.toml
[tool.poetry]
name = "mypackage"
version = "0.2.0"
[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.28"
[tool.poetry.group.test.dependencies]
pytest = "^7.4" # устанавливается через poetry install --with test
[tool.poetry.group.docs.dependencies]
sphinx = "^6.2"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Команды для установки зависимостей:
poetry install # только основные
poetry install --with test,docs # основные + test + docs
Это позволяет избежать загрязнения продакшен-окружения лишними библиотеками. Если вы случайно выполните poetry add pytest без указания группы, зависимость попадёт в основные – исправляется удалением и повторным добавлением с флагом --group test.
Пример 3: настройка Hatch для нескольких окружений с разными версиями Python
Hatch поддерживает матрицу окружений, указав версии Python в [tool.hatch.envs].
# pyproject.toml
[tool.hatch.version]
path = "mypackage/__init__.py"
[tool.hatch.envs.default]
features = []
[tool.hatch.envs.py39]
python = "3.9"
dependencies = ["pytest"]
[tool.hatch.envs.py311]
python = "3.11"
dependencies = ["pytest"]
Запустите тесты в каждом окружении:
hatch run py39:pytest
hatch run py311:pytest
Результат выполнения:
# Окружение py39 ============================= test session starts ============================== platform linux -- Python 3.9.18, pytest-7.4.2 collected 2 items ... # Окружение py311 ============================= test session starts ============================== platform linux -- Python 3.11.6, pytest-7.4.2 collected 2 items ...
Ошибка: если указанная версия Python не установлена, Hatch выдаст сообщение Python 3.9 not found. Решение – установить нужную версию через менеджер версий (pyenv, conda).
Пример 4: публикация пакета на TestPyPI с помощью build и twine
# Сборка
python -m build
# Загрузка на TestPyPI (требуется twine)
pip install twine
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
После успешной загрузки можно установить пакет с тестового репозитория:
pip install -i https://test.pypi.org/simple/ mypackage
Результат: пакет будет установлен из тестового хранилища. Если не указать --repository-url, twine попытается загрузить на основной PyPI – это частая ошибка новичков. Для отладки используйте twine check dist/* перед загрузкой.