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

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

Python определяет два типа пакетов: обычные пакеты и пакеты пространств имён. Обычные пакеты – это традиционные пакеты, существовавшие в Python 3.2 и ранее. Обычный пакет обычно реализуется как каталог, содержащий файл __init__.py. При импорте обычного пакета этот файл __init__.py неявно выполняется, и объекты, которые он определяет, привязываются к именам в пространстве имён пакета. Файл __init__.py может содержать тот же код Python, что и любой другой модуль, и Python добавит в модуль некоторые дополнительные атрибуты при его импорте.

Например, следующая структура файловой системы определяет пакет верхнего уровня 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, то возбуждается ImportError. Если имя модуля отсутствует, Python продолжит поиск модуля.

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

Однако будьте осторожны: если сохранить ссылку на объект модуля, сделать недействительной его запись в кеше sys.modules, а затем повторно импортировать именованный модуль, эти два объекта модуля не будут одинаковыми. Напротив, imp.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_module(), который принимает два аргумента: имя и путь импорта. Мета-искатель пути может использовать любую стратегию, чтобы определить, может ли он обработать именованный модуль.

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

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

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

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

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

5.4.1. Представления модулей¶Module reprs

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

Загрузчики могут реализовать метод module_repr(), который принимает один аргумент – объект модуля. Когда repr(module) вызывается для модуля с загрузчиком, поддерживающим этот протокол, все, что возвращается из module.__loader__.module_repr(module), возвращается в качестве представления модуля без дальнейшей обработки. Возвращаемое значение должно быть строкой.

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

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

• Если у модуля есть __loader__ и у этого загрузчика есть метод module_repr(), вызвать его с одним аргументом – объектом модуля. Возвращенное значение используется как представление модуля.
• Если в module_repr() возникает исключение, оно перехватывается и отбрасывается, а вычисление представления модуля продолжается так, как если бы module_repr() не существовало.
• Если у модуля есть атрибут __file__, он используется как часть repr модуля.
• Если у модуля нет __file__, но есть __loader__, то представление загрузчика используется как часть представления модуля.
• В противном случае в repr используется просто __name__ модуля.

Этот пример из PEP 420 показывает, как загрузчик может создать собственное представление модуля:

class NamespaceLoader:
    @classmethod
    def module_repr(cls, module):
        return "<module '{}' (namespace)>".format(module.__name__)

5.4.2. 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.5.1. Искатели записей пути¶Path entry finders

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

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

Three variables are used by the path based finder, sys.path, sys.path_hooks and sys.path_importer_cache. The __path__ attributes on package objects are also used. These provide additional ways that the import machinery can be customized.

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

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

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

Если записи пути нет в кэше, поисковик на основе путей перебирает все вызываемые объекты в sys.path_hooks. Каждый обработчик записи пути из этого списка вызывается с одним аргументом – записью пути, которую нужно найти. Этот вызываемый объект может либо вернуть поисковик записи пути, способный обработать данную запись пути, либо возбудить ImportError. ImportError используется поисковиком на основе путей, чтобы сообщить, что обработчик не может найти поисковик записи пути для данной записи пути. Исключение игнорируется, и обход пути импорта продолжается. Обработчик должен ожидать строковый или байтовый объект; кодировка байтовых объектов определяется обработчиком (например, это может быть кодировка файловой системы, UTF-8 или что-то ещё), и если обработчик не может декодировать аргумент, он должен возбудить ImportError.

Если обход sys.path_hooks завершается без возврата поисковика записи пути, метод find_module() поисковика на основе путей сохранит None в sys.path_importer_cache (чтобы указать, что для этой записи пути нет поисковика) и вернёт None, показывая, что данный поисковик метапути не смог найти модуль.

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 loader, which is then used to load the module.

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

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

find_loader() принимает один аргумент – полностью квалифицированное имя импортируемого модуля. find_loader() возвращает кортеж из двух элементов: первый – загрузчик, второй – часть пространства имён. Когда первый элемент (т.е. загрузчик) равен None, это означает, что, хотя поисковик записи пути не имеет загрузчика для указанного модуля, он знает, что данная запись пути вносит вклад в часть пространства имён для указанного модуля. Это почти всегда происходит, когда Python просят импортировать пакет пространства имён, не имеющий физического представления в файловой системе. Когда поисковик записи пути возвращает None в качестве загрузчика, второй элемент возвращаемого кортежа из двух элементов должен быть последовательностью, хотя она может быть пустой.

Если find_loader() возвращает значение загрузчика, отличное от None, порция игнорируется, и загрузчик возвращается из поисковика на основе путей, завершая поиск по записям пути.

Для обратной совместимости с другими реализациями протокола импорта многие поисковики пути также поддерживают тот же традиционный метод find_module(), который поддерживают мета-поисковики. Однако методы find_module() поисковика пути никогда не вызываются с аргументом path (ожидается, что они записывают соответствующую информацию о пути из начального вызова хука пути).

Метод find_module() у поисковиков записей пути является устаревшим, поскольку он не позволяет поисковику записи пути вносить вклад в пакеты пространств имён. Вместо этого поисковики записей пути должны реализовывать метод find_loader(), как описано выше. Если этот метод существует в поисковике записи пути, система импорта всегда будет вызывать find_loader() в предпочтение find_module().