Модули и импорты вглубь: sys.modules, финдеры и лоадеры, ловушка циклического импорта

import — это поиск в словаре. После первого раза

К концу этого раздела вы будете точно знать, почему перенос двух строк превратил 14 секунд в 1,3 — и как диагностировать ту же картину в собственном коде.

import json делает что-то дорогое максимум один раз на процесс. В первый раз Python находит модуль, выполняет весь его код верхнего уровня в свежем пространстве имён и кладёт получившийся объект модуля в sys.modules — обычный словарь с именами модулей в ключах. Каждый последующий import json, в любой точке процесса, — попадание в словарь: наносекунды, без I/O, без повторного выполнения. Два следствия правят повседневностью. Первое: код верхнего уровня модуля — это однократная инициализация процесса; именно поэтому import pandas из Хука стоил 12 секунд каждому воркеру — каждый свежий процесс платит цену первого импорта за всю транзитивную цепочку. Второе: модули — синглтоны на весь процесс: settings.DEBUG = True мутирует тот единственный общий объект, который видят все импортёры; на этом стоит весь манкипатчинг — и тот тест, который изменил атрибут модуля и тихо поменял поведение в чужом наборе тестов. Удаление записи из sys.modules заставит модуль выполниться заново при следующем импорте; этим пользуются перезагрузчики плагинов pytest — и этого почти никогда не стоит делать руками.

Машинерия: финдеры, лоадеры и анатомия sys.path

При промахе кеша Python обходит sys.meta_path — список финдеров. Стоковый CPython ставит три: для встроенных модулей, для замороженных и PathFinder, который идёт по sys.path каталог за каталогом. Финдер, признавший имя, возвращает ModuleSpec (объект-описатель модуля: путь к файлу, загрузчик и имя пакета) с лоадером; система импорта создаёт пустой объект модуля, регистрирует его в sys.modules до выполнения чего-либо и просит лоадер исполнить код модуля в это пространство имён. Запомните порядок — сначала регистрация, потом выполнение: это единственный факт, решающий, какие циклические импорты выживают.

У самого sys.path заряженный ствол под нулевым индексом: при python script.py нулевая запись — каталог скрипта (при -m или в REPL — текущий каталог). Локальные файлы обгоняют стандартную библиотеку. Классика: помощник random.py в рабочем каталоге, и тремя слоями глубже какая-то библиотека делает import random и получает ваш файл. Ошибка приходит далеко от причины — AttributeError: module 'random' has no attribute 'choice' в недрах чужого трейсбека; а если ваш random.py сам импортирует random, получите циклический вариант. Python 3.13 наконец печатает подсказку переименовать затеняющий файл; на всём, что старше, диагностический ход — import random; print(random.__file__). Дисциплина, закрывающая класс ошибок: абсолютные импорты по умолчанию, относительные (from . import db) — только для внутрипакетных ссылок, и никогда не называть модуль именем чего-либо из стандартной библиотеки.

Пакеты: init.py выполняется, и оговорка про namespace-пакеты

import pkg.sub — это два импорта: сначала Python импортирует pkg — а значит, выполняется pkg/__init__.py, — потом pkg.sub. Поэтому тяжёлый __init__.py — налог на весь пакет: популярный паттерн удобных реэкспортов (from .client import Client и ещё десять строк) заставляет каждого потребителя, которому нужен один маленький сабмодуль, заплатить за все. Цепочка из Хука на 12 секунд имела ровно эту форму — __init__.py, агрегирующий сабмодули, которые агрегировали pandas. Держите инициализаторы пакетов на уровне реэкспорта дешёвых имён, а тяжёлую обвязку уносите в модули, которым она нужна.

Уберите __init__.py — получите namespace-пакет: импортируется, кода инициализации нет, и — собственно фича — несколько каталогов на sys.path могут вносить части, сливающиеся в один логический пакет (company.auth из одного дистрибутива, company.billing из другого). Честные издержки: вовсе нет хука инициализации уровня пакета, чуть более медленный поиск (нужно опросить каждую запись пути) и аварийный режим — забытый __init__.py молча создаёт namespace-пакет вместо ошибки, маскируя огрехи раскладки до самого этапа упаковки. Если вы не делите один неймспейс между дистрибутивами сознательно — держите явные __init__.py.

Циклические импорты: почему умирает именно from-import

Когда видите ImportError: cannot import name 'X' from partially initialized module, первый импульс — перетасовать порядок импортов. Но правильный вопрос другой: какой вид импорта использует ваш код и когда он требует имя. Понимание этого различия ведёт к нужному фиксу, а не к везению.

Модуль a импортирует b; на середине выполнения b импортирует a обратно. Поскольку a зарегистрирован в sys.modules до начала выполнения своего тела, цикл не уходит в рекурсию — b просто получает полусобранный объект модуля: всё, что a успел связать выше своей строки import b, существует; всё ниже — ещё нет.

# a.py                          # b.py
config = {"region": "eu"}       import a            # получает полусобранный a: ок
import b                        # from a import helper  ← ImportError!
def helper(): ...               def use():
                                    return a.helper()   # в момент вызова a готов

import a внутри b выживает, потому что лишь связывает объект модуля и откладывает доступ к атрибутам до момента вызова — к тому времени a довыполнился. from a import helper требует атрибут прямо сейчас, посреди выполнения, и поднимает ImportError: cannot import name 'helper' from partially initialized module 'a' (most likely due to a circular import) — CPython буквально называет болезнь по имени. Фиксы, по ранжиру: реструктурировать — вынести общий кусок в третий модуль, который импортируют оба, убив цикл (лучший вариант, обычно вскрывает реальный изъян слоёв); поздний импорт — перенести импорт внутрь функции, отложив разрешение за пределы инициализации (прагматично, прячет зависимость); импортировать модуль, а не имя — import a плюс a.helper() в момент вызова (дешевле всего, цикл остаётся на месте).

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

Сайд-эффекты времени импорта, main и флаг -m

Всё выше складывается в одно правило: уровень модуля — для определений, а не действий. Модульный db = psycopg.connect(...) выполняется при импорте — в каждом процессе, транзитивно коснувшемся модуля, включая тест-раннер, которому нужна была одна константа, и в момент, когда конфиг может быть не загружен, а циклов событий не существует. Жизненный цикл для такой работы — явный стартовый хук, паттерн lifespan из юнита про веб-сервисы, а не время импорта. Тест на запах: импорт любого вашего модуля должен быть свободен от I/O, а python -X importtime -c "import yourpkg" — профилировщик, который это докажет.

Последний кусок: как файл становится программой. python pkg/tool.py выполняет файл как __main__ без пакетного контекста — __package__ пуст, поэтому from . import db поднимает ImportError: attempted relative import with no known parent package, а sys.path[0] становится pkg/, заново взводя ствол затенения. python -m pkg.tool, напротив, честно импортирует pkg (выполнив его __init__.py), исполняет tool как __main__ с пакетным контекстом и кладёт в sys.path[0] текущий каталог, а не каталог скрипта. Скриптам, живущим внутри пакетов, нужен -m; поэтому же console-script точки входа (следующий урок) генерируют шимы, которые импортируют ваш модуль, а не исполняют файл.