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

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

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

PyObject* PyModule_Create(PyModuleDef *def)

Значение возврата: новая ссылка.

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

PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)

Значение возврата: новая ссылка.

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

Примечание

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

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

Инициализация в несколько фаз

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

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

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

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

PyObject* PyModuleDef_Init(PyModuleDef *def)

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

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

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

Введено в версии 3.5.

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

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)

Значение возврата: Новая ссылка.

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

Введено в версии 3.5.

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

Значение возврата: Новая ссылка.

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

Примечание

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

Введено в версии 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)

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

Введено в версии 3.5.

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

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

Введено в версии 3.5.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)

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

Введено в версии 3.5.

Функции поддержки

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

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

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

Примечание

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

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

Py_INCREF(spam);
if (PyModule_AddObject(module, "spam", spam) < 0) {
    Py_DECREF(module);
    Py_DECREF(spam);
    return NULL;
}

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

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

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

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

int PyModule_AddIntMacro(PyObject *module, macro)

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

int PyModule_AddStringMacro(PyObject *module, macro)

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