Объекты модулей

Однофазная инициализация

Функция инициализации модуля может напрямую создать и вернуть объект модуля. Это называется «однофазной инициализацией» и использует одну из следующих двух функций создания модулей:

PyObject *PyModule_Create(PyModuleDef *def)

Значение возврата: Новая ссылка.

Создаёт новый объект модуля, используя определение в def. Это работает как PyModule_Create2() с module_api_version, установленным в PYTHON_API_VERSION.

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)

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

Создаёт новый объект модуля, используя определение в def, предполагая версию API module_api_version. Если эта версия не совпадает с версией интерпретатора, запускаемого в данный момент, генерируется RuntimeWarning.

Возвращает NULL с установленным исключением в случае ошибки.

Примечание

Большинство случаев использования этой функции должны использовать PyModule_Create() вместо этого; используйте только эту функцию, если вы уверены, что вам она необходима.

Перед возвращением из функции инициализации, полученный объект модуля обычно заполняется с помощью функций, таких как PyModule_AddObjectRef().

Многофазная инициализация

Альтернативный способ указания расширений — запрос «многофазной инициализации». Модули расширений, созданные таким образом, ведут себя больше как модули Python: инициализация разбивается на фазу создания, когда создаётся объект модуля, и фазу выполнения, когда он заполняется. Различие аналогично методам __new__() и __init__() классов.

В отличие от модулей, созданных с помощью однофазной инициализации, эти модули не являются синглетонами: если запись в sys.modules удаляется, а модуль повторно импортируется, создаётся новый объект модуля, а старый модуль подвергается стандартной обработке сборки мусора — как и в случае с модулями Python. По умолчанию несколько модулей, созданных по одному определению, должны быть независимыми: изменения в одном не должны влиять на другие. Это означает, что всё состояние должно быть специфичным для объекта модуля (например, используя PyModule_GetState()) или его содержимого (например, __dict__ модуля или отдельных классов, созданных с помощью PyType_FromSpec()).

Ожидается, что все модули, созданные с помощью многофазной инициализации, будут поддерживать подмножество интерпретаторов. Обеспечение независимости нескольких модулей обычно достаточно для достижения этой цели.

Для запроса многофазной инициализации функция инициализации (PyInit_modulename) возвращает экземпляр PyModuleDef с непустым m_slots. Перед возвращением экземпляр PyModuleDef должен быть инициализирован следующей функцией:

PyObject *PyModuleDef_Init(PyModuleDef *def)

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

Обеспечивает, что определение модуля является должным образом инициализированным объектом Python, который корректно сообщает о своём типе и счетчике ссылок.

Возвращает def, приведённый к типу PyObject*, или NULL, если произошла ошибка.

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

Член m_slots определения модуля должен указывать на массив структур PyModuleDef_Slot:

type PyModuleDef_Slot

int slot

Идентификатор слота, выбранный из доступных значений, объяснённых ниже.

void *value

Значение слота, смысл которого зависит от идентификатора слота.

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

Массив m_slots должен завершаться слотом с идентификатором 0.

Доступные типы слотов:

Py_mod_create

Указывает функцию, вызываемую для создания самого объекта модуля. Указатель value этого слота должен указывать на функцию с сигнатурой:

PyObject *create_module(PyObject *spec, PyModuleDef *def)

Функция получает экземпляр ModuleSpec, как определено в PEP 451, и определение модуля. Она должна возвращать новый объект модуля или устанавливать ошибку и возвращать NULL.

Эта функция должна быть минимальной. В частности, она не должна вызывать произвольный Python-код, так как попытка повторного импорта того же модуля может привести к бесконечной петле.

Несколько слотов Py_mod_create не могут быть указаны в одном определении модуля.

Если Py_mod_create не указан, механизм импорта создаст обычный объект модуля с помощью PyModule_New(). Имя берётся из spec, а не из определения, что позволяет модулям расширения динамически подстраиваться под своё место в иерархии модулей и импортироваться под разными именами через символические ссылки, при этом используя одно определение модуля.

Нет требования, чтобы возвращаемый объект был экземпляром PyModule_Type. Может использоваться любой тип, если он поддерживает установку и получение атрибутов, связанных с импортом. Тем не менее, могут быть возвращены только экземпляры PyModule_Type если у PyModuleDef есть не-NULL m_traverse, m_clear, m_free; ненулевой m_size; или слоты, отличные от Py_mod_create.

Py_mod_exec

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

int exec_module(PyObject *module)

Если указано несколько слотов Py_mod_exec, они обрабатываются в порядке их появления в массиве m_slots.

Py_mod_multiple_interpreters

Указывает одно из следующих значений:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED

Модуль не поддерживает импорт в подмножества интерпретаторов.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED

Модуль поддерживает импорт в подмножества интерпретаторов, но только когда они совместно используют основной интерпретатор GIL. (См. Изолирование модулей расширения.)

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED

Модуль поддерживает импорт в подмножества интерпретаторов, даже когда у них есть свой собственный GIL. (См. Изолирование модулей расширения.)

Этот слот определяет, произойдёт ли ошибка при импорте этого модуля в подмножество интерпретаторов.

Несколько слотов Py_mod_multiple_interpreters не могут быть указаны в одном определении модуля.

Если Py_mod_multiple_interpreters не указан, механизм импорта использует значение по умолчанию Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED.

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

См. PEP 489 для получения дополнительной информации о многофазной инициализации.

Функции низкоуровневого создания модулей

Следующие функции вызываются под капотом при использовании многофазного инициализации. Они могут быть использованы напрямую, например, при динамическом создании объектов модуля. Обратите внимание, что для полной инициализации модуля необходимо вызвать как PyModule_FromDefAndSpec, так и PyModule_ExecDef.

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)

Значение возврата: Новая ссылка.

Создает новый объект модуля, используя определение в def и ModuleSpec spec. Это работает так же, как PyModule_FromDefAndSpec2() с module_api_version, установленным в PYTHON_API_VERSION.

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

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)

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

Создает новый объект модуля, используя определение в def и ModuleSpec spec, предполагая версию API module_api_version. Если эта версия не соответствует версии работающего интерпретатора, выводится RuntimeWarning.

Возвращает NULL при ошибке.

Примечание

Большинство случаев использования этой функции должны использовать PyModule_FromDefAndSpec() вместо неё; используйте эту функцию только если вы уверены, что вам это необходимо.

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

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)

Часть Стабильной ABI с версии 3.7.

Обрабатывает все слоты выполнения (Py_mod_exec), указанные в def.

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

int PyModule_SetDocString(PyObject *module, const char *docstring)

Часть Стабильной ABI с версии 3.7.

Устанавливает строку документации для module на docstring. Эта функция вызывается автоматически при создании модуля из PyModuleDef, используя либо PyModule_Create, либо PyModule_FromDefAndSpec.

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

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)

Часть Стабильной ABI с версии 3.7.

Добавляет функции из массива functions, завершённого NULL, в module. Обратитесь к документации PyMethodDef для получения подробной информации об отдельных записях (из-за отсутствия общего пространства имён модуля, функции уровня модуля, реализованные на С, обычно принимают модуль в качестве первого параметра, делая их похожими на методы экземпляров в классах Python). Эта функция вызывается автоматически при создании модуля из PyModuleDef, используя либо PyModule_Create, либо PyModule_FromDefAndSpec.

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

Вспомогательные функции

Функция инициализации модуля (если используется однофазная инициализация) или функция, вызываемая из слота выполнения модуля (если используется многофазная инициализация), может использовать следующие функции для помощи в инициализации состояния модуля:

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)

Часть Стабильной ABI с версии 3.10.

Добавляет объект в module под именем name. Это удобная функция, которую можно использовать из функции инициализации модуля.

При успехе возвращает 0. При ошибке генерирует исключение и возвращает -1.

Возвращает -1, если value равно NULL. В этом случае необходимо вызвать её с поднятым исключением.

Пример использования:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (obj == NULL) {
        return -1;
    }
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_DECREF(obj);
    return res;
 }

Пример также можно записать, не проверяя явно, является ли obj NULL:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_XDECREF(obj);
    return res;
 }

Обратите внимание, что в этом случае следует использовать Py_XDECREF(), а не Py_DECREF(), так как obj может быть NULL.

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

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)

Часть Стабильной ABI.

Аналогично PyModule_AddObjectRef(), но при успехе заимствует ссылку на value (если возвращает 0).

Новая функция PyModule_AddObjectRef() рекомендуется, так как легко допустить утечку памяти при неправильном использовании функции PyModule_AddObject().

Примечание

В отличие от других функций, которые заимствуют ссылки, PyModule_AddObject() освобождает ссылку на value только при успехе.

Это означает, что необходимо проверить значение возврата, и код, вызывающий функцию, должен вручную вызвать Py_DECREF() value при ошибке.

Пример использования:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (obj == NULL) {
        return -1;
    }
    if (PyModule_AddObject(module, "spam", obj) < 0) {
        Py_DECREF(obj);
        return -1;
    }
    // PyModule_AddObject() stole a reference to obj:
    // Py_DECREF(obj) is not needed here
    return 0;
}

Пример также можно записать, не проверяя явно, является ли obj NULL:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (PyModule_AddObject(module, "spam", obj) < 0) {
        Py_XDECREF(obj);
        return -1;
    }
    // PyModule_AddObject() stole a reference to obj:
    // Py_DECREF(obj) is not needed here
    return 0;
}

Обратите внимание, что в этом случае следует использовать Py_XDECREF(), а не Py_DECREF(), так как obj может быть NULL.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

Часть Стабильной ABI.

Добавляет целочисленную константу в module под именем name. Эта удобная функция может быть использована из функции инициализации модуля. Возвращает -1 при ошибке, 0 при успехе.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)

Часть Стабильной ABI.

Добавляет строковую константу в module под именем name. Эта удобная функция может быть использована из функции инициализации модуля. Строка value должна быть завершена NULL символом. Возвращает -1 при ошибке, 0 при успехе.

PyModule_AddIntMacro(module, macro)

Добавляет целочисленную константу в module. Имя и значение берутся из macro. Например, PyModule_AddIntMacro(module, AF_INET) добавляет целочисленную константу AF_INET со значением AF_INET в module. Возвращает -1 при ошибке, 0 при успехе.

PyModule_AddStringMacro(module, macro)

Добавляет строковую константу в module.

int PyModule_AddType(PyObject *module, PyTypeObject *type)

Часть Стабильной ABI с версии 3.10.

Добавляет объект типа в module. Объект типа завершается вызовом PyType_Ready() внутри. Имя объекта типа берётся из последней компоненты tp_name после точки. Возвращает -1 при ошибке, 0 при успехе.

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