Импортирование модулей

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

PyObject *PyImport_ImportModuleNoBlock(const char *name): Значение возврата: Новая ссылка. Часть Стабильного API.
Эта функция — устаревшее псевдоним 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)

Значение возврата: Новая ссылка. Часть Стабильного API начиная с версии 3.7.

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

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

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level): Значение возврата: Новая ссылка. Часть Стабильного API.
Аналогично PyImport_ImportModuleLevelObject(), но имя — строка UTF-8, а не объект Unicode.

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

PyObject *PyImport_Import(PyObject *name)

Значение возврата: Новая ссылка. Часть Стабильного API.

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

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

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

PyObject *PyImport_AddModuleRef(const char *name)

Значение возврата: Новая ссылка. Часть Стабильного API начиная с версии 3.13.

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

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

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

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

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

Значение возврата: Новый ссылка. Часть Стабильной ABI.

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

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

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

Добавлена в версии 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 из cpathname, если первый установлен в NULL.

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

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

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

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

Изменено в версии 3.3: Возвращает -1 при ошибке.

const char *PyImport_GetMagicTag(): Часть Стабильной ABI.
Возвращает строку магического тега для PEP 3147 формат имён файлов байткода Python. Имейте в виду, что значение в 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.
Возвращает объект поиска для элемента sys.path/pkg.__path__ с именем 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 должен заканчиваться стоп-записью, содержащей NULL для поля name; отсутствие стоп-записи может привести к ошибке доступа к памяти. Возвращает 0 при успехе или -1 если не удалось выделить достаточной памяти для расширения внутренней таблицы. В случае неудачи модули в таблицу не добавляются. Эта функция должна быть вызвана до Py_Initialize().

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