Импорт модулей¶Importing Modules

PyObject *PyImport_ImportModule(const char *name)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Это обёртка вокруг PyImport_Import(), которая принимает const char* в качестве аргумента вместо PyObject*.

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)¶

Возвращаемое значение: новая ссылка.

Импорт модуля. Лучше всего это описывается через встроенную функцию Python __import__().

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

Неудачные импорты удаляют неполные объекты модулей, как и PyImport_ImportModule().

PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI начиная с версии 3.7.

Импорт модуля. Наилучшее описание даётся через встроенную функцию Python __import__(), поскольку стандартная функция __import__() вызывает эту функцию напрямую.

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

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Аналогично PyImport_ImportModuleLevelObject(), но имя представляет собой строку в кодировке UTF-8 вместо объекта Unicode.

Изменено в версии 3.3: Отрицательные значения для level больше не принимаются.

PyObject *PyImport_Import(PyObject *name)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI.

Это интерфейс более высокого уровня, который вызывает текущую «функцию перехвата импорта» (с явным level равным 0, что означает абсолютный импорт). Он вызывает функцию __import__() из __builtins__ текущих глобальных переменных. Это означает, что импорт выполняется с использованием тех перехватчиков импорта, которые установлены в текущем окружении.

Эта функция всегда использует абсолютные импорты.

PyObject *PyImport_ReloadModule(PyObject *m)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Перезагружает модуль. Возвращает новую ссылку на перезагруженный модуль или NULL с установленным исключением в случае ошибки (в этом случае модуль всё ещё существует).

PyObject *PyImport_AddModuleRef(const char *name)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI начиная с версии 3.13.

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

Аргумент name может быть в форме package.module. Сначала проверяется словарь модулей на наличие такого модуля, и если его нет, создаётся новый и вставляется в словарь модулей.

Возвращает сильную ссылку на модуль в случае успеха. Возвращает NULL с установленным исключением в случае ошибки.

Имя модуля name декодируется из UTF-8.

Эта функция не загружает и не импортирует модуль; если модуль ещё не был загружен, будет получен пустой объект модуля. Используйте PyImport_ImportModule() или один из его вариантов для импорта модуля. Структуры пакетов, подразумеваемые именем с точками для name, не создаются, если они ещё не существуют.

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

PyObject *PyImport_AddModuleObject(PyObject *name)¶: Возвращаемое значение: заимствованная ссылка. Часть Stable ABI начиная с версии 3.7.
Аналог PyImport_AddModuleRef(), но возвращает заимствованную ссылку, а name является объектом Python str.

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

PyObject *PyImport_AddModule(const char *name)¶: Возвращаемое значение: заимствованная ссылка. Часть Stable ABI.
Подобно PyImport_AddModuleRef(), но возвращает заимствованную ссылку.

PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI.

Принимая имя модуля (возможно, вида package.module) и объект кода, прочитанный из файла байткода Python или полученный из встроенной функции compile(), загружает модуль. Возвращает новую ссылку на объект модуля или NULL с установленным исключением, если произошла ошибка. В случае ошибки name удаляется из sys.modules, даже если name уже был в sys.modules на момент входа в PyImport_ExecCodeModule(). Оставлять не полностью инициализированные модули в sys.modules опасно, так как импорт таких модулей не может узнать, что объект модуля находится в неизвестном (и, вероятно, повреждённом с точки зрения намерений автора модуля) состоянии.

__spec__ и __loader__ модуля будут установлены, если ещё не установлены, с соответствующими значениями. Загрузчик спецификации будет установлен на __loader__ модуля (если установлен) или на экземпляр SourceFileLoader в противном случае.

Атрибут __file__ модуля будет установлен в co_filename объекта кода.

Эта функция перезагрузит модуль, если он уже был импортирован. См. PyImport_ReloadModule() для описания правильного способа перезагрузки модуля.

Если name указывает на имя с точками вида package.module, любые структуры пакета, которые ещё не были созданы, по-прежнему не будут созданы.

См. также PyImport_ExecCodeModuleEx() и PyImport_ExecCodeModuleWithPathnames().

Изменено в версии 3.12: Установка __cached__ и __loader__ является устаревшей. См. ModuleSpec для альтернатив.

Изменено в версии 3.15: __cached__ больше не устанавливается.

PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI.

Как PyImport_ExecCodeModule(), но атрибут __file__ объекта модуля устанавливается в pathname, если он не равен NULL.

См. также PyImport_ExecCodeModuleWithPathnames().

PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI начиная с версии 3.7.
Как PyImport_ExecCodeModuleEx(), но путь к любому скомпилированному файлу через cpathname используется соответствующим образом, когда не равен NULL. Из трёх функций эта является предпочтительной.

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

Изменено в версии 3.12: Установка __cached__ является устаревшей. См. ModuleSpec для альтернатив.

Изменено в версии 3.15: __cached__ больше не устанавливается.

PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Как PyImport_ExecCodeModuleObject(), но name, pathname и cpathname являются строками в кодировке UTF-8. Также предпринимаются попытки выяснить, каким должно быть значение pathname из cpathname, если первое установлено в NULL.

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

Изменено в версии 3.3: Использует imp.source_from_cache() при вычислении пути к исходному коду, если указан только путь к байткоду.

Изменено в версии 3.12: Больше не использует удалённый модуль imp.

long PyImport_GetMagicNumber()¶: Часть Stable ABI.
Возвращает магическое число для файлов байткода Python (также известных как файлы .pyc). Магическое число должно присутствовать в первых четырёх байтах файла байткода в порядке little-endian. В случае ошибки возвращает -1.

Изменено в версии 3.3: Возвращает -1 в случае неудачи.

const char *PyImport_GetMagicTag()¶: Часть Stable ABI.
Возвращает строку магического тега для имён файлов байткода Python в формате PEP 3147. Имейте в виду, что значение в sys.implementation.cache_tag является авторитетным и должно использоваться вместо этой функции.

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

PyObject *PyImport_GetModuleDict()¶: Возвращаемое значение: заимствованная ссылка. Часть Stable ABI.
Возвращает словарь, используемый для администрирования модулей (также известный как sys.modules). Обратите внимание, что это переменная, отдельная для каждого интерпретатора.

PyObject *PyImport_GetModule(PyObject *name)¶: Возвращаемое значение: новая ссылка. Часть стабильного ABI начиная с версии 3.8.
Возвращает уже импортированный модуль с заданным именем. Если модуль ещё не был импортирован, возвращает NULL, но не устанавливает ошибку. Возвращает NULL и устанавливает ошибку, если поиск не удался.

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

PyObject *PyImport_GetImporter(PyObject *path)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает объект поиска для элемента sys.path/pkg.__path__ path, возможно, извлекая его из словаря sys.path_importer_cache. Если он ещё не кэширован, обходит sys.path_hooks, пока не будет найден хук, способный обработать элемент пути. Возвращает None, если ни один хук не подошёл; это сообщает вызывающей стороне, что поисковик на основе пути не смог найти поисковик для этого элемента пути. Кэширует результат в sys.path_importer_cache. Возвращает новую ссылку на объект поисковика.

int PyImport_ImportFrozenModuleObject(PyObject *name)¶: Часть Stable ABI начиная с версии 3.7.
Загружает замороженный модуль с именем name. Возвращает 1 при успехе, 0, если модуль не найден, и -1 с установленным исключением, если инициализация не удалась. Чтобы получить доступ к импортированному модулю после успешной загрузки, используйте PyImport_ImportModule(). (Обратите внимание на неточность названия – эта функция перезагрузила бы модуль, если он уже был импортирован.)

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

Изменено в версии 3.4: Атрибут __file__ больше не устанавливается в модуле.

int PyImport_ImportFrozenModule(const char *name)¶: Часть Stable ABI.
Аналогично PyImport_ImportFrozenModuleObject(), но имя представляет собой строку в кодировке UTF-8 вместо объекта Unicode.

struct _frozen¶

Это определение типа структуры для дескрипторов замороженных модулей, как сгенерировано утилитой freeze (см. Tools/freeze/ в дистрибутиве исходного кода Python). Её определение находится в Include/import.h:

struct _frozen {
    const char *name;
    const unsigned char *code;
    int size;
    bool is_package;
};

Изменено в версии 3.11: Новое поле is_package указывает, является ли модуль пакетом или нет. Это заменяет установку поля size в отрицательное значение.

const struct _frozen *PyImport_FrozenModules¶: Этот указатель инициализируется так, чтобы указывать на массив записей _frozen, завершающийся записью, все члены которой равны NULL или нулю. Когда замороженный модуль импортируется, он ищется в этой таблице. Сторонний код может этим воспользоваться, чтобы предоставить динамически создаваемую коллекцию замороженных модулей.

int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))¶: Часть Stable ABI.
Добавляет один модуль в существующую таблицу встроенных модулей. Это удобная обёртка вокруг PyImport_ExtendInittab(), возвращающая -1, если таблицу не удалось расширить. Новый модуль можно импортировать по имени name, и он использует функцию initfunc в качестве функции инициализации, вызываемой при первой попытке импорта. Это должно вызываться до Py_Initialize().

struct _inittab¶

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

const char *name¶: Имя модуля в виде строки в кодировке ASCII.

PyObject *(*initfunc)(void)¶

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

Обратите внимание, что inittab использует «PyInit» функции инициализации; в настоящее время нет способа включить «PyModExport_» экспортные хуки.

int PyImport_ExtendInittab(struct _inittab *newtab)¶

Добавляет набор модулей в таблицу встроенных модулей. Массив newtab должен заканчиваться сторожевой записью, которая содержит NULL для поля name; отсутствие сторожевого значения может привести к ошибке памяти. Возвращает 0 при успехе или -1, если недостаточно памяти для расширения внутренней таблицы. В случае неудачи ни один модуль не добавляется во внутреннюю таблицу. Это должно вызываться до Py_Initialize().

Если Python инициализируется несколько раз, PyImport_AppendInittab() или PyImport_ExtendInittab() должны вызываться перед каждой инициализацией Python.

struct _inittab *PyImport_Inittab¶: Таблица встроенных модулей, используемая при инициализации Python. Не используйте это напрямую; вместо этого используйте PyImport_AppendInittab() и PyImport_ExtendInittab().

PyObject *PyImport_ImportModuleAttr(PyObject *mod_name, PyObject *attr_name)¶

Возвращаемое значение: новая ссылка.

Импортирует модуль mod_name и получает его атрибут attr_name.

Имена должны быть объектами Python str.

Вспомогательная функция, объединяющая PyImport_Import() и PyObject_GetAttr(). Например, она может возбуждать ImportError, если модуль не найден, и AttributeError, если атрибут не существует.

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

PyObject *PyImport_ImportModuleAttrString(const char *mod_name, const char *attr_name)¶: Возвращаемое значение: новая ссылка.
Аналогично PyImport_ImportModuleAttr(), но имена передаются в виде строк в кодировке UTF-8 вместо объектов str.

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

PyImport_LazyImportsMode PyImport_GetLazyImportsMode()¶: Возвращает текущий режим отложенного импорта.

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

PyObject *PyImport_GetLazyImportsFilter()¶: Возвращает сильную ссылку на текущий фильтр отложенного импорта. Если фильтр не задан, возвращает NULL. Эта функция всегда завершается успешно.

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

int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)¶

Аналогично PyImport_ImportModuleAttr(), но имена передаются в виде строк в кодировке UTF-8 вместо объектов str.

Эта функция всегда возвращает 0.

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

int PyImport_SetLazyImportsFilter(PyObject *filter)¶

Устанавливает текущий фильтр отложенного импорта. Параметр filter должен быть вызываемым объектом, который получит (importing_module_name, imported_module_name, [fromlist]), когда импорт может быть отложенным. Значение imported_module_name – это разрешённое имя модуля, поэтому lazy from .spam import eggs передаёт package.spam. Вызываемый объект должен вернуть True, если импорт должен быть отложенным, и False в противном случае.

Возвращает 0 при успешном выполнении и -1 с установленным исключением в противном случае.

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

type PyImport_LazyImportsMode¶

Перечисление возможных режимов отложенного импорта.

enumerator PyImport_LAZY_NORMAL¶: Уважает ключевое слово lazy в исходном коде. Это режим по умолчанию.

enumerator PyImport_LAZY_ALL¶: Делает все импорты отложенными по умолчанию.

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

PyObject *PyImport_CreateModuleFromInitfunc(PyObject *spec, PyObject *(*initfunc)(void))¶

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

Параметр spec должен быть объектом ModuleSpec.

Параметр initfunc должен быть функцией инициализации, такой же, как для PyImport_AppendInittab().

При успехе создаёт и возвращает объект модуля. Этот модуль не будет инициализирован; для инициализации вызовите PyModule_Exec(). (Пользовательские импортёры должны делать это в своём методе exec_module().)

При ошибке возвращает NULL с установленным исключением.

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