Структура проекта и if __name__ == "__main__"
Тема дорожной карты · Python Programming
Понятная точка входа и разумный layout быстро окупаются. Конструкция if __name__ == "__main__": отделяет импортируемый код от исполняемого, чтобы модуль можно было переиспользовать без сайд-эффектов. Стандартный «src layout» (src/mypkg/__init__.py, тесты вне пакета, pyproject.toml в корне) спасает от классической ловушки — случайного импорта локальных исходников вместо установленного пакета. Для проектов покрупнее давай CLI-точки через python -m mypkg и регистрируй console-scripts в pyproject.toml, чтобы у пользователей появились настоящие команды.
Как это работает
Структура проекта и if name == "main" организует код: модуль — это .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 запускал что-то.
Типичные ошибки
Ловушки Структура проекта и if name == "main": циклические импорты (A импортирует B импортирует A — переносите общий символ в третий модуль или делайте локальный импорт внутри функции); editable install + несколько Python в PATH (какой python запускается? which python и проверьте sys.executable внутри); коммит virtualenv-папки в git (она машино-зависимая — в gitignore); путаница from pkg import mod и import pkg.mod (только второй связывает pkg).