importlib — Реализация импорта

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

31.5.1. Введение

Цель пакета importlib двояка. Одна — предоставить реализацию оператора import (и, следовательно, функции __import__()) в исходном коде Python. Это обеспечивает реализацию оператора import, которая портативна для любого интерпретатора Python. Это также обеспечивает реализацию, которая проще для понимания, чем реализация на языке программирования, отличном от Python.

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

31.5.2. Функции

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 – Абстрактные базовые классы, связанные с импортом

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

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

Иерархия АБК:

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)

Метод устаревшей версии для поиска загрузчика для указанного модуля. Возвращает 2-кортеж (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(). Когда этот метод существует, create_module() также должен быть определён.

Введено в версии 3.4.

Изменено в версии 3.6: create_module() также должен быть определён.

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)

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

Введено в версии 3.3.

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

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

class importlib.abc.ResourceLoader

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

abstractmethod get_data(path)

Абстрактный метод для возвращения байтов данных, расположенных по адресу path. Загрузчики с хранилищем, подобным файловому, которое позволяет хранить произвольные данные, могут реализовать этот абстрактный метод для прямого доступа к сохранённым данным. OSError поднимется, если path не найден. Ожидается, что 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)

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

Изменено в версии 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 – Импортеры и хуки путей

Исходный код: 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

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

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

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

Устаревшее начиная с версии 3.6: Используйте вместо этого конфигурацию site. В будущих версиях Python этот поисковик может быть не включён по умолчанию.

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. Если найдено ненулевое значение, оно используется как поисковик по пути для поиска модуля. Если в 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 — это переменное число кортежей из 2 элементов, каждый из которых содержит загрузчик и последовательность суффиксов файлов, которые распознаёт этот загрузчик. Загрузчики предполагаются вызываемыми объектами, принимающими два аргумента: имя модуля и путь к найденному файлу.

Поисковик будет кешировать содержимое директории по мере необходимости, вызывая 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(), где указание имени загружаемого модуля является необязательным.

Устаревшее начиная с версии 3.6: Используйте importlib.abc.Loader.exec_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(), где указание имени загружаемого модуля является необязательным.

Устаревшее начиная с версии 3.6: Используйте importlib.abc.Loader.exec_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)

Описание состояния модуля, связанного с системой импорта. Обычно это атрибут модуля __spec__. В описаниях ниже имена в скобках соответствуют атрибутам, доступным непосредственно в объекте модуля. Например, module.__spec__.origin == module.__file__. Однако, хотя значения обычно эквивалентны, они могут отличаться, так как нет синхронизации между двумя объектами. Таким образом, возможно обновление атрибута модуля __path__ во время выполнения, и это не будет автоматически отражено в __spec__.submodule_search_locations.

Новое в версии 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 – Утилиты для импортёров

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

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

importlib.util.MAGIC_NUMBER

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

Добавлено в версии 3.4.

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

Возвращает путь к файлу с байткодом, связанному с исходным файлом path, по PEP 3147/PEP 488. Например, если path равно /foo/bar/baz.py, то возвращаемое значение будет /foo/bar/__pycache__/baz.cpython-32.pyc для Python 3.2. Строка cpython-32 взята из текущего магического тега (см. 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 не определены, будет поднято исключение TypeError.

Добавлено в версии 3.4.

Изменено в версии 3.5: Добавлен параметр optimization, параметр debug_override устарел.

Изменено в версии 3.6: Принимает объект, подобный пути.

importlib.util.source_from_cache(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.

Изменено в версии 3.6: Принимает объект, подобный пути.

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__ (если спецификация была бы None или не установлена, в этом случае генерируется исключение ValueError). В противном случае выполняется поиск с использованием sys.meta_path. Если спецификация не найдена, возвращается None.

Если 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. Функция использует доступные API загрузчика, такие как InspectLoader.is_package(), чтобы заполнить любые недостающие данные в спецификации.

Добавлена в версии 3.4.

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

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

Добавлена в версии 3.4.

Изменено в версии 3.6: Принимает объект пути.

class importlib.util.LazyLoader(loader)

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

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

Примечание

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

Добавлена в версии 3.5.

Изменено в версии 3.6: Начал вызывать create_module(), удалив предупреждение о совместимости для importlib.machinery.BuiltinImporter и importlib.machinery.ExtensionFileLoader.

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))

31.5.6. Примеры

31.5.6.1. Программный импорт

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

import importlib

itertools = importlib.import_module('itertools')

31.5.6.2. Проверка возможности импорта модуля

Если нужно определить, можно ли импортировать модуль, не выполняя сам импорт, используйте importlib.util.find_spec().

import importlib.util
import sys

# For illustrative purposes.
name = 'itertools'

spec = importlib.util.find_spec(name)
if spec is None:
    print("can't find the itertools module")
else:
    # If you chose to perform the actual import ...
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    # Adding the module to sys.modules is optional.
    sys.modules[name] = module

31.5.6.3. Прямой импорт файла исходного кода

Для прямого импорта файла Python (только для Python 3.5 и новее) используйте следующий способ:

import importlib.util
import sys

# For illustrative purposes.
import tokenize
file_path = tokenize.__file__
module_name = tokenize.__name__

spec = importlib.util.spec_from_file_location(module_name, file_path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
# Optional; only necessary if you want to be able to import the module
# by name later.
sys.modules[module_name] = module

31.5.6.4. Настройка импортёра

Для глубокой настройки импорта, обычно необходимо реализовать импортер. Это означает управление как поисковиком, так и загрузчиком. Для поисковиков есть два варианта на выбор в зависимости от ваших потребностей: поисковик мета-пути или поисковик записи пути. Первый используется для sys.meta_path, а второй создается с помощью обработчика записи пути в sys.path_hooks, который работает с записями в sys.path для потенциального создания поисковика. Этот пример покажет, как зарегистрировать собственные импортеры, чтобы импорт использовал их (для создания собственного импортера, прочитайте документацию по соответствующим классам, определенным в этом пакете):

import importlib.machinery
import sys

# For illustrative purposes only.
SpamMetaPathFinder = importlib.machinery.PathFinder
SpamPathEntryFinder = importlib.machinery.FileFinder
loader_details = (importlib.machinery.SourceFileLoader,
                  importlib.machinery.SOURCE_SUFFIXES)

# Setting up a meta path finder.
# Make sure to put the finder in the proper location in the list in terms of
# priority.
sys.meta_path.append(SpamMetaPathFinder)

# Setting up a path entry finder.
# Make sure to put the path hook in the proper location in the list in terms
# of priority.
sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))

31.5.6.5. Аппроксимация importlib.import_module()

Сам импорт реализован на языке Python, что позволяет экспонировать большую часть механизма импорта через importlib. Следующее поможет проиллюстрировать различные API, которые importlib предоставляет, предоставив приблизительную реализацию importlib.import_module() (Python 3.4 и новее для использования importlib, Python 3.6 и новее для других частей кода).

import importlib.util
import sys

def import_module(name, package=None):
    """An approximate implementation of import."""
    absolute_name = importlib.util.resolve_name(name, package)
    try:
        return sys.modules[absolute_name]
    except KeyError:
        pass

    path = None
    if '.' in absolute_name:
        parent_name, _, child_name = absolute_name.rpartition('.')
        parent_module = import_module(parent_name)
        path = parent_module.__spec__.submodule_search_locations
    for finder in sys.meta_path:
        spec = finder.find_spec(absolute_name, path)
        if spec is not None:
            break
    else:
        msg = f'No module named {absolute_name!r}'
        raise ModuleNotFoundError(msg, name=absolute_name)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    sys.modules[absolute_name] = module
    if path is not None:
        setattr(parent_module, child_name, module)
    return module