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

PyObject* PyImport_ImportModule(const char *name)

Значение возврата: Новая ссылка.

Это упрощенный интерфейс к PyImport_ImportModuleEx() ниже, оставляющий аргументы globals и locals равными NULL и level равным 0. Когда аргумент name содержит точку (когда он указывает на подмодуль пакета), аргумент fromlist устанавливается в список ['*'] таким образом, чтобы значение возврата было указанным модулем, а не верхним пакетом, который его содержит, как это было бы в противном случае. (К сожалению, это имеет дополнительный побочный эффект, когда name фактически указывает на подпакет вместо подмодуля: подмодули, указанные в переменной пакета __all__ загружаются.) Возвращает новую ссылку на импортированный модуль или NULL с установленным исключением при ошибке. Неудачный импорт модуля не оставляет модуль в sys.modules.

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

PyObject* PyImport_ImportModuleNoBlock(const char *name): Значение возврата: Новая ссылка.
Эта функция является устаревшей алиасом функции PyImport_ImportModule().

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

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)

Значение возврата: Новая ссылка.

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

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

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

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

PyObject* PyImport_Import(PyObject *name)

Значение возврата: Новая ссылка.

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

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

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

PyObject* PyImport_AddModuleObject(PyObject *name): Значение возврата: Заимствованная ссылка.
Возвращает объект модуля, соответствующий имени модуля. Аргумент name может иметь вид package.module. Сначала проверяется словарь модулей, если он есть, а если нет, создаётся новый и вставляется в словарь модулей. Возвращает NULL с установленным исключением при ошибке.

Примечание

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

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

PyObject* PyImport_AddModule(const char *name): Значение возврата: Заимствованная ссылка.
Аналогично PyImport_AddModuleObject(), но имя является строкой UTF-8, а не объектом Unicode.

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

Значение возврата: Новая ссылка.

Учитывая имя модуля (возможно, вида 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().

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

Значение возврата: Новая ссылка.

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

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

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

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

PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname): Возвращаемое значение: Новая ссылка.
Аналогично PyImport_ExecCodeModuleObject(), но name, pathname и cpathname — строки в кодировке UTF-8. Также предпринимаются попытки определить значение для pathname из cpathname, если для первого задано NULL.

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

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

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

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

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

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

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

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

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

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

void _PyImport_Init(): Инициализирует механизм импорта. Только для внутреннего использования.

void PyImport_Cleanup(): Очищает таблицу модулей. Только для внутреннего использования.

void _PyImport_Fini(): Завершает механизм импорта. Только для внутреннего использования.

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

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

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

int PyImport_ImportFrozenModule(const char *name): Аналогично 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;
};

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

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

struct _inittab

Структура, описывающая одну запись в списке встроенных модулей. Каждая из этих структур содержит имя и функцию инициализации для встроенного в интерпретатор модуля. Имя — строка в кодировке ASCII. Программы, встраивающие Python, могут использовать массив этих структур в сочетании с PyImport_ExtendInittab() для предоставления дополнительных встроенных модулей. Структура определяется в Include/import.h как:

struct _inittab {
    const char *name;           /* ASCII encoded string */
    PyObject* (*initfunc)(void);
};

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