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

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

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

PyObject *PyModule_Create(PyModuleDef *def)¶

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

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

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)¶

Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI.

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

Примечание

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

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

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

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

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

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

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

PyObject *PyModuleDef_Init(PyModuleDef *def)¶

Возвращаемое значение: Заимствованная ссылка. Part of the Стабильный ABI since version 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¶

Указывает функцию, которая вызывается для создания самого объекта module. Указатель 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)¶

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

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

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

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

Возвращаемое значение: Новая ссылка. Part of the Стабильный ABI since version 3.7.

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

Примечание

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

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

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)¶

Part of the Стабильный ABI since version 3.7.

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

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

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

Part of the Стабильный ABI since version 3.7.

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

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

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)¶

Part of the Стабильный ABI since version 3.7.

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

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

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

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

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

Part of the Стабильный ABI since version 3.10.

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

В случае успеха верните 0. В случае ошибки создайте исключение и верните -1.

Возвращает NULL, если значение равно 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_DECREF() следует использовать Py_XDECREF(), поскольку obj может быть NULL.

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

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

Part of the Стабильный 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_DECREF() следует использовать Py_XDECREF(), поскольку obj может быть NULL.

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

Part of the Стабильный ABI.

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

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

Part of the Стабильный ABI.

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

PyModule_AddIntMacro(module, macro)¶

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

PyModule_AddStringMacro(module, macro)¶

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

int PyModule_AddType(PyObject *module, PyTypeObject *type)¶

Part of the Стабильный ABI since version 3.10.

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

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