Импорт модулей

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

PyObject *PyImport_ImportModuleNoBlock(const char *name): Возвращаемое значение: новая ссылка. Часть стабильного ABI.
Эта функция является устаревшим псевдонимом PyImport_ImportModule().

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

Устарела с версии 3.13, будет удалена в версии 3.15: Вместо неё используйте PyImport_ImportModule().

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)

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

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

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

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

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

PyObject *PyImport_Import(PyObject *name)

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

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

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

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

PyObject *PyImport_AddModuleRef(const char *name)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Атрибут __file__ модуля будет установлен в значение co_filename объекта кода. Если применимо, будет также установлен __cached__.

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

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

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

Изменено в версии 3.12: Установка __cached__ и __loader__ устарела. Альтернативы см. в ModuleSpec.

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

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

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

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

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

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

Изменено в версии 3.12: Установка __cached__ устарела. Альтернативы см. в ModuleSpec.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

int PyImport_ImportFrozenModule(const char *name): Часть стабильного 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)): Часть стабильного ABI.
Добавляет один модуль в существующую таблицу встроенных модулей. Это вспомогательная обёртка над PyImport_ExtendInittab(), возвращающая -1, если расширить таблицу не удалось. Новый модуль можно импортировать под именем name; при первой попытке импорта в качестве функции инициализации вызывается initfunc. Эту функцию следует вызвать до Py_Initialize().

struct _inittab

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

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

PyObject *(*initfunc)(void): Функция инициализации модуля, встроенного в интерпретатор.

int PyImport_ExtendInittab(struct _inittab *newtab)

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

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