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

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

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

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.

Дополнительные экземпляры модуля могут создаваться в субинтерпретаторах или после повторной инициализации среды выполнения Python (Py_Finalize() и Py_Initialize()). В этих случаях совместное использование объектов Python экземплярами модуля, вероятно, приведёт к сбоям или неопределённому поведению.

Чтобы избежать подобных проблем, каждый экземпляр модуля расширения должен быть изолирован: изменения одного экземпляра не должны неявно влиять на остальные, а всё состояние, включая ссылки на объекты Python, должно относиться к конкретному экземпляру модуля. Подробнее и практическое руководство см. в разделе Изоляция модулей расширения.

Более простой способ избежать подобных проблем — выдавать ошибку при повторной инициализации.

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

Чтобы запросить многоэтапную инициализацию, функция инициализации (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.

Py_mod_gil

Задаёт одно из следующих значений:

Py_MOD_GIL_USED

Модуль зависит от наличия глобальной блокировки интерпретатора (GIL) и может обращаться к глобальному состоянию без синхронизации.

Py_MOD_GIL_NOT_USED

Модуль безопасно работает без активной GIL.

Этот слот игнорируется сборками Python, сконфигурированными без --disable-gil. В противном случае он определяет, приведёт ли импорт данного модуля к автоматическому включению GIL. Подробнее см. в разделе CPython без потоковой блокировки.

В одном определении модуля нельзя указать несколько слотов Py_mod_gil.

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

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

Подробнее о многоэтапной инициализации см. в 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 (из-за отсутствия общего пространства имён модулей «функции» уровня модуля, реализованные на 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_XDECREF() вместо Py_DECREF(), поскольку obj может быть NULL.

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

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

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

Входит в стабильный ABI начиная с версии 3.13.

Аналогична PyModule_AddObjectRef(), но «забирает» ссылку на value. Её можно вызвать с результатом функции, возвращающей новую ссылку, не проверяя результат и даже не сохраняя его в переменную.

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

if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
    goto error;
}

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

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

Входит в стабильный ABI.

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

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

Примечание

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

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

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

PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
    // If 'obj' is not NULL and PyModule_AddObject() failed,
    // 'obj' strong reference must be deleted with Py_XDECREF().
    // If 'obj' is NULL, Py_XDECREF() does nothing.
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() stole a reference to obj:
// Py_XDECREF(obj) is not needed here.

Устарела начиная с версии 3.13: PyModule_AddObject() имеет статус условно устаревшей.

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.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)

Это нестабильный API. Он может изменяться без предупреждения в минорных выпусках.

Указывает, поддерживает ли module работу без глобальной блокировки интерпретатора (GIL), используя одно из значений Py_mod_gil. Функцию необходимо вызвать во время инициализации module. Если во время инициализации модуля эта функция не вызывается, механизм импорта считает, что модуль не поддерживает работу без GIL. Эта функция доступна только в сборках Python, настроенных с параметром --disable-gil. В случае ошибки возвращает -1 с установленным исключением, в случае успеха — 0.

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