Создание пакетов и __init__.py
Тема дорожной карты · Python Programming
Пакет — директория, из которой Python умеет импортировать; раньше маркером был (возможно, пустой) __init__.py. PEP 420 ввёл namespace-пакеты и ослабил это требование, но для прикладного кода всё равно лучше явный __init__.py — он управляет тем, что экспортируется, выполняет setup на уровне пакета и спасает от сюрпризов импорта. Держи __init__.py тонким: реэкспортируй публичное API, задавай __all__, при желании определи __version__. Тяжёлая работа в __init__.py замедляет каждый импорт. Дополни это pyproject.toml и src layout, чтобы pip install -e . реально находил пакет.
Как это работает
Создание пакетов и init.py организует код: модуль — это .py-файл, пакет — директория с __init__.py (или namespace package без него). import ищет в sys.path: директория скрипта + PYTHONPATH + site-packages. Виртуальные окружения (venv, virtualenv, poetry, uv) изолируют зависимости на проект — два проекта могут пинить разные версии одной библиотеки. pyproject.toml (PEP 518/621) описывает build system + метаданные проекта + зависимости; pip install -e . ставит локальный пакет в editable-режиме.
Когда применять
Всегда используйте virtualenv на проект — никогда не ставьте глобально через pip. Для современных проектов предпочитайте pyproject.toml + uv или poetry голым requirements.txt; lockfile гарантирует воспроизводимые установки. Разбивайте на пакеты, когда кодовая база переваливает ~3-5 файлов в одной логической области или планируется публикация на PyPI. Используйте __main__.py, чтобы python -m mypkg запускал что-то.
Типичные ошибки
Ловушки Создание пакетов и init.py: циклические импорты (A импортирует B импортирует A — переносите общий символ в третий модуль или делайте локальный импорт внутри функции); editable install + несколько Python в PATH (какой python запускается? which python и проверьте sys.executable внутри); коммит virtualenv-папки в git (она машино-зависимая — в gitignore); путаница from pkg import mod и import pkg.mod (только второй связывает pkg).