Инструкция import, документация.
Базовая инструкция import
, без оператора from
, выполняется в два этапа:
- Поиск модуля, загрузка и инициализация его при необходимости.
- Определение имени или имён, в локальном пространстве имен, для области, в которой выполняется инструкция
import
.
Когда инструкция import
содержит несколько имен модулей, разделенных запятыми, эти два шага выполняются отдельно для каждого имени, как если бы предложения были разделены на отдельные операторы импорта.
Поиск и загрузка модулей более подробно описаны во
встроенной функции __import__
, а также в материалах раздела "
Система импорта в Python". Обратите внимание, что ошибки на этом шаге могут указывать либо на то, что модуль не удалось найти, либо на то, что произошла ошибка при инициализации модуля, которая включает в себя выполнение кода модуля.
Если запрошенный модуль будет успешно найден и загружен, он будет доступен в локальном пространстве имен одним из трех способов:
- Если после имени модуля следует
as
, то имя следующее за as
привязывается непосредственно к импортированному модулю. - Если никакое другое имя не указано, а импортируемый модуль является модулем верхнего уровня, имя модуля связывается в локальном пространстве имен как ссылка на импортируемый модуль.
- Если импортируемый модуль не является модулем верхнего уровня, то имя пакета верхнего уровня, содержащего этот модуль, связывается в локальном пространстве имен как ссылка на пакет верхнего уровня. Доступ к импортированному модулю должен осуществляться с использованием его полного имени, а не напрямую.
Конструкция импорта с инструкцией from
использует несколько более сложный процесс:
- Поиск модуля, указанного в инструкции
from
, загрузка и инициализация его при необходимости. - Для каждого из идентификаторов, указанных в инструкции
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. Спецификация для относительного импорта содержится в материале "
Относительный импорт пакетов".