Модули, пакеты и окружение
Тема дорожной карты · Python Programming
Python-модуль — это один .py-файл, а пакет — дерево директорий с кодом, который Python находит через sys.path. Правила: импорты выполняются сверху вниз при первой загрузке и кэшируются в sys.modules; циклические импорты обычно говорят об ошибке слоёв архитектуры; относительные импорты (from .utils import x) работают только внутри установленного пакета или запуска как пакета, но не у обычных скриптов. Под каждый проект — отдельное виртуальное окружение (python -m venv .venv), чтобы зависимости не пересекались глобально. Продвинутый уровень: namespace-пакеты (PEP 420), import hooks и editable-установки (pip install -e .).
Как это работает
Модули, пакеты и окружение организует код: модуль — это .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 запускал что-то.
Типичные ошибки
Ловушки Модули, пакеты и окружение: циклические импорты (A импортирует B импортирует A — переносите общий символ в третий модуль или делайте локальный импорт внутри функции); editable install + несколько Python в PATH (какой python запускается? which python и проверьте sys.executable внутри); коммит virtualenv-папки в git (она машино-зависимая — в gitignore); путаница from pkg import mod и import pkg.mod (только второй связывает pkg).