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

Однофазная инициализация¶Single-phase initialization

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

PyObject *PyModule_Create(PyModuleDef *def)¶

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

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

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

Возвращаемое значение: новая ссылка. Часть Stable ABI.

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

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

Примечание

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

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

Многофазная инициализация¶Multi-phase initialization

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

В отличие от модулей, созданных с помощью однофазной инициализации, эти модули не являются синглтонами. Например, если запись sys.modules удалена и модуль импортируется заново, создаётся новый объект модуля, который обычно заполняется свежими объектами методов и типов. Старый модуль подлежит обычной сборке мусора. Это отражает поведение чистых модулей Python.

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

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

A simpler way to avoid these issues is raising an error on repeated initialization.

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

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

PyObject *PyModuleDef_Init(PyModuleDef *def)¶

Возвращаемое значение: Borrowed reference. Часть Stable ABI начиная с версии 3.5.

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

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

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

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

type PyModuleDef_Slot¶

Часть Stable ABI (включая все элементы) начиная с версии 3.5.

int slot¶

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

void *value¶

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

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

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

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

Py_mod_create¶

Часть Stable ABI начиная с версии 3.5.

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

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

Py_mod_exec¶

Часть Stable ABI начиная с версии 3.5.

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

int exec_module(PyObject *module)¶

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

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

Py_mod_multiple_interpreters¶

Часть Stable ABI начиная с версии 3.12.

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

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¶

Часть Stable ABI, начиная с версии 3.13.

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

Py_MOD_GIL_USED¶

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

Py_MOD_GIL_NOT_USED¶

Модуль можно безопасно использовать без активного GIL.

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

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

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

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

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

Низкоуровневые функции создания модулей ¶Low-level module creation functions

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

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

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

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

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

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

Возвращаемое значение: новая ссылка. Часть Stable ABI начиная с версии 3.7.

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

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

Примечание

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

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

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

Часть Stable ABI начиная с версии 3.7.

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

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

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

Часть Stable ABI начиная с версии 3.7.

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

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

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

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

Часть Stable ABI начиная с версии 3.7.

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

Массив functions должен быть статически выделен (или иным образом гарантированно переживать объект модуля).

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

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

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

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

Часть Stable 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)¶

Часть Stable 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)¶

Часть Stable ABI.

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

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

Примечание

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

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

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

PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
    // Если 'obj' не NULL и PyModule_AddObject() завершился неудачей,
    // сильную ссылку 'obj' необходимо удалить с помощью Py_XDECREF().
    // Если 'obj' равен NULL, Py_XDECREF() ничего не делает.
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() перехватил ссылку на obj:
// Py_XDECREF(obj) здесь не требуется.

Мягкое устаревание начиная с версии 3.13.

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

Часть Stable ABI.

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

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

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

Часть Stable ABI.

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

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

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)¶

Часть Stable 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.