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

Одноэтапная инициализация

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

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_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.

Добавляет в module функции из массива functions, завершающегося значением NULL. Подробности об отдельных записях см. в документации 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.

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

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;
 }

Для удобства функция принимает значение NULL в качестве value при установленном исключении. В этом случае возвращает -1 и оставляет возбужденное исключение без изменений.

Пример можно также записать без явной проверки, равно ли 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.

Количество различных строк name, передаваемых этой функции, следует свести к минимуму; обычно для этого используют в качестве name только статически выделенные строки. Для имен, неизвестных во время компиляции, предпочтительно напрямую вызывать PyUnicode_FromString() и PyObject_SetAttr(). Подробнее см. PyUnicode_InternFromString(), которую можно использовать внутри для создания объекта-ключа.

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

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

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

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

Рекомендуется использовать новую функцию 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)

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

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

Это вспомогательная функция, которая вызывает PyLong_FromLong() и PyModule_AddObjectRef(); подробности см. в их документации.

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

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

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

Это вспомогательная функция, которая вызывает PyUnicode_InternFromString() и PyModule_AddObjectRef(); подробности см. в их документации.

PyModule_AddIntMacro(module, macro)

Добавляет в module целочисленную константу. Имя и значение берутся из macro. Например, PyModule_AddIntMacro(module, AF_INET) добавляет в module целочисленную константу AF_INET со значением AF_INET. В случае ошибки возвращает -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.