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

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, даже если 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, если оно не равно 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 по cpathname, если первое задано как NULL.

Добавлено в версии 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.

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, а не объектов Python str.

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