Импорт модулей¶Importing Modules

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(), но name представляет собой строку в кодировке 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(), но name представляет собой строку в кодировке 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 и .pyo). Магическое число должно находиться в первых четырёх байтах файла байт-кода в порядке 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_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()¶: Завершает работу механизма импорта. Только для внутреннего использования.

PyObject* _PyImport_FindExtension(char *, char *)¶: Только для внутреннего использования.

PyObject* _PyImport_FixupExtension(char *, char *)¶: Только для внутреннего использования.

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 {
    char *name;
    unsigned char *code;
    int size;
};

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 {
    char *name;                 /* Строка в кодировке ASCII */
    PyObject* (*initfunc)(void);
};

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