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

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

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

PyObject *PyModule_Create(PyModuleDef *def)¶

Return value: New reference.

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

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

Return value: New reference. Part of the Stable ABI.

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

Примечание

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

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

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

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

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

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

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

PyObject *PyModuleDef_Init(PyModuleDef *def)¶

Return value: Borrowed reference. Part of the Stable 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 должен быть завершен слотом с id 0.

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

Py_mod_create¶

Определяет функцию, которая вызывается для создания самого объекта модуля. Указатель значение этого слота должен указывать на функцию с такой сигнатурой:

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

Return value: New reference.

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

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

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

Return value: New reference. Part of the Stable ABI since version 3.7.

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

Примечание

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

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

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

Part of the Stable ABI since version 3.7.

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

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

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

Part of the Stable ABI since version 3.7.

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

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

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

Part of the Stable ABI since version 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)¶

Part of the Stable 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_XDECREF() вместо Py_DECREF(), поскольку obj может быть NULL.

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

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

Part of the Stable ABI.

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

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

Примечание

В отличие от других функций, которые крадут ссылки, PyModule_AddObject() только уменьшает счетчик ссылок значения при успехе.

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

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

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_XDECREF() вместо Py_DECREF(), поскольку obj может быть NULL.

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

Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

int PyModule_AddIntMacro(PyObject *module, macro)¶

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

int PyModule_AddStringMacro(PyObject *module, macro)¶

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

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

Part of the Stable ABI since version 3.10.

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

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