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

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

Изменено в версии 2.4: Неудачные импорты удаляют незавершённые объекты модуля.

Изменено в версии 2.6: Всегда использует абсолютные импорты.

PyObject* PyImport_ImportModuleNoBlock(const char *name)¶: Эта версия PyImport_ImportModule() не блокируется. Она предназначена dля использования в C-функциях, которые импортируют другие модули для выполнения функции. Импорт может блокироваться, если другой поток удерживает блокировку импорта. Функция PyImport_ImportModuleNoBlock() никогда не блокируется. Сначала она пытается получить модуль из sys.modules, а при неудаче вызывает PyImport_ImportModule(), если только блокировка не удерживается; в этом случае функция возбуждает ImportError.

Новое в версии 2.6.

PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)¶

Возвращаемое значение: новая ссылка.

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

Возвращаемое значение – новая ссылка на импортированный модуль или пакет верхнего уровня, либо NULL с установленным исключением в случае ошибки (до Python 2.4 модуль мог быть создан и в этом случае). Как и для __import__(), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой fromlist.

Изменено в версии 2.4: Неудачные импорты удаляют незавершённые объекты модуля.

Изменено в версии 2.6: Функция является псевдонимом для PyImport_ImportModuleLevel() с -1 в качестве level, что означает относительный импорт.

PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)¶

Возвращаемое значение: новая ссылка.

Возвращаемое значение – это новая ссылка на импортированный модуль или пакет верхнего уровня, или NULL с установленным исключением в случае неудачи. Как и для __import__(), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был указан непустой fromlist.

Новое в версии 2.5.

PyObject* PyImport_Import(PyObject *name)¶: Возвращаемое значение: новая ссылка.
Это интерфейс более высокого уровня, который вызывает текущую «функцию перехвата импорта». Он вызывает функцию __import__() из __builtins__ текущих глобальных переменных. Это означает, что импорт выполняется с использованием любых перехватчиков импорта, установленных в текущем окружении, например, с помощью rexec или ihooks.

Изменено в версии 2.6: Всегда использует абсолютные импорты.

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

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

Примечание

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

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

Возвращаемое значение: новая ссылка.

Принимая имя модуля (возможно, вида package.module) и объект кода, прочитанный из файла байт-кода Python или полученный от встроенной функции compile(), загружает модуль. Возвращает новую ссылку на объект модуля или NULL с установленным исключением, если произошла ошибка. До Python 2.4 модуль мог быть создан даже в случае ошибки. Начиная с Python 2.4, name удаляется из sys.modules в случае ошибки, даже если name уже находился в sys.modules на момент вызова PyImport_ExecCodeModule(). Оставление неполностью инициализированных модулей в sys.modules опасно, так как импорт таких модулей не может определить, что объект модуля находится в неизвестном (и, вероятно, повреждённом относительно намерений автора модуля) состоянии.

Атрибут __file__ модуля будет установлен в co_filename объекта кода.

Эта функция перезагрузит модуль, если он уже был импортирован. См. PyImport_ReloadModule() для описания правильного способа перезагрузки модуля.

Если name указывает на имя с точками вида package.module, любые структуры пакета, которые ещё не были созданы, по-прежнему не будут созданы.

Изменено в версии 2.4: name удаляется из sys.modules в случае ошибки.

PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)¶: Возвращаемое значение: новая ссылка.
Как и PyImport_ExecCodeModule(), но атрибут __file__ объекта модуля устанавливается в pathname, если он не равен NULL.

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

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. Возвращает новую ссылку на объект импортёра.

Новое в версии 2.6.

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

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

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

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

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

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

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, void (*initfunc)(void))¶: Добавляет один модуль в существующую таблицу встроенных модулей. Это удобная обёртка вокруг PyImport_ExtendInittab(), возвращающая -1, если таблицу не удалось расширить. Новый модуль можно импортировать по имени name, и он использует функцию initfunc в качестве функции инициализации, вызываемой при первой попытке импорта. Это должно вызываться до Py_Initialize().

struct _inittab¶

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

struct _inittab {
    char *name;
    void (*initfunc)(void);
};

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