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

Введение

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

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

Функции

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

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

Примечание

Для программирования импорта модулей следует использовать import_module(), а не эту функцию.

importlib.import_module(name, package=None)

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

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

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

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

importlib.find_loader(name, path=None)

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

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

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

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

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

importlib.invalidate_caches()

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

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

importlib.reload(module)

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

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

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

Есть ряд других замечаний:

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

try:
    cache
except NameError:
    cache = {}

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

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

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

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

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

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

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

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

Иерархия ABC:

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

class importlib.abc.Finder

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

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

abstractmethod find_module(fullname, path=None)

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

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

class importlib.abc.MetaPathFinder

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

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

find_spec(fullname, path, target=None)

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

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

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

find_loader(fullname)

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

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

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

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

find_module(fullname)

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

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

invalidate_caches()

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

class importlib.abc.Loader

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

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

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

create_module(spec)

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

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

Изменено в версии 3.5: Начиная с Python 3.6, этот метод больше не будет необязательным, если определен exec_module().

exec_module(module)

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

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

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

load_module(fullname)

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

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

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

• __name__

  Имя модуля.

• __file__

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

• __cached__

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

• __path__

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

• __package__

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

• __loader__

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

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

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

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

module_repr(module)

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

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

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

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

class importlib.abc.ResourceReader

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

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

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

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

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

abstractmethod open_resource(resource)

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

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

abstractmethod resource_path(resource)

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

Если ресурс конкретно не существует в файловой системе, следует поднять исключение FileNotFoundError.

abstractmethod is_resource(name)

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

abstractmethod contents()

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

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

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

class importlib.abc.ResourceLoader

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

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

abstractmethod get_data(path)

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

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

С последующим объектом кода можно выполнить его в модуле, выполнив exec(code, module.__dict__).

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

Изменено в версии 3.5: Метод стал статическим.

exec_module(module)

Реализация Loader.exec_module().

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

load_module(fullname)

Реализация Loader.load_module().

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

class importlib.abc.ExecutionLoader

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

abstractmethod get_filename(fullname)

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

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

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

class importlib.abc.FileLoader(fullname, path)

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

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

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

name

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

path

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

load_module(fullname)

Вызывает load_module() родителя.

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

abstractmethod get_filename(fullname)

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

abstractmethod get_data(path)

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

class importlib.abc.SourceLoader

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

• ResourceLoader.get_data()

• ExecutionLoader.get_filename()

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

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

path_stats(path)

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

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

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

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

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

path_mtime(path)

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

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

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

set_data(path, data)

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

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

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

get_code(fullname)

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

exec_module(module)

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

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

load_module(fullname)

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

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

get_source(fullname)

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

is_package(fullname)

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

importlib.resources – Ресурсы

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

Этот модуль использует систему импорта Python для доступа к ресурсам внутри пакетов. Если вы можете импортировать пакет, вы можете получить доступ к ресурсам внутри этого пакета. Ресурсы можно открыть или прочитать в двоичном или текстовом режиме.

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

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

Определены следующие типы.

importlib.resources.Package

Тип Package определен как Union[str, ModuleType]. Это означает, что там, где функция описывает прием Package, вы можете передать либо строку, либо модуль. Объекты модулей должны иметь разрешаемый __spec__.submodule_search_locations , который не является None.

importlib.resources.Resource

Этот тип описывает имена ресурсов, передаваемые различным функциям в этом пакете. Он определен как Union[str, os.PathLike].

Доступны следующие функции.

importlib.resources.open_binary(package, resource)

Открыть для двоичного чтения ресурс внутри пакета.

Пакет — это имя или объект модуля, который соответствует требованиям Package. Ресурс — это имя ресурса для открытия внутри пакета; он не может содержать разделители путей и не может содержать подресурсы (т. е. не может быть каталогом). Эта функция возвращает экземпляр typing.BinaryIO, двоичный поток ввода-вывода, открытый для чтения.

importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')

Открыть для текстового чтения ресурс внутри пакета. По умолчанию ресурс открывается для чтения в кодировке UTF-8.

Пакет — это имя или объект модуля, который соответствует требованиям Package. Ресурс — это имя ресурса для открытия внутри пакета; он не может содержать разделители путей и не может содержать подресурсы (т. е. не может быть каталогом). encoding и errors имеют такое же значение, как и в встроенной функции open().

Эта функция возвращает экземпляр typing.TextIO, текстовый поток ввода-вывода, открытый для чтения.

importlib.resources.read_binary(package, resource)

Прочитать и вернуть содержимое ресурса внутри пакета как bytes.

Пакет — это имя или объект модуля, который соответствует требованиям Package. Ресурс — это имя ресурса для открытия внутри пакета; он не может содержать разделители путей и не может содержать подресурсы (т. е. не может быть каталогом). Эта функция возвращает содержимое ресурса как bytes.

importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')

Прочитать и вернуть содержимое ресурса внутри пакета как str. По умолчанию содержимое читается в строгой кодировке UTF-8.

Пакет — это имя или объект модуля, который соответствует требованиям Package. Ресурс — это имя ресурса для открытия внутри пакета; он не может содержать разделители путей и не может содержать подресурсы (т. е. не может быть каталогом). encoding и errors имеют такое же значение, как и в встроенной функции open(). Эта функция возвращает содержимое ресурса как str.

importlib.resources.path(package, resource)

Возвращает путь к ресурсу как фактический путь в файловой системе. Эта функция возвращает менеджер контекста для использования в операторе with. Менеджер контекста предоставляет объект pathlib.Path.

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

Пакет — это имя или объект модуля, который соответствует требованиям Package. Ресурс — это имя ресурса для открытия внутри пакета; он не может содержать разделители путей и не может содержать подресурсы (т. е. не может быть каталогом).

importlib.resources.is_resource(package, name)

Возвращает True , если в пакете есть ресурс с именем name, иначе False. Помните, что каталоги — не ресурсы! Пакет — это имя или объект модуля, который соответствует требованиям Package.

importlib.resources.contents(package)

Возвращает итерируемый объект по именованным элементам в пакете. Итерируемый объект возвращает str ресурсы (например, файлы) и не-ресурсы (например, каталоги). Итерируемый объект не рекурсивно входит в подкаталоги.

Пакет — это имя или объект модуля, который соответствует требованиям Package.

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 find_module(fullname, path=None)

Обёртка старой версии над find_spec().

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

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.

find_loader(fullname)

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

invalidate_caches()

Очистить внутренний кэш.

classmethod path_hook(*loader_details)

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

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

class importlib.machinery.SourceFileLoader(fullname, path)

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

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

name

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

path

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

is_package(fullname)

Возвращает True, если path похоже на путь к пакету.

path_stats(path)

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

set_data(path, data)

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

load_module(name=None)

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

Устарело начиная с версии 3.6: Используйте importlib.abc.Loader.exec_module() вместо этого.

class importlib.machinery.SourcelessFileLoader(fullname, path)

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

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

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

name

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

path

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

is_package(fullname)

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

get_code(fullname)

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

get_source(fullname)

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

load_module(name=None)

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

Устарело начиная с версии 3.6: Используйте importlib.abc.Loader.exec_module() вместо этого.

class importlib.machinery.ExtensionFileLoader(fullname, path)

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

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

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

name

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

path

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

create_module(spec)

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

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

exec_module(module)

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

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

is_package(fullname)

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

get_code(fullname)

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

get_source(fullname)

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

get_filename(fullname)

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

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

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

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

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

name

(__name__)

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

loader

(__loader__)

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

origin

(__file__)

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

submodule_search_locations

(__path__)

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

loader_state

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

cached

(__cached__)

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

parent

(__package__)

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

has_location

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

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.

Исключение 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.

Изменено в версии 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.module_for_loader

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

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

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

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

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

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

@importlib.util.set_loader

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

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

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

@importlib.util.set_package

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

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

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

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

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

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

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

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

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

importlib.util.source_hash(source_bytes)

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

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

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

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