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

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

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

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.

Примечание

В большинстве случаев следует использовать 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.

См. 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.

Примечание

В большинстве случаев следует использовать 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.

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

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

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

Новая в версии 3.10.

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

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

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

Рекомендуется использовать новую функцию 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_XDECREF() вместо Py_DECREF(), так как obj может быть NULL.

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

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

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

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

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

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

int PyModule_AddIntMacro(PyObject *module, macro)

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

int PyModule_AddStringMacro(PyObject *module, macro)

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

int PyModule_AddType(PyObject *module, PyTypeObject *type)

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

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

Новая в версии 3.9.