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

PyTypeObject PyModule_Type¶

Часть Stable ABI.

Этот экземпляр PyTypeObject представляет тип Python-модуля. Он доступен программам Python как types.ModuleType.

int PyModule_Check(PyObject *p)¶

Возвращает истину, если p – объект модуля или подтип объекта модуля. Эта функция всегда выполняется успешно.

int PyModule_CheckExact(PyObject *p)¶

Возвращает истину, если p – объект модуля, но не подтип PyModule_Type. Эта функция всегда выполняется успешно.

PyObject *PyModule_NewObject(PyObject *name)¶

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

Возвращает новый объект модуля с module.__name__, установленным в name. Атрибуты модуля __name__, __doc__, __package__ и __loader__ заполняются (все, кроме __name__, устанавливаются в None). Вызывающий отвечает за установку атрибута __file__.

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

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

Изменено в версии 3.4: __package__ и __loader__ теперь устанавливаются в None.

PyObject *PyModule_New(const char *name)¶

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

Аналогично PyModule_NewObject(), но имя – строка в кодировке UTF-8, а не объект Unicode.

PyObject *PyModule_GetDict(PyObject *module)¶

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

Возвращает объект словаря, реализующий пространство имён module; этот объект совпадает с атрибутом __dict__ объекта модуля. Если module не является объектом модуля (или подтипом объекта модуля), возбуждается SystemError и возвращается NULL.

Расширениям рекомендуется использовать другие функции PyModule_* и PyObject_* вместо прямого манипулирования __dict__ модуля.

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

PyObject *PyModule_GetNameObject(PyObject *module)¶

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

Возвращает значение __name__ для module. Если модуль не предоставляет такого значения или оно не является строкой, возбуждается SystemError и возвращается NULL.

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

const char *PyModule_GetName(PyObject *module)¶

Часть Stable ABI.

Аналогично PyModule_GetNameObject(), но возвращает имя, закодированное в 'utf-8'.

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

void *PyModule_GetState(PyObject *module)¶

Часть Stable ABI.

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

PyModuleDef *PyModule_GetDef(PyObject *module)¶

Часть Stable ABI.

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

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

PyObject *PyModule_GetFilenameObject(PyObject *module)¶

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

Возвращает имя файла, из которого был загружен module, используя атрибут __file__ модуля module. Если он не определён или не является строкой, возбуждает SystemError и возвращает NULL; в противном случае возвращает ссылку на объект Unicode.

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

const char *PyModule_GetFilename(PyObject *module)¶

Часть Stable ABI.

Аналогично PyModule_GetFilenameObject(), но возвращает имя файла, закодированное в 'utf-8'.

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

Устарело с версии 3.2: PyModule_GetFilename() возбуждает UnicodeEncodeError для некодируемых имён файлов; вместо него используйте PyModule_GetFilenameObject().

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

Функции из предыдущего раздела работают с любым объектом модуля, в том числе с модулями, импортированными из кода Python.

Модули, определённые через C API, обычно используют определение модуля, PyModuleDef – статически выделенное, неизменное «описание» того, как должен быть создан модуль.

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

В отличие от PyModule_New(), определение позволяет управлять состоянием модуля – областью памяти, которая выделяется и очищается вместе с объектом модуля. В отличие от атрибутов модуля Python, код Python не может заменить или удалить данные, хранящиеся в состоянии модуля.

type PyModuleDef¶

Часть Stable ABI (включая все члены).

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

PyModuleDef_Base m_base¶

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

const char *m_name¶

Имя нового модуля.

const char *m_doc¶

Докстринг для модуля; обычно используется переменная докстринга, созданная с помощью PyDoc_STRVAR.

Py_ssize_t m_size¶

Состояние модуля может храниться в выделенной под каждый модуль области памяти, доступ к которой можно получить через PyModule_GetState(), а не в статических глобальных переменных. Это делает модули безопасными для использования в нескольких под-интерпретаторах.

Эта область памяти выделяется на основе m_size при создании модуля и освобождается при удалении объекта модуля, после вызова функции m_free (если она присутствует).

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

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

Подробнее см. PEP 3121.

PyMethodDef *m_methods¶

Указатель на таблицу функций уровня модуля, описываемых значениями PyMethodDef. Может быть NULL, если функции отсутствуют.

PyModuleDef_Slot *m_slots¶

Массив определений слотов для многофазной инициализации, завершающийся записью {0, NULL}. При использовании устаревшей однофазной инициализации m_slots должен быть NULL.

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

inquiry m_reload¶

traverseproc m_traverse¶

Функция обхода, вызываемая при GC-обходе объекта модуля, или NULL, если она не нужна.

Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция Py_mod_exec). Если точнее, функция не вызывается, когда m_size больше 0 и состояние модуля (возвращаемое PyModule_GetState()) равно NULL.

Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.

inquiry m_clear¶

Функция очистки, вызываемая при GC-очистке объекта модуля, или NULL, если она не нужна.

Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция Py_mod_exec). Если точнее, функция не вызывается, когда m_size больше 0 и состояние модуля (возвращаемое PyModule_GetState()) равно NULL.

Как и PyTypeObject.tp_clear, эта функция вызывается не всегда перед освобождением модуля. Например, когда подсчёта ссылок достаточно, чтобы определить, что объект больше не используется, циклический сборщик мусора не задействуется, и m_free вызывается напрямую.

Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.

freefunc m_free¶

Функция, вызываемая при освобождении объекта модуля, или NULL, если она не нужна.

Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция Py_mod_exec). Если точнее, функция не вызывается, когда m_size больше 0 и состояние модуля (возвращаемое PyModule_GetState()) равно NULL.

Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.

PyTypeObject PyModuleDef_Type¶

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

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

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

Следующие функции можно использовать для создания модуля за пределами инициализирующей функции расширения. Они также используются в однофазной инициализации.

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.

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.

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

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

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

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

PYTHON_API_VERSION¶

Версия C API. Определяется для обратной совместимости.

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

PYTHON_ABI_VERSION¶

Определяется как 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.