Как задать версию пакета с помощью __init__.py

Расширенные примеры версионирования

Иерархическое версионирование подпакетов

В больших пакетах можно задавать версию для каждого подпакета отдельно, экспортируя её через __init__.py.

# mypackage/subpackage1/__init__.py
__version__ = '1.0.0'

# mypackage/subpackage2/__init__.py
__version__ = '2.0.0'

# Использование
import mypackage.subpackage1
print(mypackage.subpackage1.__version__)  # '1.0.0'

Такая структура полезна, если подпакеты развиваются с разной скоростью. Однако следует документировать, что версия корневого пакета (например, mypackage.__version__) может не совпадать с версиями вложенных модулей.

Автоматическое обновление версии с помощью versioneer

versioneer создаёт файл _version.py на основе Git-тегов и может внедрять переменную в __init__.py. Полная настройка включает:

# Установка и инициализация
pip install versioneer
versioneer install

После этого в setup.cfg добавляется:

[versioneer]
VCS = git
style = pep440
versionfile_source = mypackage/_version.py
versionfile_build = mypackage/_version.py
tag_prefix = v
parentdir_prefix = mypackage-

В __init__.py:

from ._version import get_versions
__version__ = get_versions()['version']
del get_versions

Результат при наличии тега v1.2.0:

>>> import mypackage
>>> mypackage.__version__
'1.2.0'

При отсутствии тега версия будет содержать хеш коммита.

Использование __all__ вместе с __version__

В __init__.py можно экспортировать не только версию, но и список публичных имён. Это помогает инструментам статического анализа.

# mypackage/__init__.py
__version__ = '0.5.0'
__all__ = ['submodule1', 'submodule2', '__version__']

from . import submodule1, submodule2

Теперь from mypackage import * импортирует и __version__, и подмодули.

Динамическое получение версии из git в рантайме (без файла)

Некоторые проекты отказываются от хранения версии в файле и получают её напрямую из Git при запуске. Это не рекомендуется для установленных пакетов, но возможно в среде разработки.

import subprocess
import os

def get_git_version():
    try:
        return subprocess.check_output(
            ['git', 'describe', '--tags'],
            cwd=os.path.dirname(__file__)
        ).decode().strip()
    except Exception:
        return 'unknown'

__version__ = get_git_version()

Результат:

>>> import mypackage
>>> mypackage.__version__
'v1.0.0-5-gabcdef'

Недостаток: высокая задержка при первом импорте, зависимость от Git и отсутствие версии после установки (если репозиторий не включён).

Кэширование версии при импорте

Если получение версии затратно (например, вызов Git), можно сохранить результат в глобальную переменную.

# mypackage/__init__.py
_version = None

def _get_version():
    global _version
    if _version is None:
        # вычисляем один раз
        from importlib.metadata import version
        try:
            _version = version('mypackage')
        except:
            _version = '0.0.0.dev'
    return _version

__version__ = _get_version()

Такой подход позволяет ускорить повторные обращения к атрибуту.