31.5. importlib – Реализация import¶importlib – The implementation of import

31.5.1. Введение¶Introduction

Назначение пакета importlib двоякое. Во-первых, предоставить реализацию оператора import (а значит, и функции __import__()) в исходном коде Python. Это даёт реализацию import, переносимую в любой интерпретатор Python. Кроме того, такая реализация легче для понимания, чем написанная на другом языке программирования.

Вторая – в этом пакете предоставлены компоненты для реализации import, что упрощает пользователям создание собственных объектов (обобщённо называемых importer) для участия в процессе импорта.

31.5.2. Функции¶Functions

importlib.__import__(name, globals=None, locals=None, fromlist=(), level=0)¶

Реализация встроенной функции __import__().

Примечание

Для программного импорта модулей следует использовать import_module() вместо данной функции.

importlib.import_module(name, package=None)¶

Импортирует модуль. Аргумент name задаёт импортируемый модуль в абсолютном или относительном выражении (например, pkg.mod или ..mod). Если имя задано в относительном выражении, то аргумент package должен быть установлен в имя пакета, который будет служить якорем для разрешения имени пакета (например, import_module('..mod', 'pkg.subpkg') импортирует pkg.mod).

Функция import_module() действует как упрощающая обёртка вокруг importlib.__import__(). Это означает, что вся семантика функции проистекает из importlib.__import__(). Самое важное различие между этими двумя функциями заключается в том, что import_module() возвращает указанный пакет или модуль (например, pkg.mod), а __import__() возвращает корневой пакет или модуль (например, pkg).

При динамическом импорте модуля, созданного после запуска интерпретатора (например, создан Python-файл), может потребоваться вызов invalidate_caches(), чтобы новый модуль был замечен системой импорта.

Изменено в версии 3.3: Родительские пакеты импортируются автоматически.

importlib.find_loader(name, path=None)¶

Находит загрузчик для модуля, опционально в пределах указанного path. Если модуль находится в sys.modules, то возвращается sys.modules[name].__loader__ (если только загрузчик не окажется None или не будет установлен; в этом случае возбуждается ValueError). В противном случае выполняется поиск с помощью sys.meta_path. None возвращается, если загрузчик не найден.

Точечное имя не импортирует неявно свои родительские пакеты, так как для этого требуется их загрузка, что может быть нежелательно. Чтобы правильно импортировать подмодуль, необходимо импортировать все родительские пакеты подмодуля и указать правильный аргумент path.

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

Изменено в версии 3.4: Если __loader__ не установлен, возбуждается ValueError, так же как и когда атрибут установлен в None.

Устарело с версии 3.4: Вместо этого используйте importlib.util.find_spec().

importlib.invalidate_caches()¶

Инвалидирует внутренние кеши искателей, хранящиеся в sys.meta_path. Если искатель реализует invalidate_caches(), то он будет вызван для выполнения инвалидации. Эту функцию следует вызывать при создании или установке любых модулей во время работы программы, чтобы гарантировать, что все искатели заметят существование нового модуля.

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

importlib.reload(module)¶

Перезагружает ранее импортированный модуль. Аргумент должен быть объектом модуля, то есть он должен быть успешно импортирован ранее. Это полезно, если вы отредактировали исходный файл модуля во внешнем редакторе и хотите опробовать новую версию, не выходя из интерпретатора Python. Возвращаемое значение – объект модуля (который может отличаться, если повторный импорт помещает другой объект в sys.modules).

Когда выполняется reload():

• Код модуля Python перекомпилируется, а код уровня модуля выполняется заново, создавая новый набор объектов, которые привязываются к именам в словаре модуля путём повторного использования загрузчика, который изначально загрузил модуль. Функция init модулей расширения не вызывается повторно.
• Как и все другие объекты в Python, старые объекты освобождаются только после того, как счётчики ссылок на них упадут до нуля.
• Имена в пространстве имён модуля обновляются, чтобы указывать на новые или изменённые объекты.
• Другие ссылки на старые объекты (например, имена вне модуля) не перепривязываются для указания на новые объекты и должны быть обновлены в каждом пространстве имён, где они встречаются, если это необходимо.

Существует ряд других предостережений:

При перезагрузке модуля его словарь (содержащий глобальные переменные модуля) сохраняется. Переопределения имён заменяют старые определения, так что это обычно не проблема. Если новая версия модуля не определяет имя, которое было определено старой версией, старое определение сохраняется. Эта возможность может быть использована в пользу модуля, если он поддерживает глобальную таблицу или кеш объектов – с помощью оператора try можно проверить наличие таблицы и пропустить её инициализацию, если требуется:

try:
    cache
except NameError:
    cache = {}

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

Если модуль импортирует объекты из другого модуля с помощью from … import …, вызов reload() для другого модуля не переопределяет импортированные из него объекты – один из способов обойти это – повторно выполнить оператор from, другой – использовать import и полные имена (module.name) вместо этого.

Если модуль создаёт экземпляры класса, перезагрузка модуля, в котором определён класс, не влияет на определения методов этих экземпляров – они продолжают использовать старое определение класса. То же самое верно и для производных классов.

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

31.5.3. importlib.abc – Абстрактные базовые классы, связанные с импортом¶importlib.abc – Abstract base classes related to import

Исходный код: Lib/importlib/abc.py

Модуль importlib.abc содержит все основные абстрактные базовые классы, используемые import. Также предоставляются некоторые подклассы основных абстрактных базовых классов, помогающие в реализации основных ABC.

Иерархия ABC:

object
 +-- Finder (deprecated)
 |    +-- MetaPathFinder
 |    +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader

class importlib.abc.Finder¶

Абстрактный базовый класс, представляющий искатель.

Устарело с версии 3.3: Используйте MetaPathFinder или PathEntryFinder вместо этого.

abstractmethod find_module(fullname, path=None)¶

Абстрактный метод для поиска загрузчика для указанного модуля. Изначально описан в PEP 302; этот метод предназначался для использования в sys.meta_path и в подсистеме импорта на основе путей.

Изменено в версии 3.4: При вызове возвращает None вместо возбуждения NotImplementedError.

class importlib.abc.MetaPathFinder¶

Абстрактный базовый класс, представляющий мета-поисковик путей. Для совместимости это подкласс Finder.

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

find_spec(fullname, path, target=None)¶

Абстрактный метод для поиска спецификации для указанного модуля. Если это импорт верхнего уровня, path будет равняться None. В противном случае выполняется поиск подпакета или модуля, и path будет значением __path__ из родительского пакета. Если спецификацию не удаётся найти, возвращается None. При передаче параметра target представляет собой объект модуля, который искатель может использовать для принятия более обоснованного решения о том, какую спецификацию вернуть.

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

find_module(fullname, path)¶

Устаревший метод для поиска загрузчика для указанного модуля. Если это импорт верхнего уровня, path будет равен None. В противном случае выполняется поиск подпакета или модуля и path будет значением __path__ из родительского пакета. Если загрузчик не найден, None возвращается.

Если определён find_spec(), обеспечивается обратно совместимая функциональность.

Изменено в версии 3.4: Возвращает None при вызове вместо возбуждения NotImplementedError. Можно использовать find_spec() для обеспечения функциональности.

Устарело с версии 3.4: Вместо этого используйте find_spec().

invalidate_caches()¶

Необязательный метод, который при вызове должен инвалидировать любой внутренний кеш, используемый искателем. Используется importlib.invalidate_caches() при инвалидации кешей всех искателей на sys.meta_path.

Изменено в версии 3.4: Возвращает None при вызове вместо NotImplemented.

class importlib.abc.PathEntryFinder¶

Абстрактный базовый класс, представляющий поисковик записей пути. Хотя он имеет некоторое сходство с MetaPathFinder, PathEntryFinder предназначен для использования только в подсистеме импорта на основе путей, предоставляемой PathFinder. Этот ABC является подклассом Finder только для совместимости.

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

find_spec(fullname, target=None)¶

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

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

find_loader(fullname)¶

Устаревший метод для поиска загрузчика для указанного модуля. Возвращает кортеж из двух элементов (loader, portion), где portion – последовательность местоположений файловой системы, вносящих вклад в часть пакета пространства имён. Загрузчик может быть None, а portion указывает на вклад местоположений файловой системы в пакет пространства имён. Пустой список можно использовать для portion, чтобы указать, что загрузчик не является частью пакета пространства имён. Если loader равен None и portion – пустой список, то загрузчик или местоположение для пакета пространства имён не найдены (т.е. не удалось ничего найти для модуля).

Если определён find_spec(), обеспечивается обратно совместимая функциональность.

Изменено в версии 3.4: Возвращает (None, []) вместо возбуждения NotImplementedError. Использует find_spec() при наличии для обеспечения функциональности.

Устарело с версии 3.4: Вместо этого используйте find_spec().

find_module(fullname)¶

Конкретная реализация Finder.find_module(), эквивалентная self.find_loader(fullname)[0].

Устарело с версии 3.4: Вместо этого используйте find_spec().

invalidate_caches()¶

Необязательный метод, который при вызове должен аннулировать любой внутренний кэш, используемый поисковиком. Используется PathFinder.invalidate_caches() при аннулировании кэшей всех кэшированных поисковиков.

class importlib.abc.Loader¶

Абстрактный базовый класс для загрузчика. См. PEP 302 для точного определения загрузчика.

create_module(spec)¶

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

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

Изменено в версии 3.5: Начиная с Python 3.6, этот метод перестанет быть необязательным, если определён exec_module().

exec_module(module)¶

Абстрактный метод, который выполняет модуль в его собственном пространстве имён при импорте или перезагрузке модуля. Модуль должен уже быть инициализирован к моменту вызова exec_module().

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

load_module(fullname)¶

Устаревший метод загрузки модуля. Если модуль не может быть загружен, вызывается ImportError, иначе возвращается загруженный модуль.

Если запрошенный модуль уже существует в sys.modules, то следует использовать и перезагрузить именно его. В противном случае загрузчик должен создать новый модуль и вставить его в sys.modules до начала загрузки, чтобы избежать рекурсии при импорте. Если загрузчик вставил модуль, но загрузка завершилась неудачей, он должен удалить его из sys.modules; модули, уже находившиеся в sys.modules до начала работы загрузчика, следует оставить нетронутыми (см. importlib.util.module_for_loader()).

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

• __name__

  Имя модуля.

• __file__

  Путь к месту хранения данных модуля (не задан для встроенных модулей).

• __cached__

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

• __path__

  Список строк, задающих путь поиска внутри пакета. Этот атрибут не задан для модулей.

• __package__

  Родительский пакет модуля или пакета. Если модуль является корневым, то его значением является пустая строка. importlib.util.module_for_loader() декоратор может обработать детали для __package__.

• __loader__

  Загрузчик, используемый для загрузки модуля. Декоратор importlib.util.module_for_loader() может самостоятельно обработать детали для __package__.

Если exec_module() доступен, то предоставляется обратно совместимая функциональность.

Изменено в версии 3.4: Возбуждает ImportError при вызове вместо NotImplementedError. Функциональность доступна, если exec_module() присутствует.

Устарело с версии 3.4: Рекомендуемый API для загрузки модуля – exec_module() (и create_module()). Загрузчики должны реализовывать его вместо load_module(). Механизм импорта берёт на себя все остальные обязанности load_module(), когда реализован exec_module().

module_repr(module)¶

Устаревший метод, который при реализации вычисляет и возвращает строковое представление заданного модуля в виде строки. Стандартный repr() для типа модуля будет использовать результат этого метода по необходимости.

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

Изменено в версии 3.4: Сделано необязательным вместо абстрактного метода.

Устарело с версии 3.4: Механизм импорта теперь заботится об этом автоматически.

class importlib.abc.ResourceLoader¶

Абстрактный базовый класс для загрузчика, который реализует опциональный протокол PEP 302 для загрузки произвольных ресурсов из бэкенда хранилища.

abstractmethod get_data(path)¶

Абстрактный метод, возвращающий байты для данных, расположенных по пути path. Загрузчики, использующие файлоподобное хранилище, позволяющее хранить произвольные данные, могут реализовать этот абстрактный метод, чтобы обеспечить прямой доступ к хранимым данным. Если path не найден, возбуждается OSError. Ожидается, что path будет сформирован с использованием атрибута __file__ модуля или элемента из __path__ пакета.

Изменено в версии 3.4: возбуждает OSError вместо NotImplementedError.

class importlib.abc.InspectLoader¶

Абстрактный базовый класс для загрузчика, который реализует опциональный протокол PEP 302 для загрузчиков, которые инспектируют модули.

get_code(fullname)¶

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

Примечание

Хотя метод имеет реализацию по умолчанию, рекомендуется переопределить его, если это возможно для повышения производительности.

Изменено в версии 3.4: Больше не является абстрактным, предоставлена конкретная реализация.

abstractmethod get_source(fullname)¶

Абстрактный метод, возвращающий исходный код модуля. Он возвращается в виде текстовой строки с использованием универсальных символов новой строки, преобразуя все распознанные разделители строк в символы '\n'. Возвращает None, если исходный код недоступен (например, для встроенного модуля). Возбуждает ImportError, если загрузчик не может найти указанный модуль.

Изменено в версии 3.4: возбуждает ImportError вместо NotImplementedError.

is_package(fullname)¶

Абстрактный метод, возвращающий истинное значение, если модуль является пакетом, и ложное в противном случае. ImportError возбуждается, если loader не может найти модуль.

Изменено в версии 3.4: возбуждает ImportError вместо NotImplementedError.

static source_to_code(data, path='<string>')¶

Создаёт объект кода из исходного кода Python.

Аргумент data может быть любым значением, которое поддерживает функция compile() (т.е. строка или байты). Аргумент path должен быть «путём» к месту происхождения исходного кода, что может быть абстрактным понятием (например, местоположение в zip-файле).

С помощью полученного объекта кода можно выполнить его в модуле, запустив exec(code, module.__dict__).

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

Изменено в версии 3.5: метод стал статическим.

exec_module(module)¶

Реализация Loader.exec_module().

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

load_module(fullname)¶

Реализация Loader.load_module().

Устарело с версии 3.4: используйте exec_module().

class importlib.abc.ExecutionLoader¶

Абстрактный базовый класс, наследующий от InspectLoader, который при реализации помогает выполнять модуль как скрипт. Этот ABC представляет необязательный протокол PEP 302.

abstractmethod get_filename(fullname)¶

Абстрактный метод, который должен возвращать значение __file__ для указанного модуля. Если путь недоступен, возбуждается ImportError.

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

Изменено в версии 3.4: возбуждает ImportError вместо NotImplementedError.

class importlib.abc.FileLoader(fullname, path)¶

Абстрактный базовый класс, наследующий от ResourceLoader и ExecutionLoader, предоставляющий конкретные реализации ResourceLoader.get_data() и ExecutionLoader.get_filename().

Аргумент fullname – это полное разрешённое имя модуля, который должен обрабатывать загрузчик. Аргумент path – путь к файлу модуля.

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

name¶

Имя модуля, который может обрабатывать загрузчик.

path¶

Путь к файлу модуля.

load_module(fullname)¶

Вызывает load_module() родительского класса.

Устарело с версии 3.4: Вместо этого используйте Loader.exec_module().

abstractmethod get_filename(fullname)¶

Возвращает path.

abstractmethod get_data(path)¶

Читает path как двоичный файл и возвращает байты из него.

class importlib.abc.SourceLoader¶

Абстрактный базовый класс для реализации загрузки файлов с исходным кодом (и, опционально, байткодом). Класс наследует от ResourceLoader и ExecutionLoader, требуя реализации:

• ResourceLoader.get_data()

• ExecutionLoader.get_filename()

  Должен возвращать только путь к файлу исходного кода; загрузка без исходного кода не поддерживается.

Абстрактные методы, определённые в этом классе, предназначены для добавления опциональной поддержки файлов байткода. Если не реализовать эти опциональные методы (или заставить их возбуждать NotImplementedError), загрузчик будет работать только с исходным кодом. Реализация методов позволяет загрузчику работать с файлами исходного кода и байткода; это не допускает загрузку без исходного кода, когда предоставляется только байткод. Файлы байткода – это оптимизация для ускорения загрузки за счёт удаления этапа разбора компилятором Python, поэтому никакой специальный API для байткода не предоставляется.

path_stats(path)¶

Опциональный абстрактный метод, возвращающий dict, содержащий метаданные о заданном пути. Поддерживаемые ключи словаря:

• 'mtime' (обязательный): целое число или число с плавающей точкой, представляющее время изменения исходного кода;
• 'size' (необязательный): размер исходного кода в байтах.

Любые другие ключи в словаре игнорируются – это позволяет добавлять расширения в будущем. Если с путём не удаётся работать, возбуждается OSError.

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

Изменено в версии 3.4: Теперь возбуждается OSError вместо NotImplementedError.

path_mtime(path)¶

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

Устарело с версии 3.3: Этот метод устарел в пользу path_stats(). Реализовывать его необязательно, но он всё ещё доступен для совместимости. Если путь не удаётся обработать, возбуждается OSError.

Изменено в версии 3.4: Теперь возбуждается OSError вместо NotImplementedError.

set_data(path, data)¶

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

Если запись по пути не удаётся из-за того, что путь доступен только для чтения (errno.EACCES/PermissionError), исключение не должно распространяться.

Изменено в версии 3.4: Больше не возбуждает NotImplementedError при вызове.

get_code(fullname)¶

Конкретная реализация InspectLoader.get_code().

exec_module(module)¶

Конкретная реализация Loader.exec_module().

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

load_module(fullname)¶

Конкретная реализация Loader.load_module().

Устарело с версии 3.4: Вместо этого используйте exec_module().

get_source(fullname)¶

Конкретная реализация InspectLoader.get_source().

is_package(fullname)¶

Конкретная реализация InspectLoader.is_package(). Модуль считается пакетом, если его путь к файлу (получаемый через ExecutionLoader.get_filename()) представляет собой файл с именем __init__ после удаления расширения и само имя модуля не оканчивается на __init__.

31.5.4. importlib.machinery – Импортёры и перехватчики путей¶importlib.machinery – Importers and path hooks

Исходный код: Lib/importlib/machinery.py

Этот модуль содержит различные объекты, помогающие import находить и загружать модули.

importlib.machinery.SOURCE_SUFFIXES¶

Список строк, представляющих распознаваемые расширения файлов для исходных модулей.

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

importlib.machinery.DEBUG_BYTECODE_SUFFIXES¶

Список строк, представляющих расширения файлов для неоптимизированных байт-код модулей.

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

Устарело с версии 3.5: Используйте BYTECODE_SUFFIXES вместо.

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES¶

Список строк с расширениями файлов для оптимизированных модулей байткода.

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

Устарело с версии 3.5: Используйте BYTECODE_SUFFIXES вместо.

importlib.machinery.BYTECODE_SUFFIXES¶

Список строк с распознаваемыми расширениями файлов для модулей байткода (включая начальную точку).

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

Изменено в версии 3.5: Значение больше не зависит от __debug__.

importlib.machinery.EXTENSION_SUFFIXES¶

Список строк с распознаваемыми расширениями файлов для модулей расширений.

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

importlib.machinery.all_suffixes()¶

Возвращает объединённый список строк со всеми расширениями файлов для модулей, распознаваемых стандартным механизмом импорта. Это вспомогательная функция для кода, которому нужно лишь узнать, может ли путь файловой системы относиться к модулю, без необходимости в деталях о типе модуля (например, inspect.getmodulename()).

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

class importlib.machinery.BuiltinImporter¶

Импортёр для встроенных модулей. Все известные встроенные модули перечислены в sys.builtin_module_names. Этот класс реализует абстрактные базовые классы importlib.abc.MetaPathFinder и importlib.abc.InspectLoader.

В этом классе определены только методы класса, чтобы не было необходимости в создании экземпляров.

Изменено в версии 3.5: В рамках PEP 489 встроенный импортёр теперь реализует Loader.create_module() и Loader.exec_module().

class importlib.machinery.FrozenImporter¶

Импортёр для замороженных модулей. Этот класс реализует абстрактные базовые классы importlib.abc.MetaPathFinder и importlib.abc.InspectLoader.

В этом классе определены только методы класса, чтобы не было необходимости в создании экземпляров.

class importlib.machinery.WindowsRegistryFinder¶

Finder для модулей, объявленных в реестре Windows. Этот класс реализует абстрактный базовый класс importlib.abc.Finder.

В этом классе определены только методы класса, чтобы не было необходимости в создании экземпляров.

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

class importlib.machinery.PathFinder¶

Искатель для sys.path и атрибутов пакета __path__. Этот класс реализует абстрактный базовый класс importlib.abc.MetaPathFinder.

В этом классе определены только методы класса, чтобы не было необходимости в создании экземпляров.

classmethod find_spec(fullname, path=None, target=None)¶

Метод класса, который пытается найти спецификацию для модуля, заданного fullname на sys.path или, если определён, на path. Для каждого просматриваемого элемента пути проверяется sys.path_importer_cache. Если найден объект, не равный false, то он используется как искатель элемента пути для поиска искомого модуля. Если элемент не найден в sys.path_importer_cache, то sys.path_hooks ищется искатель для элемента пути, и если найден, сохраняется в sys.path_importer_cache, а также запрашивается о модуле. Если искатель так и не найден, то None сохраняется в кеше и возвращается.

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

Изменено в версии 3.5: Если текущая рабочая директория – представленная пустой строкой – больше не является допустимой, то возвращается None, но значение не кешируется в sys.path_importer_cache.

classmethod find_module(fullname, path=None)¶

Устаревшая обёртка для find_spec().

Устарело с версии 3.4: Вместо этого используйте find_spec().

classmethod invalidate_caches()¶

Вызывает importlib.abc.PathEntryFinder.invalidate_caches() для всех искателей, хранящихся в sys.path_importer_cache.

Изменено в версии 3.4: Вызывает объекты в sys.path_hooks, передавая текущую рабочую директорию в качестве '' (т.е. пустую строку).

class importlib.machinery.FileFinder(path, *loader_details)¶

Конкретная реализация importlib.abc.PathEntryFinder, которая кеширует результаты из файловой системы.

Аргумент path – это каталог, за поиск в котором отвечает искатель.

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

Искатель будет кешировать содержимое каталога по мере необходимости, вызывая stat для каждого поиска модуля, чтобы убедиться, что кеш не устарел. Поскольку устаревание кеша зависит от гранулярности информации о состоянии файловой системы, предоставляемой операционной системой, существует потенциальное состояние гонки: поиск модуля, создание нового файла и последующий поиск модуля, который представляет этот новый файл. Если операции выполняются достаточно быстро, чтобы уложиться в гранулярность вызовов stat, поиск модуля завершится неудачей. Чтобы этого избежать, при динамическом создании модуля обязательно вызывайте importlib.invalidate_caches().

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

path¶

Путь, в котором будет искать искатель.

find_spec(fullname, target=None)¶

Пытается найти спецификацию для обработки fullname внутри path.

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

find_loader(fullname)¶

Пытается найти загрузчик для fullname в path.

invalidate_caches()¶

Очищает внутренний кеш.

classmethod path_hook(*loader_details)¶

Метод класса, возвращающий замыкание для использования в sys.path_hooks. Замыкание возвращает экземпляр FileFinder, используя аргумент path, переданный непосредственно замыканию, и loader_details косвенно.

Если аргумент замыкания не является существующим каталогом, вызывается ImportError.

class importlib.machinery.SourceFileLoader(fullname, path)¶

Конкретная реализация importlib.abc.SourceLoader путём наследования от importlib.abc.FileLoader и предоставления конкретных реализаций других методов.

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

name¶

Имя модуля, который будет обрабатывать этот загрузчик.

path¶

Путь к исходному файлу.

is_package(fullname)¶

Возвращает True, если path, по-видимому, относится к пакету.

path_stats(path)¶

Конкретная реализация importlib.abc.SourceLoader.path_stats().

set_data(path, data)¶

Конкретная реализация importlib.abc.SourceLoader.set_data().

load_module(name=None)¶

Конкретная реализация importlib.abc.Loader.load_module(), где указание имени загружаемого модуля необязательно.

class importlib.machinery.SourcelessFileLoader(fullname, path)¶

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

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

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

name¶

Имя модуля, который будет обрабатывать загрузчик.

path¶

Путь к файлу байт-кода.

is_package(fullname)¶

Определяет, является ли модуль пакетом, на основе path.

get_code(fullname)¶

Возвращает объект кода для name, созданный из path.

get_source(fullname)¶

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

load_module(name=None)¶

Конкретная реализация importlib.abc.Loader.load_module(), где указание имени загружаемого модуля необязательно.

class importlib.machinery.ExtensionFileLoader(fullname, path)¶

Конкретная реализация importlib.abc.ExecutionLoader для модулей-расширений.

Аргумент fullname задаёт имя модуля, который должен поддерживать загрузчик. Аргумент path – это путь к файлу модуля-расширения.

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

name¶

Имя модуля, который поддерживает загрузчик.

path¶

Путь к модулю-расширению.

create_module(spec)¶

Создаёт объект модуля из указанной спецификации в соответствии с PEP 489.

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

exec_module(module)¶

Инициализирует указанный объект модуля в соответствии с PEP 489.

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

is_package(fullname)¶

Возвращает True, если путь к файлу указывает на модуль __init__ пакета на основе EXTENSION_SUFFIXES.

get_code(fullname)¶

Возвращает None, так как у модулей-расширений нет объекта кода.

get_source(fullname)¶

Возвращает None, так как у модулей-расширений нет исходного кода.

get_filename(fullname)¶

Возвращает path.

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

class importlib.machinery.ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)¶

Спецификация состояния модуля, связанного с системой импорта.

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

name¶

(__name__)

Строка с полным именем модуля.

loader¶

(__loader__)

Загрузчик, используемый для загрузки. Для пространств имён пакетов он должен быть установлен в None.

origin¶

(__file__)

Имя места, из которого загружается модуль, например “builtin” для встроенных модулей и имя файла для модулей, загружаемых из исходного кода. Обычно “origin” должен быть установлен, но может быть None (значение по умолчанию), что означает, что он не указан.

submodule_search_locations¶

(__path__)

Список строк, указывающих, где искать подмодули, если это пакет (иначе None).

loader_state¶

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

cached¶

(__cached__)

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

parent¶

(__package__)

(Только для чтения) Полное имя пакета, которому принадлежит модуль как подмодуль (или None).

has_location¶

Логическое значение, указывающее, относится ли атрибут «origin» модуля к загружаемому расположению.

31.5.5. importlib.util – Утилитарный код для импортеров¶importlib.util – Utility code for importers

Исходный код: Lib/importlib/util.py

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

importlib.util.MAGIC_NUMBER¶

Байты, представляющие номер версии байт-кода. Если требуется помощь в загрузке или записи байт-кода, рекомендуется использовать importlib.abc.SourceLoader.

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

importlib.util.cache_from_source(path, debug_override=None, *, optimization=None)¶

Возвращает путь PEP 3147/PEP 488 к скомпилированному в байт-код файлу, связанному с исходным path. Например, если path – /foo/bar/baz.py, возвращаемым значением будет /foo/bar/__pycache__/baz.cpython-32.pyc для Python 3.2. Строка cpython-32 берётся из текущего magic-тега (см. get_tag(); если sys.implementation.cache_tag не задан, то вызывается NotImplementedError).

Параметр optimization используется для указания уровня оптимизации файла байт-кода. Пустая строка означает отсутствие оптимизации, поэтому /foo/bar/baz.py с optimization равным '' приведёт к пути байт-кода /foo/bar/__pycache__/baz.cpython-32.pyc. None приводит к использованию уровня оптимизации интерпретатора. Используется строковое представление любого другого значения, поэтому /foo/bar/baz.py с optimization равным 2 приведёт к пути байт-кода /foo/bar/__pycache__/baz.cpython-32.opt-2.pyc. Строковое представление optimization может содержать только буквенно-цифровые символы, иначе вызывается ValueError.

Параметр debug_override устарел и может использоваться для переопределения системного значения __debug__. Значение True эквивалентно установке optimization в пустую строку. Значение False аналогично установке optimization в 1. Если оба debug_override и optimization не равны None, то вызывается TypeError.

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

Изменено в версии 3.5: Был добавлен параметр optimization, а параметр debug_override был объявлен устаревшим.

importlib.util.source_from_cache(path)¶

По заданному path для имени файла PEP 3147 возвращает связанный путь к файлу исходного кода. Например, если path равен /foo/bar/__pycache__/baz.cpython-32.pyc, возвращаемый путь будет /foo/bar/baz.py. path необязательно должен существовать, однако если он не соответствует формату PEP 3147 или PEP 488, вызывается ValueError. Если sys.implementation.cache_tag не определён, вызывается NotImplementedError.

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

importlib.util.decode_source(source_bytes)¶

Декодирует заданные байты, представляющие исходный код, и возвращает их в виде строки с универсальными символами новой строки (как требуется в importlib.abc.InspectLoader.get_source()).

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

importlib.util.resolve_name(name, package)¶

Преобразует относительное имя модуля в абсолютное.

Если name не содержит ведущих точек, то name просто возвращается. Это позволяет использовать такие конструкции, как importlib.util.resolve_name('sys', __package__), без проверки того, требуется ли аргумент package.

ValueError возникает, если name является относительным именем модуля, а package имеет ложное значение (например, None или пустая строка). ValueError также возникает, если относительное имя выходит за пределы содержащего его пакета (например, запрос ..bacon из пакета spam).

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

importlib.util.find_spec(name, package=None)¶

Находит spec для модуля, возможно, относительно указанного имени package. Если модуль находится в sys.modules, возвращается sys.modules[name].__spec__ (если только spec не будет None или не задан, и в этом случае вызывается ValueError). В противном случае выполняется поиск с помощью sys.meta_path. None возвращается, если spec не найден.

Если name относится к подмодулю (содержит точку), родительский модуль импортируется автоматически.

name и package работают так же, как для import_module().

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

importlib.util.module_from_spec(spec)¶

Создает новый модуль на основе spec и spec.loader.create_module().

Если spec.loader.create_module() не возвращает None, то любые существующие атрибуты не будут сброшены. Кроме того, AttributeError не будет вызвано, если оно возникает при обращении к spec или установке атрибута модуля.

Эта функция предпочтительнее использования types.ModuleType для создания нового модуля, так как spec используется для установки как можно большего количества атрибутов, управляемых импортом, на модуле.

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

@importlib.util.module_for_loader¶

Декоратор для importlib.abc.Loader.load_module() для выбора подходящего объекта модуля для загрузки. Ожидается, что декорируемый метод имеет сигнатуру вызова с двумя позиционными аргументами (например, load_module(self, module)), второй из которых будет объектом модуля для использования загрузчиком. Обратите внимание, что декоратор не будет работать со статическими методами из-за предположения о двух аргументах.

Декорируемый метод будет принимать имя модуля для загрузки, как и ожидается для загрузчика. Если модуль не найден в sys.modules, то создается новый. Независимо от того, откуда взялся модуль, __loader__ устанавливается в self, а __package__ устанавливается на основе того, что возвращает importlib.abc.InspectLoader.is_package() (если доступно). Эти атрибуты устанавливаются безусловно для поддержки перезагрузки.

Если декорируемый метод вызывает исключение, а модуль был добавлен в sys.modules, то модуль будет удален, чтобы предотвратить оставление частично инициализированного модуля в sys.modules. Если модуль уже был в sys.modules, то он остается без изменений.

Изменено в версии 3.3: __loader__ и __package__ автоматически устанавливаются (когда это возможно).

Изменено в версии 3.4: Устанавливает __name__, __loader__ __package__ безусловно для поддержки перезагрузки.

Устарело с версии 3.4: Механизм импорта теперь напрямую выполняет все функции, предоставляемые этой функцией.

@importlib.util.set_loader¶

Декоратор для importlib.abc.Loader.load_module() для установки атрибута __loader__ на возвращаемом модуле. Если атрибут уже установлен, декоратор ничего не делает. Предполагается, что первый позиционный аргумент обернутого метода (т.е. self) – это то, на что должно быть установлено __loader__.

Изменено в версии 3.4: Устанавливает __loader__, если установлен в None, как если бы атрибут не существовал.

Устарело с версии 3.4: Механизм импорта заботится об этом автоматически.

@importlib.util.set_package¶

Декоратор для importlib.abc.Loader.load_module(), позволяющий задать атрибут __package__ для возвращаемого модуля. Если __package__ установлен и имеет значение, отличное от None, оно не будет изменено.

Устарело с версии 3.4: Механизм импорта заботится об этом автоматически.

importlib.util.spec_from_loader(name, loader, *, origin=None, is_package=None)¶

Фабричная функция для создания экземпляра ModuleSpec на основе загрузчика. Параметры имеют тот же смысл, что и для ModuleSpec. Функция использует доступные loader API, такие как InspectLoader.is_package(), для заполнения отсутствующей информации о спецификации.

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

importlib.util.spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)¶

Фабричная функция для создания экземпляра ModuleSpec на основе пути к файлу. Отсутствующая информация будет заполнена в спецификации с использованием API загрузчика и с учётом того, что модуль будет файловым.

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

class importlib.util.LazyLoader(loader)¶

Класс, который откладывает выполнение загрузчика модуля до момента обращения к атрибуту модуля.

Этот класс работает только с загрузчиками, которые определяют exec_module(), поскольку требуется контроль над тем, какой тип модуля используется. По тем же причинам метод create_module() загрузчика будет игнорироваться (т.е. метод загрузчика должен возвращать только None; это исключает BuiltinImporter и ExtensionFileLoader). Наконец, модули, которые подменяют объект, помещённый в sys.modules, не будут работать, поскольку нет способа безопасно заменить ссылки на модуль по всему интерпретатору; если такая подмена обнаруживается, возбуждается ValueError.

Примечание

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

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

classmethod factory(loader)¶

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

suffixes = importlib.machinery.SOURCE_SUFFIXES
loader = importlib.machinery.SourceFileLoader
lazy_loader = importlib.util.LazyLoader.factory(loader)
finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))