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

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

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

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

31.5.2. Функции¶Functions

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

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

importlib.import_module(name, package=None)¶

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

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

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

importlib.find_loader(name, path=None)¶

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

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

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

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

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

importlib.invalidate_caches()¶

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

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

importlib.reload(module)¶

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

При выполнении reload():

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

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

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

try:
    cache
except NameError:
    cache = {}

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

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

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

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

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

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

Иерархия ABC:

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

class importlib.abc.Finder¶

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

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

find_module(fullname, path=None)¶

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

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

class importlib.abc.MetaPathFinder¶

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

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

find_spec(fullname, path, target=None)¶

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

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

find_module(fullname, path)¶

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

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

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

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

invalidate_caches()¶

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

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

class importlib.abc.PathEntryFinder¶

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

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

find_spec(fullname, target=None)¶

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

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

find_loader(fullname)¶

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

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

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

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

find_module(fullname)¶

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

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

invalidate_caches()¶

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

class importlib.abc.Loader¶

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

create_module(spec)¶

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

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

exec_module(module)¶

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

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

load_module(fullname)¶

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

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

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

• __name__

  Имя модуля.

• __file__

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

• __cached__

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

• __path__

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

• __package__

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

• __loader__

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

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

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

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

module_repr(module)¶

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

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

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

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

class importlib.abc.ResourceLoader¶

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

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: Больше не является абстрактным, предоставлена конкретная реализация.

get_source(fullname)¶

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

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

is_package(fullname)¶

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

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

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

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

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

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

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.

get_filename(fullname)¶

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

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

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

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

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

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

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

name¶

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

path¶

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

load_module(fullname)¶

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

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

get_filename(fullname)¶

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

get_data(path)¶

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

class importlib.abc.SourceLoader¶

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

• ResourceLoader.get_data()

• ExecutionLoader.get_filename()

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

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

path_stats(path)¶

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

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

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

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

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

path_mtime(path)¶

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

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

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

set_data(path, data)¶

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

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

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

get_code(fullname)¶

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

exec_module(module)¶

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

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

load_module(fullname)¶

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

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

get_source(fullname)¶

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

is_package(fullname)¶

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

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

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

importlib.machinery.SOURCE_SUFFIXES¶

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

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

importlib.machinery.DEBUG_BYTECODE_SUFFIXES¶

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

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

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES¶

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

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

importlib.machinery.BYTECODE_SUFFIXES¶

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

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

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.

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

Примечание

Из-за ограничений C-API модулей расширения, в настоящее время BuiltinImporter не реализует Loader.exec_module().

class importlib.machinery.FrozenImporter¶

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

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

class importlib.machinery.WindowsRegistryFinder¶

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

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

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

class importlib.machinery.PathFinder¶

Finder для 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.

classmethod find_module(fullname, path=None)¶

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

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

classmethod invalidate_caches()¶

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

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

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

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

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

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

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

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

path¶

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

find_spec(fullname, target=None)¶

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

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

find_loader(fullname)¶

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

invalidate_caches()¶

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

classmethod path_hook(*loader_details)¶

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

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

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

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

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

name¶

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

path¶

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

is_package(fullname)¶

Возвращает true, если path указывает на пакет.

path_stats(path)¶

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

set_data(path, data)¶

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

load_module(name=None)¶

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

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

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

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

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

name¶

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

path¶

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

is_package(fullname)¶

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

get_code(fullname)¶

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

get_source(fullname)¶

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

load_module(name=None)¶

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

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

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

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

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

name¶

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

path¶

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

load_module(name=None)¶

Загружает модуль расширения только в том случае, если fullname совпадает с name или является None.

Примечание

Из-за ограничений C-API модулей расширения на данный момент ExtensionFileLoader не реализует Loader.exec_module().

is_package(fullname)¶

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

get_code(fullname)¶

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

get_source(fullname)¶

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

get_filename(fullname)¶

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

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

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

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

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

name¶

(__name__)

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

loader¶

(__loader__)

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

origin¶

(__file__)

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

submodule_search_locations¶

(__path__)

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

loader_state¶

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

cached¶

(__cached__)

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

parent¶

(__package__)

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

has_location¶

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

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

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

importlib.util.MAGIC_NUMBER¶

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

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

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

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

path не обязан существовать.

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

importlib.util.source_from_cache(path)¶

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

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

importlib.util.decode_source(source_bytes)¶

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

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

importlib.util.resolve_name(name, package)¶

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

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

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

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

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

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

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

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

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

@importlib.util.module_for_loader¶

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

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

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

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

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

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

@importlib.util.set_loader¶

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

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

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

@importlib.util.set_package¶

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

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

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

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

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

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

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

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