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

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

1. Введение

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

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

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 и квалифицированные имена (модуль.имя).

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

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

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

Введено в версии 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)

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

Введено в версии 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__.

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

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» модуля на загружаемое местоположение.

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)

Возвращает путь PEP 3147/PEP 488 к файлу скомпилированных байтов, связанному с исходным путём path. Например, если 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 не None, поднимается исключение TypeError.

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

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

importlib.util.source_from_cache(path)

Учитывая путь к имени файла PEP 3147, верните путь к соответствующему файлу исходного кода. Например, если путь равен /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)

Найти спецификацию модуля, необязательно относительно указанного имени 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)), для которого второй аргумент будет объектом модуля object, который будет использоваться загрузчиком. Обратите внимание, что декоратор не будет работать с статическими методами из-за предположения о двух аргументах.

Декорированный метод будет принимать имя загружаемого модуля, как ожидается для загрузчика. Если модуль не найден в 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.

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