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

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 схема блокировок была заменена блокировками на уровне отдельных модулей для большинства задач, поэтому особое поведение этой функции больше не требуется.

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_AddModuleObject(PyObject *name): Возвращаемое значение: заимствованная ссылка. Часть стабильного ABI начиная с версии 3.7.
Возвращает объект модуля, соответствующий имени модуля. Аргумент name может иметь вид package.module. Сначала выполняется поиск в словаре модулей; если объект там отсутствует, создаётся новый и добавляется в словарь модулей. В случае ошибки возвращает NULL и устанавливает исключение.

Примечание

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

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

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

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().

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.

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(), если указан только путь к байт-коду.

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.