Модульные объекты

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

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

PyObject *PyModule_Create(PyModuleDef *def)

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

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

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)

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

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

Примечание

Большинство случаев использования этой функции должны использовать 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.

См. 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.

Примечание

Большинство случаев использования этой функции должны использовать 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 (из-за отсутствия общего пространства имён модуля, функции уровня модуля, реализованные на C, обычно получают модуль в качестве своего первого параметра, делая их похожими на методы экземпляров в 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.

Возвращает NULL, если 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.