Внедрение версии в Python пакет: простой и стандартный способ

Быстрый ответ

Чтобы внедрить номер версии в ваш пакет Python, следует прописать в файле __init__.py переменную __version__. При этом стоит придерживаться формата семантического версионирования (MAJOR.MINOR.PATCH). Вот так:

# В файле __init__.py вашего пакета
__version__ = '1.0.0'  # Версионирование просто и понятно – ваши программистские радости вырастают в геометрической прогрессии

Для вывода номера версии:

# Получаем версию пакета
from your_package import __version__
print(__version__)  # Отобразит номер версии, сэкономив ваше время

Версионирование через данный подход станет ключом к эффективному управлению зависимостями и понятной навигации по изменениям в последующих релизах вашего пакета.

Версионирование 101: Основы

Триумвират PEP

Работая над проектом на Python, вы наверняка знакомы с "Триумвиратом PEP". PEP 440 вводит четкие правила по формату версий, PEP 396 советует использовать именно __version__, а PEP 8 указывает на наилучшее место для размещения "dunder" имен модулей.

Единый источник истины

Один за всех, и все за одного! Сохраните информацию о версии в файле _version.py, расположенном в каталоге вашего пакета. Он станет единым источником информации о версии.

Универсальный формат версии

Следуйте принципам семантического версионирования, присваивайте __version__ строковое значение, что делает его универсально применимым и соответствующим PEP 440.

Синхронизация версий

Для поддержания синхронизации между setup.py и _version.py, рекомендуется использовать регулярные выражения, чтобы не применять прямой импорт пакета в setup.py:

# В файле setup.py

import re

with open("your_package/_version.py", "rt") as fh:
    version = re.search(r"__version__ = '([^']+)'", fh.read()).group(1)
    # Владение регулярными выражениями – повод для гордости на любом собрании Python-разработчиков

Автоматическое версионирование

Не отвергайте страсть к автоматизации, присущую каждому программисту! Инструменты, такие как python-versioneer или pbr, позволяют автоматизировать управление версиями на основе git-тегов, исключая ручное обновление.

Визуализация версионирования: почтовая аналогия

Версионирование можно сравнить со службой почты:

Ваш пакет: Письмо, готовое к отправке 📨

__version__ = '1.0.0'  # Почтовая марка, удостоверяющая доставку, и радующая пользователей, подобно почтальонам!

Доставка пакета: Получатель мгновенно узнает детали версии по наклейке на посылке:

📨→ 🏷️ `Версия: 1.0.0`

Это понятно, прозрачно и надёжно, как утренний кофе ☕️.

Последовательное использование

Придерживайтесь общепринятого именования __version__, чтобы обеспечивать единообразие между стандартными библиотеками и сторонними модулями.

Упрощённое сравнение

При сравнении версий в коде рекомендуется применять представление версий в виде кортежей целых чисел.

Разрешение проблем установки и сборки

Избегайте прямого импорта пакета в setup.py, чтобы предотвратить нежелательные побочные эффекты во время установки и возможные проблемы при сборке.

Полезные материалы

1. PEP 396 – Номера версий модуля – Детальное разъяснение схемы нумерации версий модулей в Python.
2. Семантическое версионирование 2.0.0 – Золотой стандарт нумерации версий.
3. Унификация версии пакета – Руководство по упаковке Python — Подробное руководство по менеджменту версий вашего пакета.
4. Документация setuptools 69.1.0.post20240212 – Незаменимый инструмент для решения задач упаковки Python.
5. GitHub – python-versioneer/python-versioneer – Автоматизация версионирования для Python-проектов.
6. bumpversion · PyPI — Удобный инструмент для безошибочного увеличения номеров версий.
7. Как опубликовать пакет Python с открытым исходным кодом на PyPI – Real Python — Глубокое погружение в файл setup.py, направляющее вас по процессу упаковки и распространения пакета.