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

Определение модуля¶Module definition

Модули, создаваемые с помощью C API, обычно определяются массивом структур PySlot, который предоставляет «описание» того, как следует создавать модуль. Подробнее о слотах см. Слоты определения.

Массив слотов обычно используется для определения «основного» объекта модуля расширения (подробнее см. Определение модулей расширения). Он также может использоваться для динамического создания модулей расширения.

Если не указано иное, один и тот же идентификатор слота не может повторяться в массиве слотов.

Состояние модуля ¶Module state

Модули расширения могут иметь состояние модуля – фрагмент памяти, который выделяется при создании модуля и освобождается при удалении объекта модуля. Состояние модуля задаётся с помощью специализированных слотов.

Типичное применение состояния модуля – хранение типа исключения или любого объекта типа, определённого модулем –

В отличие от атрибутов модуля Python, код Python не может заменить или удалить данные, хранящиеся в состоянии модуля.

Хранение информации о модуле в атрибутах и состоянии модуля, а не в статических глобальных переменных, делает объекты модулей изолированными и более безопасными для использования в нескольких под-интерпретаторах. Это также помогает Python выполнять упорядоченную очистку при завершении работы.

Расширения, которые хранят ссылки на объекты Python как часть состояния модуля, должны реализовывать Py_mod_state_traverse и Py_mod_state_clear функции, чтобы избежать утечек ссылок.

Чтобы получить состояние из данного модуля, используйте следующие функции:

void *PyModule_GetState(PyObject *module)¶

Часть Stable ABI.

Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или NULL. См. Py_mod_state_size.

При ошибке возвращает NULL с установленным исключением. Используйте PyErr_Occurred(), чтобы отличить этот случай от отсутствующего состояния модуля.

int PyModule_GetStateSize(PyObject *module, Py_ssize_t *result)¶

Часть Stable ABI начиная с версии 3.15.

Устанавливает *result в размер состояния module, как задано с помощью Py_mod_state_size (или PyModuleDef.m_size), и возвращает 0.

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

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

PyObject *module = <the module in question>

void *module_token;
if (PyModule_GetToken(module, &module_token) < 0) {
    return NULL;
}
if (module_token != your_token) {
    PyErr_SetString(PyExc_ValueError, "unexpected module")
    return NULL;
}

// Состояние этого модуля имеет ожидаемую структуру памяти; приведение типов безопасно.
struct my_state state = (struct my_state*)PyModule_GetState(module)

Создание модулей расширения динамически¶Creating extension modules dynamically

Следующие функции могут использоваться для динамического создания модуля расширения, а не из экспортного хука расширения.

PyObject *PyModule_FromSlotsAndSpec(const PySlot *slots, PyObject *spec)¶

Возвращаемое значение: новая ссылка. Часть Stable ABI начиная с версии 3.15.

Создаёт новый объект модуля, принимая массив слотов и ModuleSpec spec.

Аргумент slots должен указывать на массив структур PySlot структур, завершающийся записью с ID слота 0 (обычно записывается как PySlot_END). Массив должен содержать запись Py_mod_abi.

Аргумент spec может быть любым объектом, подобным ModuleSpec, как описано в документации Py_mod_create. В текущей версии spec должен иметь атрибут name.

При успехе возвращает новый модуль. При ошибке возвращает NULL с установленным исключением.

Обратите внимание: эта функция не обрабатывает слот выполнения модуля (Py_mod_exec). Для полной инициализации модуля необходимо вызвать как PyModule_FromSlotsAndSpec(), так и PyModule_Exec(). (См. также многофазную инициализацию.)

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

int PyModule_Exec(PyObject *module)¶

Часть Stable ABI начиная с версии 3.15.

Выполняет слот(ы) Py_mod_exec модуля module.

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

Для ясности: если у module нет слотов, например, если используется однофазная инициализация (устаревшая), то эта функция ничего не делает и возвращает 0.

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

Структура определения модуля¶Module definition struct

Традиционно модули расширения определялись с помощью определения модуля как «описания» того, как должен создаваться модуль. Вместо прямого использования массива слотов определение содержит выделенные поля для наиболее распространённой функциональности и допускает дополнительные слоты как механизм расширения.

Этот способ определения модулей по-прежнему доступен, и удалять его не планируется.

type PyModuleDef¶

Часть Stable ABI (см. ниже).

Структура определения модуля, содержащая информацию, необходимую для создания объекта модуля.

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

Структура, включая все поля, является частью Stable ABI для сборок без свободных потоков (abi3). В Stable ABI для сборок со свободными потоками (abi3t) эта структура непрозрачна и практически непригодна к использованию; см. Module definition для замены.

PyModuleDef_Base m_base¶

Всегда инициализируйте этот элемент значением PyModuleDef_HEAD_INIT:

type PyModuleDef_Base¶

Часть Stable ABI (см. ниже).

Тип PyModuleDef.m_base.

Структура является частью Stable ABI для сборок без свободных потоков (abi3). В Stable ABI для сборок со свободными потоками (abi3t) эта структура непрозрачна и практически непригодна к использованию.

PyModuleDef_HEAD_INIT¶

Требуемое начальное значение для PyModuleDef.m_base.

const char *m_name¶

Соответствует слоту Py_mod_name.

const char *m_doc¶

Эти элементы соответствуют слоту Py_mod_doc. Установка в NULL равнозначна опусканию слота.

Py_ssize_t m_size¶

Соответствует слоту Py_mod_state_size. Установка в ноль равнозначна опусканию слота.

При использовании однофазной инициализации (устаревшей) или при динамическом создании модулей с помощью PyModule_Create() или PyModule_Create2(), m_size может быть установлен в -1. Это указывает на то, что модуль не поддерживает под-интерпретаторы, поскольку имеет глобальное состояние.

PyMethodDef *m_methods¶

Соответствует слоту Py_mod_methods. Установка в NULL равнозначна опусканию слота.

PyModuleDef_Slot *m_slots¶

Массив дополнительных слотов, завершающийся элементом {0, NULL}. Обратите внимание, что элементы используют более старую структуру PyModuleDef_Slot, а не PySlot.

Если массив содержит слоты, соответствующие элементам PyModuleDef, значения должны совпадать. Например, если используется Py_mod_name в m_slots, PyModuleDef.m_name должен быть установлен на тот же указатель (а не просто на равную строку).

Изменено в версии 3.5: До версии 3.5 этот элемент всегда устанавливался в NULL, и определялся как:

inquiry m_reload¶

type PyModuleDef_Slot¶

Часть Stable ABI (включая все элементы) начиная с версии 3.5.

Более старая структура, определяющая дополнительные слоты модуля.

Обратите внимание, что массив PyModuleDef_Slot может быть включён в массив PySlot с помощью Py_mod_slots, и наоборот с помощью Py_slot_subslots.

Каждая структура PyModuleDef_Slot modslot интерпретируется как следующая структура PySlot:

(PySlot){
   .sl_id=modslot.slot,
   .sl_flags=PySlot_INTPTR | sub_static,
   .sl_ptr=modslot.value
}

где sub_static равно PySlot_STATIC, если слот требует флаг (например, для Py_mod_methods), или если этот флаг присутствует в «родительском» слоте Py_mod_slots (если есть).

int slot¶

Соответствует PySlot.sl_id.

void *value¶

Соответствует PySlot.sl_ptr.

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

traverseproc m_traverse¶

inquiry m_clear¶

freefunc m_free¶

Эти элементы соответствуют слотам Py_mod_state_traverse, Py_mod_state_clear и Py_mod_state_free, соответственно.

Установка этих элементов в NULL равнозначна пропуску соответствующих слотов.

Изменено в версии 3.9: Функции m_traverse, m_clear и m_free больше не вызываются до выделения состояния модуля.

PyTypeObject PyModuleDef_Type¶

Часть Stable ABI начиная с версии 3.5.

Тип объектов PyModuleDef.

Py_mod_slots¶

Часть Stable ABI начиная с версии 3.15.

Slot ID, который работает как Py_slot_subslots, за исключением того, что он задаёт массив структур PyModuleDef_Slot.

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

Следующий API можно использовать для создания модулей из структуры PyModuleDef:

PyObject *PyModule_Create(PyModuleDef *def)¶

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

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

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

Возвращаемое значение: новая ссылка. Часть Stable ABI.

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

Возвращает NULL с установленным исключением в случае ошибки.

Эта функция не поддерживает слоты. Элемент m_slots структуры def должен быть равен NULL.

Примечание

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

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

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

Этот макрос вызывает PyModule_FromDefAndSpec2() с module_api_version, установленным в PYTHON_API_VERSION, или в PYTHON_ABI_VERSION, если используется ограниченный API.

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

Мягкое устаревание с версии 3.16.0a0 (не выпущена): В новом коде используйте PyModule_FromSlotsAndSpec().

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

Возвращаемое значение: новая ссылка. Часть Stable ABI начиная с версии 3.7.

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

Возвращает NULL с установленным исключением в случае ошибки.

Обратите внимание, что это не обрабатывает слоты выполнения (Py_mod_exec). Для полной инициализации модуля необходимо вызвать как PyModule_FromDefAndSpec, так и PyModule_ExecDef.

Примечание

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

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

Мягкое устаревание с версии 3.16.0a0 (не выпущена): В новом коде используйте PyModule_FromSlotsAndSpec().

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

Часть Stable ABI начиная с версии 3.7.

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

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

Мягкое устаревание с версии 3.16.0a0 (не выпущена): Для выполнения собственных слотов выполнения модуля используйте PyModule_Exec(), который работает с модулями, созданными не из структуры PyModuleDef.

PYTHON_API_VERSION¶

PYTHON_API_STRING¶

Версия C API, соответственно как целое число (1013) и строка ("1013"). Определена для обратной совместимости.

В настоящее время эта константа не обновляется в новых версиях Python и не полезна для версионирования. В будущем это может измениться.

PYTHON_ABI_VERSION¶

PYTHON_ABI_STRING¶

Определены как 3 и "3" соответственно для обратной совместимости.

В настоящее время эта константа не обновляется в новых версиях Python и не полезна для версионирования. В будущем это может измениться.

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

Следующие функции предоставляются для помощи в инициализации объекта модуля. Они предназначены для слота выполнения модуля (Py_mod_exec), функции инициализации для устаревшей однофазной инициализации, или кода, создающего модули динамически.

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

Часть Stable ABI начиная с версии 3.10.

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

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

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

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;
 }

Для удобства функция принимает NULL value с установленным исключением. В этом случае возвращает -1 и просто оставляет вызванное исключение без изменений.

Пример можно также написать без явной проверки, что 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)¶

Часть Stable ABI, начиная с версии 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)¶

Часть Stable ABI.

Похоже на 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) {
    // Если 'obj' не NULL и PyModule_AddObject() завершился неудачей,
    // сильную ссылку 'obj' необходимо удалить с помощью Py_XDECREF().
    // Если 'obj' равен NULL, Py_XDECREF() ничего не делает.
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() перехватил ссылку на obj:
// Py_XDECREF(obj) здесь не требуется.

Мягкое устаревание начиная с версии 3.13.

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

Часть Stable ABI.

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

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

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

Часть Stable ABI.

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

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

PyModule_AddIntMacro(module, macro)¶

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

PyModule_AddStringMacro(module, macro)¶

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

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

Часть Stable ABI начиная с версии 3.10.

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

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

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

Часть Stable ABI начиная с версии 3.7.

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

Эта функция вызывается автоматически при создании модуля из PyModuleDef (например, при использовании многофазной инициализации, PyModule_Create или PyModule_FromDefAndSpec). Некоторые авторы модулей могут предпочитать определять функции в нескольких массивах PyMethodDef; в этом случае им следует вызывать эту функцию напрямую.

Массив functions должен быть статически выделен (или иным образом гарантированно переживать объект модуля).

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

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

Часть Stable ABI начиная с версии 3.7.

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

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

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

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)¶

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

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

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