Объекты модулей¶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)¶

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

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

Примечание

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

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

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

Альтернативный способ задания расширений – запросить «многофазную инициализацию». Модули расширения, созданные таким образом, ведут себя больше как модули 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 должен завершаться слотом с 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.

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

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

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

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

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

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

Новое в версии 3.5.

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

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

Создаёт новый объект модуля на основе определения module и спецификации модуля 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)¶

Устанавливает 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.

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

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

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

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

Примечание

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

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

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

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

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

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

int PyModule_AddIntMacro(PyObject *module, macro)¶

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

int PyModule_AddStringMacro(PyObject *module, macro)¶

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