Спецификация инструкции import в Python.

Инструкция import, документация.

Базовая инструкция import, без оператора from, выполняется в два этапа:

1. Поиск модуля, загрузка и инициализация его при необходимости.
2. Определение имени или имён, в локальном пространстве имен, для области, в которой выполняется инструкция import.

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

Поиск и загрузка модулей более подробно описаны во встроенной функции __import__, а также в материалах раздела "Система импорта в Python". Обратите внимание, что ошибки на этом шаге могут указывать либо на то, что модуль не удалось найти, либо на то, что произошла ошибка при инициализации модуля, которая включает в себя выполнение кода модуля.

Если запрошенный модуль будет успешно найден и загружен, он будет доступен в локальном пространстве имен одним из трех способов:

• Если после имени модуля следует as, то имя следующее за as привязывается непосредственно к импортированному модулю.
• Если никакое другое имя не указано, а импортируемый модуль является модулем верхнего уровня, имя модуля связывается в локальном пространстве имен как ссылка на импортируемый модуль.
• Если импортируемый модуль не является модулем верхнего уровня, то имя пакета верхнего уровня, содержащего этот модуль, связывается в локальном пространстве имен как ссылка на пакет верхнего уровня. Доступ к импортированному модулю должен осуществляться с использованием его полного имени, а не напрямую.

Конструкция импорта с инструкцией from использует несколько более сложный процесс:

1. Поиск модуля, указанного в инструкции from, загрузка и инициализация его при необходимости.
2. Для каждого из идентификаторов, указанных в инструкции import:
   • проверить, имеет ли импортируемый модуль атрибут с таким именем;
   • если нет, попытаться импортировать подмодуль с этим именем, а затем снова проверить импортированный модуль на наличие этого атрибута;
   • если атрибут не найден, вызывать исключение ImportError.
   • если все прошло нормально, то ссылка на идентификатор, указанный в инструкции import, сохраняется в локальном пространстве имен с использованием имени в предложении as, если оно присутствует, в противном случае используется имя атрибута модуля.

Примеры использования:

# foo импортируется и привязывается локально
import foo

# foo.bar.baz импортируется, foo привязывается локально
import foo.bar.baz

# foo.bar.baz импортируется и связывается как fbb
import foo.bar.baz as fbb

# foo.bar.baz импортируется и связывается как baz
from foo.bar import baz

# foo импортируется и foo.attr связывается как attr
from foo import attr

Если список идентификаторов заменяется звездочкой '*', все публичные имена, определенные в модуле, связываются в локальном пространстве имен для области, в которой выполняется оператор import.

Публичные имена модуля, определяются путем проверки пространства имен модуля на наличие переменной с именем __all__. Если __all__ определена, то это должна быть последовательность строк, которые являются именами, определенными или импортированными этим модулем. Имена, приведенные в переменной с именем __all__, считаются общедоступными и должны существовать. Если __all__ не определена, то набор публичных имен включает все имена, найденные в пространстве имен модуля, которые не начинаются с символа подчеркивания '_'. Переменная __all__ должна содержать весь открытый API модуля. Она предназначена для того, чтобы избежать случайного экспорта элементов, которые не являются частью API, например библиотечных модулей, которые были импортированы и использованы в модуле.

Подстановочная форма импорта from module import * (со звездочкой) допускается только на уровне модуля. Попытка использовать его в определениях классов или функций вызовет исключение SyntaxError.

При указании модуля для выполнения импорта из пакета, не обязательно указывать абсолютное имя модуля в точечной нотации. Если модуль или пакет содержится в другом пакете, то можно выполнить относительный импорт в том же самом верхнем пакете без необходимости упоминания имени пакета. Используя начальные точки в указанном модуле или пакете после инструкции from, можно указать, как высоко будет проходить текущая иерархия пакетов без указания точных имен. Одна ведущая точка означает текущий пакет, в котором находится модуль, производящий импорт. Две точки означают один уровень выше. Три точки - это два уровня вверх и т. д.

Так что если вы выполняете from . import mod из модуля в пакете pkg, тогда вы в конечном итоге импортируете pkg.mod. Если вы выполняете from ..subpkg2 import mod из pkg.subpkg1 вы импортируете pkg.subpkg2.mod. Спецификация для относительного импорта содержится в материале "Относительный импорт пакетов".

importlib.import_module() предоставляется для поддержки приложений, которые динамически определяют модули для загрузки.