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

PyObject *PyImport_ImportModule(const char *name)

Значение возврата: Новый ссылка. Часть Стабильной ABI.

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

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

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

END_OF_DOCUMENT_MARKER

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). Магическое число должно быть представлено в первых четырёх байтах файла байт-кода в порядке little-endian. При ошибке возвращает -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.
Возвращает объект поиска для элемента sys.path/pkg.__path__ с именем 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.

int PyImport_ExtendInittab(struct _inittab *newtab)

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

Если Python инициализируется несколько раз, PyImport_AppendInittab() или PyImport_ExtendInittab() должны вызываться перед каждой инициализацией Python.