Импорт модулей

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, даже если при входе в PyImport_ExecCodeModule() name уже находилось в sys.modules. Оставлять в 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 задано значение NULL, также предпринимаются попытки определить его значение по cpathname.

Добавлено в версии 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 инициализируется несколько раз, перед каждой инициализацией Python необходимо вызывать PyImport_AppendInittab() или PyImport_ExtendInittab().