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

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

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

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 должен завершаться слотом с id 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_NOT_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)

Часть Стабильного API с версии 3.10.

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

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

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

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

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

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

Часть Стабильного API с версии 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)

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

Аналогично 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) {
    // 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)

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

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

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

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

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

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

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

PyModule_AddIntMacro(module, macro)

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

PyModule_AddStringMacro(module, macro)

Добавляет строковую константу в модуль.

int PyModule_AddType(PyObject *module, PyTypeObject *type)

Часть Стабильного API с версии 3.10.

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

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

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)

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

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

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