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

Введение

Цель пакета importlib состоит из трёх пунктов.

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

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

В-третьих, пакет содержит модули, предоставляющие дополнительную функциональность для управления аспектами пакетов Python:

• importlib.metadata предоставляет доступ к метаданным из сторонних дистрибутивов.
• importlib.resources предоставляет функции для доступа к ресурсам, не являющимся кодом, из пакетов Python.

Функции

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

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

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

Изменено в версии 3.10: Пакеты пространств имён, созданные/установленные в другом месте sys.path после импорта того же пространства имён, замечаются.

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.

Изменено в версии 3.7: Возникает ModuleNotFoundError, если перезагружаемый модуль не имеет ModuleSpec.

importlib.abc – Абстрактные базовые классы, связанные с импортом

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

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

Иерархия ABC:

object
 +-- MetaPathFinder
 +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader

class importlib.abc.MetaPathFinder

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

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

Изменён в версии 3.10: Больше не является подклассом Finder.

find_spec(fullname, path, target=None)

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

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

invalidate_caches()

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

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

class importlib.abc.PathEntryFinder

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

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

Изменён в версии 3.10: Больше не является подклассом Finder.

find_spec(fullname, target=None)

Абстрактный метод для поиска спецификации указанного модуля. Поиск будет производиться только в элементе пути, которому он назначен. Если спецификация не найдена, возвращается None. При передаче target — это объект модуля, который поиск может использовать для более точного определения возвращаемой спецификации. importlib.util.spec_from_loader() может быть полезен для реализации конкретного PathEntryFinders.

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

invalidate_caches()

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

class importlib.abc.Loader

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

Загрузчики, которые хотят поддерживать чтение ресурсов, должны реализовать метод get_resource_reader() согласно importlib.resources.abc.ResourceReader.

Изменено в версии 3.7: Введён необязательный метод get_resource_reader().

create_module(spec)

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

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

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

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

• __name__

  Полное квалифицированное имя модуля. Оно является '__main__' для выполненного модуля.

• __file__

  Расположение, которое использовал загрузчик для загрузки модуля. Например, для модулей, загруженных из файла .py, это имя файла. Оно не устанавливается для всех модулей (например, встроенных модулей).

• __cached__

  Имя файла скомпилированной версии кода модуля. Оно не устанавливается для всех модулей (например, встроенных модулей).

• __path__

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

• __package__

  Полное квалифицированное имя пакета, в котором находится модуль (или пустая строка для модуля верхнего уровня). Если модуль является пакетом, то это то же самое, что и __name__.

• __loader__

  Используемый загрузчик для загрузки модуля.

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

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

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

class importlib.abc.ResourceLoader

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

Устарело начиная с версии 3.7: Этот ABC устарел в пользу поддержки загрузки ресурсов через importlib.resources.abc.ResourceReader.

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)

Вызывает super’s 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__.

class importlib.abc.ResourceReader

Заменено на TraversableResources

Абстрактный базовый класс для работы с ресурсами.

С точки зрения этого ABC, ресурс — это двоичный артефакт, входящий в пакет. Обычно это такой файл данных, который находится рядом с файлом __init__.py пакета. Цель этого класса — абстрагировать доступ к таким файлам данных, чтобы неважно, хранятся ли пакет и его файлы данных, например, в файле zip или в файловой системе.

В любом методе этого класса ожидается, что аргумент resource будет объектом-путь, который концептуально представляет только имя файла. Это означает, что пути к подкаталогам не должны включаться в аргумент resource. Это связано с тем, что местоположение пакета, для которого предназначен читатель, выступает в качестве «каталога». Поэтому метафора каталогов и имён файлов — это пакеты и ресурсы соответственно. Это также объясняет, почему экземпляры этого класса ожидается будут напрямую соответствовать определённому пакету (а не потенциально представлять несколько пакетов или модуль).

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

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

Устарел начиная с версии 3.12, будет удалён в версии 3.14: Используйте importlib.resources.abc.TraversableResources вместо этого.

abstractmethod open_resource(resource)

Возвращает открытый объект-поток для двоичного чтения ресурса.

Если ресурс не найден, возникает FileNotFoundError.

abstractmethod resource_path(resource)

Возвращает путь к файлу в файловой системе для ресурса.

Если ресурс не существует в файловой системе, генерируется FileNotFoundError.

abstractmethod is_resource(name)

Возвращает True если указанное имя name считается ресурсом. FileNotFoundError генерируется, если name не существует.

abstractmethod contents()

Возвращает итерируемый набор строк, содержащих содержимое пакета. Обратите внимание, что не требуется, чтобы все имена, возвращаемые итератором, были фактическими ресурсами, например, допустимо возвращать имена, для которых is_resource() будет ложным.

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

Абстрактный метод возвращает итерируемый набор без элементов.

class importlib.abc.Traversable

Объект с подмножеством методов pathlib.Path, подходящих для перемещения по каталогам и открытия файлов.

Для представления объекта в файловой системе используйте importlib.resources.as_file().

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

Устарел начиная с версии 3.12, будет удалён в версии 3.14: Используйте importlib.resources.abc.Traversable вместо этого.

name

Абстрактное. Базовое имя этого объекта без каких-либо ссылок на родителя.

abstractmethod iterdir()

Возвращает итерируемый набор объектов Traversable в self.

abstractmethod is_dir()

Возвращает True если self является каталогом.

abstractmethod is_file()

Возвращает True если self является файлом.

abstractmethod joinpath(child)

Возвращает дочерний Traversable в self.

abstractmethod __truediv__(child)

Возвращает дочерний Traversable в self.

abstractmethod open(mode='r', *args, **kwargs)

mode может быть ‘r’ или ‘rb’ для открытия как текста или двоичных данных. Возвращает обработчик, подходящий для чтения (такой же, как pathlib.Path.open).

При открытии как текста принимает параметры кодирования, такие как те, которые принимаются io.TextIOWrapper.

read_bytes()

Считывает содержимое self в виде байтов.

read_text(encoding=None)

Считывает содержимое self в виде текста.

class importlib.abc.TraversableResources

Абстрактный базовый класс для читателей ресурсов, способных обслуживать интерфейс importlib.resources.files(). Подклассы importlib.resources.abc.ResourceReader и предоставляет конкретные реализации абстрактных методов importlib.resources.abc.ResourceReader. Поэтому любой загрузчик, предоставляющий importlib.abc.TraversableResources, также предоставляет ResourceReader.

Загрузчики, которые хотят поддерживать чтение ресурсов, должны реализовать этот интерфейс.

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

Устарел начиная с версии 3.12, будет удалён в версии 3.14: Используйте importlib.resources.abc.TraversableResources вместо этого.

abstractmethod files()

Возвращает объект importlib.resources.abc.Traversable для загруженного пакета.

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. Этот класс реализует ABC importlib.abc.MetaPathFinder и importlib.abc.InspectLoader.

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

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

class importlib.machinery.FrozenImporter

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

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

Изменено в версии 3.4: Получил методы create_module() и exec_module().

class importlib.machinery.WindowsRegistryFinder

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

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

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

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

class importlib.machinery.PathFinder

Поиск модулей по sys.path и атрибутам пакетов __path__. Этот класс реализует ABC 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 invalidate_caches()

Вызывает importlib.abc.PathEntryFinder.invalidate_caches() для всех обработчиков поиска, хранящихся в sys.path_importer_cache, которые определяют этот метод. В противном случае записи в sys.path_importer_cache с установленным значением None удаляются.

Изменено в версии 3.7: Записи с None в 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.

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 — путь к файлу модуля расширения.

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

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

Изменено в версии 3.12: Многофазная инициализация теперь требуется для использования в подинтерпретаторах.

name

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

path

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

create_module(spec)

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

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

exec_module(module)

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

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

is_package(fullname)

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

get_code(fullname)

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

get_source(fullname)

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

get_filename(fullname)

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

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

class importlib.machinery.NamespaceLoader(name, path, path_finder)

Конкретная реализация importlib.abc.InspectLoader для пакетов имён пространства имён. Это псевдоним для закрытого класса и используется только для получения доступа к атрибуту __loader__ пакетов имён пространства имён:

>>> from importlib.machinery import NamespaceLoader
>>> import my_namespace
>>> isinstance(my_namespace.__loader__, NamespaceLoader)
True
>>> import importlib.abc
>>> isinstance(my_namespace.__loader__, importlib.abc.Loader)
True

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

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

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

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

name

(__name__)

Полное квалифицированное имя модуля. Искатель (finder) всегда должен устанавливать этот атрибут в непустую строку.

loader

(__loader__)

Используемый загрузчик (loader) для загрузки модуля. Искатель (finder) всегда должен устанавливать этот атрибут.

origin

(__file__)

Местоположение, которое загрузчик (loader) должен использовать для загрузки модуля. Например, для модулей, загружаемых из файла .py, это имя файла. Искатель (finder) всегда должен устанавливать этот атрибут в осмысленное значение для использования загрузчиком (loader). В редких случаях, когда его нет (например, для пакетов имён пространства имён), он должен быть установлен в None.

submodule_search_locations

(__path__)

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

loader_state

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

cached

(__cached__)

Имя файла скомпилированной версии кода модуля. Искатель (finder) всегда должен устанавливать этот атрибут, но он может быть None для модулей, которым не нужно хранить скомпилированный код.

parent

(__package__)

(только для чтения) Полное квалифицированное имя пакета, в котором находится модуль (или пустая строка для модуля верхнего уровня). Если модуль является пакетом, то это то же самое, что name.

has_location

True if the spec’s origin refers to a loadable location,

False в противном случае. Это значение влияет на то, как интерпретируется origin и как заполняется атрибут модуля __file__.

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 устарел.

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

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.

Изменено в версии 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', __spec__.parent) без проверки, нужен ли аргумент package.

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

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

Изменено в версии 3.9: Для повышения согласованности с инструкциями импорта, возбуждается ImportError вместо ValueError при недопустимых попытках относительного импорта.

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.

Изменено в версии 3.7: Возбуждает ModuleNotFoundError вместо AttributeError, если package на самом деле не является пакетом (т.е. не имеет атрибута __path__).

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.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: Принимает объект-путь.

importlib.util.source_hash(source_bytes)

Возвращает хэш source_bytes в виде байтов. Файл, основанный на хэше .pyc, встраивает source_hash() содержимого соответствующего исходного файла в его заголовок.

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

importlib.util._incompatible_extension_module_restrictions(*, disable_check)

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

Обратите внимание, что эта функция предназначена для обработки необычного случая; такого, который, вероятно, в конечном итоге исчезнет. Вероятность того, что это не то, что вы искали, довольно высока.

Вы можете получить тот же эффект, что и эта функция, реализовав базовый интерфейс многофазной инициализации (PEP 489) и соврав о поддержке нескольких интерпретаторов (или GIL на интерпретатор).

Предупреждение

Использование этой функции для отключения проверки может привести к неожиданному поведению и даже к сбоям. Она должна использоваться только при разработке модулей расширений.

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

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

Примеры

import importlib

itertools = importlib.import_module('itertools')

import importlib.util
import sys

# For illustrative purposes.
name = 'itertools'

if name in sys.modules:
    print(f"{name!r} already in sys.modules")
elif (spec := importlib.util.find_spec(name)) is not None:
    # If you chose to perform the actual import ...
    module = importlib.util.module_from_spec(spec)
    sys.modules[name] = module
    spec.loader.exec_module(module)
    print(f"{name!r} has been imported")
else:
    print(f"can't find the {name!r} module")

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)
sys.modules[module_name] = module
spec.loader.exec_module(module)

>>> import importlib.util
>>> import sys
>>> def lazy_import(name):
...     spec = importlib.util.find_spec(name)
...     loader = importlib.util.LazyLoader(spec.loader)
...     spec.loader = loader
...     module = importlib.util.module_from_spec(spec)
...     sys.modules[name] = module
...     loader.exec_module(module)
...     return module
...
>>> lazy_typing = lazy_import("typing")
>>> #lazy_typing is a real module object,
>>> #but it is not loaded in memory yet.
>>> lazy_typing.TYPE_CHECKING
False

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

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)
    sys.modules[absolute_name] = module
    spec.loader.exec_module(module)
    if path is not None:
        setattr(parent_module, child_name, module)
    return module