5. Система импорта¶The import system

5.2.1. Обычные пакеты¶Regular packages

Python defines two types of packages, regular packages and namespace packages. Regular packages are traditional packages as they existed in Python 3.2 and earlier. A regular package is typically implemented as a directory containing an __init__.py file. When a regular package is imported, this __init__.py file is implicitly executed, and the objects it defines are bound to names in the package’s namespace. The __init__.py file can contain the same Python code that any other module can contain, and Python will add some additional attributes to the module when it is imported.

Например, следующая структура файловой системы определяет пакет верхнего уровня parent с тремя вложенными пакетами:

parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py

Импорт parent.one неявно выполнит parent/__init__.py и parent/one/__init__.py. Последующие импорты parent.two или parent.three выполнят parent/two/__init__.py и parent/three/__init__.py соответственно.

5.2.2. Пакеты пространств имен¶Namespace packages

A namespace package is a composite of various portions, where each portion contributes a subpackage to the parent package. Portions may reside in different locations on the file system. Portions may also be found in zip files, on the network, or anywhere else that Python searches during import. Namespace packages may or may not correspond directly to objects on the file system; they may be virtual modules that have no concrete representation.

Пакеты пространств имен не используют обычный список для своего атрибута __path__. Вместо этого они используют пользовательский итерируемый тип, который автоматически выполняет новый поиск частей пакета при следующей попытке импорта в рамках этого пакета, если путь родительского пакета (или sys.path для пакета верхнего уровня) изменяется.

В пакетах пространств имен нет файла parent/__init__.py. Фактически, при поиске импорта может быть найдено несколько каталогов parent, каждый из которых предоставляется разной частью. Таким образом, parent/one может физически не находиться рядом с parent/two. В этом случае Python создаст пакет пространства имен для пакета верхнего уровня parent всякий раз, когда импортируется сам этот пакет или любой из его вложенных пакетов.

See also PEP 420 for the namespace package specification.

5.3.1. Кеш модулей¶The module cache

Первое место, проверяемое при поиске импорта, – это sys.modules. Это отображение служит кешем всех ранее импортированных модулей, включая промежуточные пути. Таким образом, если foo.bar.baz был ранее импортирован, sys.modules будет содержать записи для foo, foo.bar и foo.bar.baz. Каждый ключ будет иметь в качестве значения соответствующий объект модуля.

Во время импорта имя модуля ищется в sys.modules, и если оно присутствует, связанное значение является модулем, удовлетворяющим импорт, и процесс завершается. Однако если значением является None, то возбуждается ModuleNotFoundError. Если имя модуля отсутствует, Python продолжает поиск модуля.

sys.modules доступен для записи. Удаление ключа может не уничтожить связанный модуль (поскольку другие модули могут хранить на него ссылки), но это сделает недействительной запись кеша для указанного модуля, что заставит Python выполнить новый поиск этого модуля при следующем импорте. Ключ также можно присвоить None, что приведет к тому, что следующий импорт модуля завершится ModuleNotFoundError.

Однако будьте осторожны: если вы сохраните ссылку на объект модуля, сделаете недействительной его запись в кеше sys.modules, а затем повторно импортируете указанный модуль, два объекта модуля не будут одинаковыми. В отличие от этого, importlib.reload() будет повторно использовать тот же объект модуля и просто повторно инициализирует содержимое модуля, выполнив его код заново.

5.3.2. Искатели и загрузчики¶Finders and loaders

Если именованный модуль не найден в sys.modules, то вызывается протокол импорта Python для поиска и загрузки модуля. Этот протокол состоит из двух концептуальных объектов: искателей и загрузчиков. Задача искателя – определить, может ли он найти именованный модуль, используя любую известную ему стратегию. Объекты, реализующие оба этих интерфейса, называются импортерами – они возвращают самих себя, когда обнаруживают, что могут загрузить запрошенный модуль.

Python includes a number of default finders and importers. The first one knows how to locate built-in modules, and the second knows how to locate frozen modules. A third default finder searches an import path for modules. The import path is a list of locations that may name file system paths or zip files. It can also be extended to search for any locatable resource, such as those identified by URLs.

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

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

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

5.3.3. Хуки импорта¶Import hooks

Механизм импорта разработан как расширяемый; основным механизмом для этого являются хуки импорта. Существует два типа хуков импорта: мета-хуки и хуки пути импорта.

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

Хуки пути импорта вызываются как часть обработки sys.path (или package.__path__) в тот момент, когда встречается связанный с ними элемент пути. Хуки пути импорта регистрируются путем добавления новых вызываемых объектов в sys.path_hooks, как описано ниже.

5.3.4. Мета-путь¶The meta path

Когда именованный модуль не найден в sys.modules, Python затем ищет в sys.meta_path, который содержит список объектов искателей мета-пути. Эти искатели опрашиваются по порядку, чтобы выяснить, знают ли они, как обрабатывать именованный модуль. Искатели мета-пути должны реализовывать метод с именем find_spec(), который принимает три аргумента: имя, путь импорта и (опционально) целевой модуль. Искатель мета-пути может использовать любую стратегию по своему усмотрению, чтобы определить, может ли он обработать именованный модуль или нет.

Если искатель мета-пути знает, как обрабатывать именованный модуль, он возвращает объект спецификации. Если он не может обработать именованный модуль, он возвращает None. Если обработка sys.meta_path достигает конца своего списка, не вернув спецификацию, то возбуждается ModuleNotFoundError. Любые другие возникшие исключения просто распространяются вверх, прерывая процесс импорта.

Метод find_spec() искателей мета-пути вызывается с двумя или тремя аргументами. Первый – это полное имя импортируемого модуля, например foo.bar.baz. Второй аргумент – это записи пути, используемые для поиска модуля. Для модулей верхнего уровня вторым аргументом является None, но для подмодулей или подпакетов вторым аргументом является значение атрибута __path__ родительского пакета. Если соответствующий атрибут __path__ недоступен, возбуждается ModuleNotFoundError. Третий аргумент – это существующий объект модуля, который будет целью загрузки позже. Система импорта передает целевой модуль только во время перезагрузки.

Мета-путь может обходиться несколько раз для одного запроса импорта. Например, предполагая, что ни один из задействованных модулей еще не был кеширован, импорт foo.bar.baz сначала выполнит импорт верхнего уровня, вызывая mpf.find_spec("foo", None, None) у каждого искателя мета-пути (mpf). После того, как foo был импортирован, foo.bar будет импортирован путем обхода мета-пути во второй раз с вызовом mpf.find_spec("foo.bar", foo.__path__, None). Как только foo.bar будет импортирован, последний обход вызовет mpf.find_spec("foo.bar.baz", foo.bar.__path__, None).

Некоторые искатели мета-пути поддерживают только импорт верхнего уровня. Эти импортеры всегда будут возвращать None, если в качестве второго аргумента передано что-либо, кроме None.

sys.meta_path по умолчанию Python имеет три искателя мета-пути: один умеет импортировать встроенные модули, один – замороженные модули и один – модули из пути импорта (т.е. искатель на основе пути).

5.4.1. Загрузчики¶Loaders

Загрузчики модулей выполняют критическую функцию загрузки: выполнение модуля. Механизм импорта вызывает метод importlib.abc.Loader.exec_module() с одним аргументом – объектом модуля, который нужно выполнить. Любое значение, возвращённое из exec_module(), игнорируется.

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

• Если модуль является модулем Python (в отличие от встроенного модуля или динамически загружаемого расширения), загрузчик должен выполнить код модуля в глобальном пространстве имён модуля (module.__dict__).

• Если загрузчик не может выполнить модуль, он должен вызвать исключение ImportError, хотя любое другое исключение, возникшее во время exec_module(), будет распространено.

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

Загрузчики модулей могут реализовать метод create_module(), чтобы принять участие в создании объекта модуля во время загрузки. Он принимает один аргумент – спецификацию модуля – и возвращает новый объект модуля для использования во время загрузки. create_module() не нужно устанавливать какие-либо атрибуты объекта модуля. Если метод возвращает None, механизм импорта создаст новый модуль самостоятельно.

5.4.2. Подмодули¶Submodules

Когда подмодуль загружается с помощью любого механизма (например, API importlib, операторов import или import-from, или встроенной __import__()), в пространстве имён родительского модуля создаётся связывание с объектом подмодуля. Например, если пакет spam содержит подмодуль foo, то после импорта spam.foo у spam будет атрибут foo, который связан с подмодулем. Допустим, имеется следующая структура каталогов:

spam/
    __init__.py
    foo.py
    bar.py

и spam/__init__.py содержит следующие строки:

from .foo import Foo
from .bar import Bar

тогда выполнение следующего кода создаёт привязку имени к foo и bar в spam модуле:

>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.bar
<module 'spam.bar' from '/tmp/imports/spam/bar.py'>

Учитывая привычные правила связывания имён в Python, это может показаться удивительным, но на самом деле это фундаментальная особенность системы импорта. Сохраняется следующий инвариант: если имеются sys.modules['spam'] и sys.modules['spam.foo'] (как после импорта выше), то второй должен быть атрибутом foo первого.

5.4.3. Спецификация модуля¶Module spec

Механизм импорта использует различную информацию о каждом модуле во время импорта, особенно перед загрузкой. Большая часть этой информации является общей для всех модулей. Назначение спецификации модуля – инкапсулировать эту связанную с импортом информацию для каждого модуля отдельно.

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

Спецификация модуля доступна как атрибут __spec__ объекта модуля. Подробнее о содержимом спецификации модуля см. в ModuleSpec.

5.4.4. Атрибуты модуля, связанные с импортом¶Import-related module attributes

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

__name__¶

Атрибут __name__ должен содержать полное квалифицированное имя модуля. Это имя используется для однозначной идентификации модуля в системе импорта.

__loader__¶

Атрибут __loader__ должен быть установлен в объект загрузчика, который использовал механизм импорта при загрузке модуля. Это предназначено в основном для интроспекции, но может использоваться и для дополнительной функциональности, специфичной для загрузчика, например для получения данных, связанных с загрузчиком.

__package__¶

Атрибут модуля __package__ должен быть установлен. Его значением должна быть строка, но оно может совпадать со значением __name__. Если модуль является пакетом, значением __package__ должно быть его __name__. Если модуль не является пакетом, для модулей верхнего уровня __package__ должно быть установлено в пустую строку, а для подмодулей – в имя родительского пакета. Подробнее см. в PEP 366.

Этот атрибут используется вместо __name__ для вычисления явных относительных импортов для главных модулей, как определено в PEP 366. Ожидается, что его значение совпадает с __spec__.parent.

Изменено в версии 3.6: Значение __package__ должно совпадать с __spec__.parent.

__spec__¶

Атрибут __spec__ должен быть установлен в спецификацию модуля, которая использовалась при импорте модуля. Установка __spec__ надлежащим образом в равной степени относится и к модулям, инициализируемым при запуске интерпретатора. Единственное исключение – __main__, где __spec__ в некоторых случаях устанавливается в None.

Если __package__ не определён, в качестве запасного варианта используется __spec__.parent.

Новое в версии 3.4.

Изменено в версии 3.6: __spec__.parent используется как запасной вариант, когда __package__ не определён.

__path__¶

Если модуль является пакетом (обычным или пространства имён), атрибут объекта модуля __path__ должен быть установлен. Значение должно быть итерируемым, но может быть пустым, если __path__ не имеет дальнейшего значения. Если __path__ не пусто, при итерации оно должно давать строки. Более подробно о семантике __path__ рассказано ниже.

Модули, не являющиеся пакетами, не должны иметь атрибута __path__.

__file__¶

__cached__¶

__file__ является необязательным. Если установлен, значение этого атрибута должно быть строкой. Система импорта может оставить __file__ неустановленным, если он не имеет семантического смысла (например, модуль, загруженный из базы данных).

Если __file__ установлен, также может быть уместно установить атрибут __cached__, который является путем к любой скомпилированной версии кода (например, файл с байт-кодом). Файл не обязан существовать для установки этого атрибута; путь может просто указывать, где бы находился скомпилированный файл (см. PEP 3147).

Также уместно устанавливать __cached__, когда __file__ не установлен. Однако такой сценарий довольно нетипичен. В конечном счёте, именно загрузчик использует __file__ и/или __cached__. Поэтому, если загрузчик может загрузить модуль из кеша, но в остальном не загружает из файла, такой нетипичный сценарий может быть уместен.

5.4.5. module.__path__¶

По определению, если у модуля есть атрибут __path__, то это пакет.

Атрибут __path__ пакета используется при импорте его подпакетов. В механизме импорта он работает почти так же, как sys.path, то есть предоставляет список мест для поиска модулей во время импорта. Однако __path__ обычно гораздо более ограничен, чем sys.path.

__path__ должен быть итерируемым объектом строк, но может быть пустым. Те же правила, что и для sys.path, применяются к __path__ пакета, а sys.path_hooks (описанные ниже) используются при обходе __path__ пакета.

Файл __init__.py пакета может задавать или изменять атрибут __path__ пакета, и это был обычный способ реализации пространств имён пакетов до PEP 420. С принятием PEP 420 пространства имён пакетов больше не нуждаются в __init__.py файлах, содержащих только код манипуляции __path__; механизм импорта автоматически устанавливает __path__ корректно для пространства имён пакетов.

5.4.6. Строковые представления модулей¶Module reprs

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

Если у модуля есть спецификация (__spec__), механизм импорта попытается сгенерировать строковое представление на её основе. Если это не удаётся или спецификация отсутствует, система импорта создаст строковое представление по умолчанию, используя любую доступную информацию о модуле. Она попытается использовать module.__name__, module.__file__ и module.__loader__ в качестве входных данных для строкового представления, с умолчаниями для отсутствующей информации.

Ниже приведены точные правила:

• Если у модуля есть атрибут __spec__, для генерации строкового представления используется информация из спецификации. Учитываются атрибуты «name», «loader», «origin» и «has_location».

• Если у модуля есть атрибут __file__, он используется как часть строкового представления модуля.

• Если у модуля нет __file__, но есть __loader__, который не равен None, то строковое представление загрузчика используется как часть строкового представления модуля.

• В противном случае в строковом представлении используется просто __name__ модуля.

5.4.7. Инвалидация кэшированного байт-кода¶Cached bytecode invalidation

Прежде чем Python загрузит кэшированный байт-код из файла .pyc, он проверяет, актуален ли кэш относительно исходного файла .py. По умолчанию Python делает это, сохраняя метку времени последнего изменения и размер исходного файла в кэш-файле при его записи. Во время выполнения система импорта затем проверяет кэш-файл, сверяя сохранённые метаданные в кэш-файле с метаданными исходного файла.

Python также поддерживает кэш-файлы на основе хеша, в которых вместо метаданных хранится хеш содержимого исходного файла. Существует два варианта таких .pyc файлов: проверяемые и непроверяемые. Для проверяемых .pyc файлов Python проверяет кэш-файл, хешируя исходный файл и сравнивая полученный хеш с хешем в кэш-файле. Если проверяемый кэш-файл на основе хеша оказывается недействительным, Python пересоздаёт его и записывает новый проверяемый кэш-файл на основе хеша. Для непроверяемых .pyc файлов Python просто считает кэш-файл действительным, если он существует. Поведение проверки .pyc файлов на основе хеша можно переопределить с помощью флага --check-hash-based-pycs.

5.5.1. Искатели записей пути¶Path entry finders

Искатель на основе путей отвечает за поиск и загрузку модулей и пакетов Python, расположение которых задаётся строковой записью пути. Большинство записей пути указывают на расположения в файловой системе, но не обязаны ограничиваться этим.

Будучи искателем мета-путей, искатель на основе путей реализует протокол find_spec(), описанный ранее, однако он также предоставляет дополнительные перехватчики, которые можно использовать для настройки того, как модули находятся и загружаются из пути импорта.

Искатель на основе путей использует три переменные: sys.path, sys.path_hooks и sys.path_importer_cache. Также используются атрибуты __path__ объектов пакетов. Они предоставляют дополнительные способы настройки механизма импорта.

sys.path содержит список строк, определяющих места поиска модулей и пакетов. Он инициализируется из переменной окружения PYTHONPATH и различных других установок по умолчанию, зависящих от установки и реализации. Записи в sys.path могут указывать на каталоги файловой системы, zip-файлы и потенциально другие «места» (см. модуль site), которые следует искать для модулей, такие как URL-адреса или запросы к базам данных. В sys.path должны присутствовать только строки и байтовые строки; все остальные типы данных игнорируются. Кодировка байтовых записей определяется конкретными искателями путей.

Искатель на основе путей является искателем мета-путей, поэтому механизм импорта начинает поиск пути импорта вызовом метода find_spec() искателя на основе путей, как описано ранее. Когда аргумент path для find_spec() задан, это будет список строковых путей для обхода – обычно атрибут __path__ пакета для импорта внутри этого пакета. Если аргумент path равен None, это указывает на импорт верхнего уровня, и используется sys.path.

Путевой искатель перебирает все элементы поискового пути и для каждого из них ищет подходящий искатель элемента пути (PathEntryFinder). Поскольку эта операция может быть дорогой (например, вызовы stat() для поиска), путевой искатель хранит кеш, сопоставляющий элементы пути с их искателями. Этот кеш поддерживается в sys.path_importer_cache (несмотря на название, он хранит объекты искателей, а не только объекты импортёров). Таким образом, дорогой поиск искателя элемента пути для конкретной записи пути выполняется только один раз. Пользовательский код может удалять записи из кеша в sys.path_importer_cache, заставляя путевой искатель снова выполнять поиск элемента пути 3.

If the path entry is not present in the cache, the path based finder iterates over every callable in sys.path_hooks. Each of the path entry hooks in this list is called with a single argument, the path entry to be searched. This callable may either return a path entry finder that can handle the path entry, or it may raise ImportError. An ImportError is used by the path based finder to signal that the hook cannot find a path entry finder for that path entry. The exception is ignored and import path iteration continues. The hook should expect either a string or bytes object; the encoding of bytes objects is up to the hook (e.g. it may be a file system encoding, UTF-8, or something else), and if the hook cannot decode the argument, it should raise ImportError.

If sys.path_hooks iteration ends with no path entry finder being returned, then the path based finder’s find_spec() method will store None in sys.path_importer_cache (to indicate that there is no finder for this path entry) and return None, indicating that this meta path finder could not find the module.

If a path entry finder is returned by one of the path entry hook callables on sys.path_hooks, then the following protocol is used to ask the finder for a module spec, which is then used when loading the module.

Текущий рабочий каталог – обозначаемый пустой строкой – обрабатывается несколько иначе, чем другие записи в sys.path. Во-первых, если текущий рабочий каталог не существует, в sys.path_importer_cache не сохраняется никакого значения. Во-вторых, значение текущего рабочего каталога запрашивается заново при каждом поиске модуля. В-третьих, путь, используемый для sys.path_importer_cache и возвращаемый importlib.machinery.PathFinder.find_spec(), будет фактическим текущим рабочим каталогом, а не пустой строкой.

5.5.2. Протокол искателя записей пути¶Path entry finder protocol

Для поддержки импорта модулей и инициализированных пакетов, а также для внесения частей в пространственно-именованные пакеты, искатели записей пути должны реализовывать метод find_spec().

find_spec() принимает два аргумента: полное имя импортируемого модуля и (необязательный) целевой модуль. find_spec() возвращает полностью заполненную спецификацию для модуля. В этой спецификации всегда будет установлен атрибут «loader» (за одним исключением).

Чтобы указать механизму импорта, что спецификация представляет часть пространства имён, поисковик записи пути устанавливает «submodule_search_locations» в список, содержащий эту часть.

5.8.1. __main__.__spec__¶

В зависимости от того, как инициализируется __main__, __main__.__spec__ устанавливается соответствующим образом или в None.

Когда Python запускается с опцией -m, __spec__ устанавливается в спецификацию модуля соответствующего модуля или пакета. __spec__ также заполняется, когда модуль __main__ загружается при выполнении каталога, zip-файла или другой записи sys.path.

In the remaining cases __main__.__spec__ is set to None, as the code used to populate the __main__ does not correspond directly with an importable module:

• интерактивная подсказка

• -c опция

• запуск из stdin

• запуск напрямую из исходного или байт-код файла

Обратите внимание, что __main__.__spec__ всегда None в последнем случае, даже если файл технически можно импортировать напрямую как модуль. Используйте флаг -m, если нужны корректные метаданные модуля в __main__.

Также обратите внимание, что даже если __main__ соответствует импортируемому модулю и __main__.__spec__ установлено соответствующим образом, они всё равно считаются отдельными модулями. Это связано с тем, что блоки, защищённые проверками if __name__ == "__main__":, выполняются только тогда, когда модуль используется для заполнения пространства имён __main__, а не при обычном импорте.