Полное руководство по настройкам пакетов в Python

Расширенные примеры настройки пакетов

Группы зависимостей (optional-dependencies) в pyproject.toml

Можно определить дополнительные группы зависимостей, например для тестирования или документации. Пример pyproject.toml с setuptools:

[project]
name = "mypackage"
version = "0.1.0"
dependencies = [
    "requests>=2.25",
]

[project.optional-dependencies]
test = [
    "pytest>=7",
    "pytest-cov",
]
docs = [
    "sphinx",
    "myst-parser",
]

Установить с группой: pip install mypackage[test] или pip install -e .[test,docs]. Результат - будут установлены основные зависимости и выбранные группы.

Пояснение: optional-dependencies полезны для разделения окружений (dev, test, doc). Это избегает установки лишних пакетов в продакшн.

Динамическое определение версии из модуля

Часто версию хранят в __init__.py и читают в setup.py или pyproject.toml. Пример с setuptools и setup.py:

# mypackage/__init__.py
__version__ = "0.1.0"

# setup.py
import re
from setuptools import setup

with open("mypackage/__init__.py", "r") as f:
    version = re.search(r"__version__\s*=\s*[\"']([^\"']+)[\"']", f.read()).group(1)

setup(
    name="mypackage",
    version=version,
    ...
)

Для pyproject.toml можно использовать плагин setuptools-scm, который автоматически извлекает версию из git тегов. Пример pyproject.toml:

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

[project]
name = "mypackage"
dynamic = ["version"]

[tool.setuptools_scm]

После этого версия извлекается автоматически на основе git-тегов. Результат: pip install -e . установит пакет с версией, полученной из коммита (например, 0.1.0.dev5).

Настройка сборки C-расширений с setuptools

Для пакетов с расширениями на C/C++ используется секция ext_modules. Пример setup.py:

from setuptools import setup, Extension

module = Extension(
    'mypackage._core',
    sources=['src/core.c'],
    include_dirs=['include']
)

setup(
    name='mypackage',
    version='0.1.0',
    ext_modules=[module],
    packages=['mypackage'],
)

Результат: при сборке компилируется core.c и создаётся модуль _core.so (или .pyd). Типичная ошибка - отсутствие компилятора C. Решение: установить build-essential (Linux) или Visual Studio Build Tools (Windows).

Публикация пакета на PyPI с классификаторами

Классификаторы (classifiers) помогают пользователям найти пакет по категориям. Пример pyproject.toml:

[project]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Topic :: Software Development :: Libraries",
]

После сборки (python -m build) и публикации (twine upload dist/*) классификаторы отображаются на странице PyPI.

Использование плагина setuptools-scm для управления версией

Плагин setuptools-scm автоматически вычисляет версию на основе git тегов. Пример конфигурации в pyproject.toml:

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

[tool.setuptools_scm]
version_scheme = "post-release"
local_scheme = "no-local-version"

Если в git есть тег v0.1.0, то версия будет 0.1.0. Если после тега есть коммиты, версия станет 0.1.0.post1+. Результат виден при вызове python -c "import mypackage; print(mypackage.__version__)".

Настройка консольных скриптов (entry points) в pyproject.toml

Консольные скрипты позволяют запускать функции из пакета как команды терминала. Пример:

[project.scripts]
mycli = "mypackage.cli:main"
another = "mypackage.utils:run"

После установки пакета команды mycli и another будут доступны в терминале. Результат проверки:

$ mycli --help
usage: mycli [-h]
...