Импорт в Python и организация проекта

Когда вы работаете с модулями в Python, импорт играет важную роль, и понимание его работы может значительно улучшить вашу разработку. В этом посте мы рассмотрим, как работает оператор import в Python и как организовать структуру вашего проекта для более эффективного использования импорта.

При импорте модуля Python не учитывает, в каком файле находится этот импорт. Единственное, что влияет на импорт, - это то, как был запущен код. Если модуль не был загружен ранее, Python пытается найти его в нескольких каталогах, которые определены в переменной sys.path.

По умолчанию sys.path содержит следующие каталоги:

- Каталог, из которого был запущен скрипт
- Каталоги, указанные в переменной окружения PYTHONPATH
- Каталог текущего активного виртуального окружения
- Каталог установки Python

- Если вы запускаете свой скрипт командой python scriptname.py, то первым в списке будет каталог, содержащий запускаемый скрипт. Текущий рабочий каталог не имеет значения.
- Если вы запускаете код командой python -m packagename, то первым в списке будет текущий рабочий каталог. При этом Python попытается найти и импортировать packagename в соответствии с общими правилами.
- Если вы используете инструменты, такие как pytest, для запуска кода, они также могут добавлять что-то в sys.path.

В большинстве случаев вам не потребуется вручную изменять sys.path, так как стандартный алгоритм заполнения его значений является стандартным и привычным для всех. Если по какой-то причине этот алгоритм не подходит вам, возможно, у вас неправильно организована структура проекта.

Так как поиск модулей для импорта происходит сначала в каталоге "проекта", важно аккуратно называть ваши файлы и каталоги. Если вы случайно назовете свой модуль так же, как встроенный или сторонний модуль, при любом импорте такого модуля будет загружаться именно ваш модуль, что может нарушить работу кода.

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

Вынесите запускаемые скрипты на верхний уровень, а остальной код упакуйте в пакет.
Упаковка вашего кода в пакет с уникальным именем позволит избежать конфликтов имен. При этом вынесение всех запускаемых файлов на один уровень делает состав sys.path предсказуемым.

Примерная структура проекта будет выглядеть следующим образом:

Copy code
├── appname
│ ├── __init__.py
│ ├── other_module.py
│ └── some_module.py
├── cli_module.py
└── requirements.txt
Создайте распространяемый пакет (рекомендуется).
В этом случае вы упаковываете весь ваш код в пакет, что помогает избежать конфликтов имен. Для запуска команд вы можете использовать синтаксис python -m appname.cli_module или заполнить секцию entry_points в файле с описанием вашего проекта (например, setup.cfg или pyproject.toml). После этого вы сможете запускать ваш код, находясь в любом каталоге, без необходимости указывать полные пути к файлам.

Для удобства разработки с таким подходом удобно устанавливать пакет в режиме редактирования с помощью команды pip install -e ..

Примерная структура проекта для создания распространяемого пакета будет выглядеть следующим образом:
├── pyproject.toml
└── src
└── appname
├── __init__.py
├── cli_module.py
├── other_module.py
└── some_module.py
Дополнительные материалы для изучения:

Дополнительные материалы:
* https://packaging.python.org/en/latest/
* https://docs.python.org/3/reference/import.html
* https://docs.python.org/3/library/sys.html#sys.path
* https://ru.wikipedia.org/wiki/Рабочий_каталог