imp — Доступ к внутренностям импорта

Этот модуль предоставляет интерфейс к механизмам, используемым для реализации оператора import. Он определяет следующие константы и функции:

imp.get_magic()

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

imp.get_suffixes()

Возвращает список кортежей из 3 элементов, каждый описывает определенный тип модуля. Каждый кортеж имеет вид (suffix, mode, type), где suffix — строка, добавляемая к имени модуля для получения имени файла для поиска, mode — строка режима, передаваемая встроенной функции open() для открытия файла (может быть 'r' для текстовых файлов или 'rb' для двоичных файлов), и type — тип файла, имеющий одно из значений PY_SOURCE, PY_COMPILED или C_EXTENSION, описанных ниже.

imp.find_module(name[, path])

Попытается найти модуль name. Если path опущено или None, то просматривается список имен каталогов, указанных в sys.path, но сначала проверяются несколько специальных мест: функция пытается найти встроенный модуль с заданным именем (C_BUILTIN), затем замороженный модуль (PY_FROZEN), а на некоторых системах также проверяются другие места (в Windows — реестр, который может указывать на определенный файл).

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

Если поиск успешен, возвращаемое значение — кортеж из 3 элементов (file, pathname, description):

file — открытый файл, размещённый в начале, pathname — полное имя найденного файла, а description — кортеж из 3 элементов, как в списке, возвращаемом get_suffixes(), описывающий тип найденного модуля.

Если модуль не находится в файле, возвращаемое значение file — None, pathname — пустая строка, а кортеж description содержит пустые строки для своего суффикса и режима; тип модуля указывается, как указано выше в скобках. Если поиск неудачен, поднимается исключение ImportError. Другие исключения указывают на проблемы с аргументами или средой.

Если модуль — пакет, file — None, pathname — путь к пакету, а последний элемент в кортеже description — PKG_DIRECTORY.

Эта функция не обрабатывает иерархические имена модулей (имена, содержащие точки). Для поиска P.M, то есть подмодуля M пакета P, используйте find_module() и load_module() для поиска и загрузки пакета P, а затем используйте find_module() с аргументом path, установленным на P.__path__. Если у самого P есть имён, содержащих точки, примените этот рецепт рекурсивно.

imp.load_module(name, file, pathname, description)

Загружает модуль, который ранее был найден функцией find_module() (или иным образом, дающим совместимые результаты). Эта функция делает больше, чем просто импорт модуля: если модуль уже импортирован, она эквивалентна reload()! Аргумент name указывает полное имя модуля (включая имя пакета, если это подмодуль пакета). Аргумент file — открытый файл, а pathname — соответствующее имя файла; эти могут быть None и '', соответственно, когда модуль является пакетом или не загружается из файла. Аргумент description — кортеж, аналогичный возвращаемому get_suffixes(), описывающий тип модуля, который должен быть загружен.

Если загрузка успешна, возвращаемое значение — объект модуля; в противном случае возникает исключение (обычно ImportError).

Важно: вызывающая сторона отвечает за закрытие аргумента file, если он не был None, даже при возникновении исключения. Лучше всего это сделать с помощью оператора try … finally.

imp.new_module(name)

Возвращает новый пустой объект модуля с именем name. Этот объект не вставляется в sys.modules.

imp.lock_held()

Возвращает True если блокировка импорта сейчас захвачена, иначе False. На платформах без потоков всегда возвращает False.

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

imp.acquire_lock()

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

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

На платформах без потоков эта функция ничего не делает.

Новая в версии 2.3.

imp.release_lock()

Освободить блокировку импорта интерпретатора. На платформах без потоков эта функция ничего не делает.

Новая в версии 2.3.

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

imp.PY_SOURCE

Модуль был найден как исходный файл.

imp.PY_COMPILED

Модуль был найден как файл с объектом скомпилированного кода.

imp.C_EXTENSION

Модуль был найден как динамически загружаемая общая библиотека.

imp.PKG_DIRECTORY

Модуль был найден как каталог пакета.

imp.C_BUILTIN

Модуль был найден как встроенный модуль.

imp.PY_FROZEN

Модуль был найден как замороженный модуль (см. init_frozen()).

Следующие константы и функции устарели; их функциональность доступна через find_module() или load_module(). Они сохранены для обратной совместимости:

imp.SEARCH_ERROR

Не используется.

imp.init_builtin(name)

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

imp.init_frozen(name)

Инициализирует замороженный модуль с именем name и возвращает его объект модуля. Если модуль уже был инициализирован, он будет инициализирован снова. Если замороженного модуля с именем name нет, возвращается None. (Замороженные модули — это модули, написанные на Python, чьи скомпилированные объекты байткода включены в пользовательскую интерпретатор Python утилитой Python freeze. См. Tools/freeze/ на данный момент.)

imp.is_builtin(name)

Возвращает 1 если есть встроенный модуль с именем name, который можно повторно инициализировать. Возвращает -1 если есть встроенный модуль с именем name, который нельзя повторно инициализировать (см. init_builtin()). Возвращает 0 если встроенного модуля с именем name нет.

imp.is_frozen(name)

Возвращает True если существует замороженный модуль (см. init_frozen()) с именем name, или False если такого модуля нет.

imp.load_compiled(name, pathname[, file])

Загружает и инициализирует модуль, реализованный как файл байткодированного кода, и возвращает объект модуля. Если модуль был уже инициализирован, он будет инициализирован снова. Аргумент name используется для создания или доступа к объекту модуля. Аргумент pathname указывает на файл байткодированного кода. Аргумент file — это файл байткодированного кода, открытый для чтения в двоичном режиме с начала. В настоящее время он должен быть реальным объектом файла, а не пользовательским классом, эмулирующим файл.

imp.load_dynamic(name, pathname[, file])

Загружает и инициализирует модуль, реализованный как динамически загружаемая общая библиотека, и возвращает его объект модуля. Если модуль был уже инициализирован, он будет инициализирован снова. Повторная инициализация включает копирование атрибута __dict__ кэшированного экземпляра модуля в значение, используемое в кэшированном модуле в sys.modules. Аргумент pathname должен указывать на общую библиотеку. Аргумент name используется для построения имени функции инициализации: вызывается внешняя C-функция, называемая initname() в общей библиотеке. Необязательный аргумент file игнорируется. (Примечание: использование общих библиотек сильно зависит от системы, и не все системы его поддерживают.)

Подробность реализации CPython: Внутренности импорта идентифицируют модули расширения по имени файла, поэтому выполнение foo = load_dynamic("foo", "mod.so") и bar = load_dynamic("bar", "mod.so") приведет к тому, что как foo, так и bar будут ссылаться на один и тот же модуль, независимо от того, экспортирует ли mod.so функцию initbar или нет. В системах, которые их поддерживают, для импорта нескольких модулей из одной общей библиотеки могут использоваться ссылки, так как каждая ссылка на модуль будет использовать другое имя файла.

imp.load_source(name, pathname[, file])

Загружает и инициализирует модуль, реализованный как файл исходного кода Python, и возвращает его объект модуля. Если модуль был уже инициализирован, он будет инициализирован снова. Аргумент name используется для создания или доступа к объекту модуля. Аргумент pathname указывает на исходный файл. Аргумент file — это исходный файл, открытый для чтения в текстовом формате с начала. В настоящее время он должен быть реальным объектом файла, а не пользовательским классом, эмулирующим файл. Обратите внимание, что если существует соответствующий байткодированный файл (с расширением .pyc или .pyo ), он будет использоваться вместо парсинга заданного исходного файла.

class imp.NullImporter(path_string)

Тип NullImporter — это обработчик импорта PEP 302, который обрабатывает строки путей, не являющиеся каталогами, отказываясь находить какие-либо модули. Вызов этого типа с существующим каталогом или пустой строкой вызывает ImportError. В противном случае возвращается экземпляр NullImporter.

Python добавляет экземпляры этого типа в sys.path_importer_cache для любых записей путей, которые не являются каталогами и не обрабатываются другими обработчиками путей в sys.path_hooks. Экземпляры имеют только один метод:

find_module(fullname[, path])

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

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

1. Примеры

Следующая функция эмулирует стандартную инструкцию import до Python 1.4 (без иерархических имён модулей). (Эта реализация не работала бы в этой версии, поскольку find_module() был расширен, а load_module() был добавлен в 1.4.)

import imp
import sys

def __import__(name, globals=None, locals=None, fromlist=None):
    # Fast path: see if the module has already been imported.
    try:
        return sys.modules[name]
    except KeyError:
        pass

    # If any of the following calls raises an exception,
    # there's a problem we can't handle -- let the caller handle it.

    fp, pathname, description = imp.find_module(name)

    try:
        return imp.load_module(name, fp, pathname, description)
    finally:
        # Since we may exit via an exception, close fp explicitly.
        if fp:
            fp.close()

Более полный пример, реализующий иерархические имена модулей и включающий функцию reload(), можно найти в модуле knee. Модуль knee можно найти в Demo/imputil/ в дистрибутиве исходного кода Python.