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)

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

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

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

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

• module.__name__
• module.__file__
• module.__cached__
• module.__path__
• module.__package__
• module.__loader__ (устарел)

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

Изменено в версии 3.4: При вызове возбуждает исключение ImportError вместо NotImplementedError. Если доступен exec_module(), обеспечивается соответствующая функциональность.

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

class importlib.abc.ResourceLoader

Заменён классом TraversableResources

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

Устарел с версии 3.7: Этот ABC устарел; вместо него следует поддерживать загрузку ресурсов с помощью importlib.resources.abc.TraversableResources.

abstractmethod get_data(path)

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

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

class importlib.abc.InspectLoader

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

get_code(fullname)

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

Примечание

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

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

abstractmethod get_source(fullname)

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

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

is_package(fullname)

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

Изменено в версии 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, будет удалён в версии 3.15: вместо него используйте 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, будет удалён в версии 3.15: Вместо него используйте 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, будет удалён в версии 3.15: Вместо него используйте 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 считается ресурсом. Если name не существует, вызывается исключение FileNotFoundError.

abstractmethod contents()

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

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

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

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

При необходимости поисковик кэширует содержимое каталога, вызывая 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, будет удалено в версии 3.15: Вместо этого используйте 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, будет удалено в версии 3.15: Вместо этого используйте 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, если путь к файлу указывает на модуль __init__ пакета, что определяется по 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

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

loader

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

origin

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

submodule_search_locations

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

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

loader_state

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

cached

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

parent

(Только для чтения) Полное имя пакета, в котором находится модуль (или пустая строка для модуля верхнего уровня). См. module.__package__. Если модуль является пакетом, это значение совпадает с name.

has_location

True, если origin спецификации указывает на доступное для загрузки местоположение, и 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: Если package на самом деле не является пакетом (то есть у него нет атрибута __path__), вызывается исключение ModuleNotFoundError вместо AttributeError.

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__, и не использовать слоты. Наконец, этот класс не работает с модулями, подменяющими объект, помещённый в 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


def import_from_path(module_name, file_path):
    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)
    return module


# For illustrative purposes only (use of `json` is arbitrary).
import json
file_path = json.__file__
module_name = json.__name__

# Similar outcome as `import json`.
json = import_from_path(module_name, file_path)

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