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

PyTypeObject PyModule_Type¶: Часть Стабильный ABI.
Этот экземпляр PyTypeObject представляет тип модуля Python. В программах Python он отображается как types.ModuleType.

int PyModule_Check(PyObject *p)¶: Возвращает true, если p является объектом модуля или подтипом объекта модуля. Эта функция всегда работает успешно.

int PyModule_CheckExact(PyObject *p)¶: Возвращает true, если p является объектом модуля, но не является подтипом PyModule_Type. Эта функция всегда успешна.

PyObject *PyModule_NewObject(PyObject *name)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.7.
Возвращает новый объект модуля с атрибутом __name__, установленным на name. Атрибуты __name__, __doc__, __package__ и __loader__ модуля заполнены (все, кроме __name__, установлены в None); вызывающая сторона отвечает за предоставление атрибута __file__.

Added in version 3.3.

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

PyObject *PyModule_New(const char *name)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Аналогично PyModule_NewObject(), но имя представляет собой строку в кодировке UTF-8, а не объект Unicode.

PyObject *PyModule_GetDict(PyObject *module)¶

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

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

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

PyObject *PyModule_GetNameObject(PyObject *module)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI с версии 3.7.
Возвращает значение __name__ модуля module. Если модуль не предоставляет такого значения или если оно не является строкой, то поднимается значение SystemError и возвращается NULL.

Added in version 3.3.

const char *PyModule_GetName(PyObject *module)¶: Часть Стабильный ABI.
Аналогично PyModule_GetNameObject(), но возвращает имя, закодированное в 'utf-8'.

void *PyModule_GetState(PyObject *module)¶: Часть Стабильный ABI.
Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или NULL. См. PyModuleDef.m_size.

PyModuleDef *PyModule_GetDef(PyObject *module)¶: Часть Стабильный ABI.
Возвращает указатель на структуру PyModuleDef, из которой был создан модуль, или NULL, если модуль не был создан из определения.

PyObject *PyModule_GetFilenameObject(PyObject *module)¶: Возвращаемое значение: Новая ссылка. Часть Стабильный ABI.
Возвращает имя файла, из которого был загружен модуль, используя атрибут модуля __file__. Если он не определен или если он не является строкой Юникода, выведите SystemError и верните NULL; в противном случае верните ссылку на объект Юникода.

Added in version 3.2.

const char *PyModule_GetFilename(PyObject *module)¶: Часть Стабильный ABI.
Аналогично PyModule_GetFilenameObject(), но возвращает имя файла в кодировке „utf-8“.

Не рекомендуется, начиная с версии 3.2: PyModule_GetFilename() повышает значение UnicodeEncodeError при некодируемых именах файлов, используйте вместо этого PyModule_GetFilenameObject().

Инициализация модулей C¶

Объекты модулей обычно создаются из модулей расширения (разделяемых библиотек, экспортирующих функцию инициализации) или скомпилированных модулей (в которых функция инициализации добавляется с помощью PyImport_AppendInittab()). Подробности см. в Создание расширений на языках C и C++ или Расширение встроенного Python.

Функция инициализации может либо передать экземпляр определения модуля в PyModule_Create() и вернуть результирующий объект модуля, либо запросить «многофазную инициализацию», вернув саму структуру определения.

type PyModuleDef¶

Часть Стабильный ABI (включая всех членов).

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

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

const char *m_name¶: Имя для нового модуля.

const char *m_doc¶: Документная строка для модуля; обычно используется переменная docstring, созданная с помощью 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: Больше не вызывается до выделения состояния модуля.

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

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

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()).

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

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

PyObject *PyModuleDef_Init(PyModuleDef *def)¶

Возвращаемое значение: Заимствованная ссылка. Часть Стабильный ABI с версии 3.5.

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

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

Added in version 3.5.

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

type PyModuleDef_Slot¶

int slot¶: Идентификатор слота, выбираемый из доступных значений, описанных ниже.

void *value¶: Значение слота, смысл которого зависит от идентификатора слота.

Added in version 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.

Py_mod_multiple_interpreters¶

Укажите одно из следующих значений:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED¶: Модуль не поддерживает импортирование в субинтерпретаторы.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED¶: Модуль поддерживает импортирование в подинтерпретаторы, но только если они разделяют GIL основного интерпретатора. (См. Изолирование модулей расширения).

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED¶: Модуль поддерживает импортирование в субинтерпретаторы, даже если они имеют свой собственный GIL. (См. Изолирование модулей расширения).

Этот слот определяет, будет ли импорт этого модуля в субинтерпретаторе неудачным.

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

Если Py_mod_multiple_interpreters не указан, механизм импорта по умолчанию принимает значение Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED.

Added in version 3.12.

Py_mod_gil¶

Укажите одно из следующих значений:

Py_MOD_GIL_USED¶: Модуль зависит от наличия глобальной блокировки интерпретатора (GIL) и может получить доступ к глобальному состоянию без синхронизации.

Py_MOD_GIL_NOT_USED¶: Модуль безопасен для работы без активного GIL.

Этот слот игнорируется сборками Python, не настроенными на --disable-gil. В противном случае он определяет, приведет ли импорт этого модуля к автоматическому включению GIL. Более подробную информацию см. в разделе Свободнопоточный CPython.

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

Если Py_mod_gil не указан, механизм импорта по умолчанию принимает значение Py_MOD_GIL_USED.

Added in version 3.13.

Более подробную информацию о многофазной инициализации см. в разделе PEP 489.

Низкоуровневые функции создания модулей¶

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

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)¶: Возвращаемое значение: Новая ссылка.
Создает новый объект модуля, учитывая определение в def и ModuleSpec spec. Модуль ведет себя как PyModule_FromDefAndSpec2() с module_api_version, установленной на PYTHON_API_VERSION.

Added in 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(); используйте ее только в том случае, если вы уверены, что она вам нужна.

Added in version 3.5.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)¶: Часть Стабильный ABI с версии 3.7.
Обработайте все слоты выполнения (Py_mod_exec), указанные в def.

Added in version 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)¶: Часть Стабильный ABI с версии 3.7.
Установите для модуля значение docstring. Эта функция вызывается автоматически при создании модуля из PyModuleDef, используя PyModule_Create или PyModule_FromDefAndSpec.

Added in version 3.5.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)¶: Часть Стабильный ABI с версии 3.7.
Добавьте в module функции из массива functions, находящегося в NULL. Подробнее об отдельных функциях см. в документации PyMethodDef (из-за отсутствия общего пространства имен модулей «функции» уровня модуля, реализованные в C, обычно получают модуль в качестве первого параметра, что делает их похожими на методы экземпляра классов Python). Эта функция вызывается автоматически при создании модуля из PyModuleDef, используя PyModule_Create или PyModule_FromDefAndSpec.

Added in version 3.5.

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

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

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

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

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

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

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

Added in version 3.10.

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

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

Аналогична PyModule_AddObjectRef(), но «крадет» ссылку на значение. Ее можно вызвать с результатом функции, которая возвращает новую ссылку, не утруждая себя проверкой результата или даже сохранением его в переменной.

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

if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
    goto error;
}

Added in version 3.13.

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

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

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

Рекомендуется использовать новые функции PyModule_Add() или PyModule_AddObjectRef(), так как при неправильном использовании функции PyModule_AddObject() можно легко получить утечку ссылок.

Примечание

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

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

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

PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
    // If 'obj' is not NULL and PyModule_AddObject() failed,
    // 'obj' strong reference must be deleted with Py_XDECREF().
    // If 'obj' is NULL, Py_XDECREF() does nothing.
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() stole a reference to obj:
// Py_XDECREF(obj) is not needed here.

Не рекомендуется, начиная с версии 3.13: PyModule_AddObject() - это soft deprecated.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)¶: Часть Стабильный ABI.
Добавляет целочисленную константу в модуль в качестве имени. Эта удобная функция может быть использована из функции инициализации модуля. Возвращает -1 при ошибке, 0 при успехе.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)¶: Часть Стабильный ABI.
Добавляет строковую константу в модуль в качестве имени. Эта удобная функция может быть использована из функции инициализации модуля. Строка value должна быть NULL-конечной. Возвращает -1 при ошибке, 0 при успехе.

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

PyModule_AddStringMacro(module, macro)¶: Добавьте строковую константу в модуль.

int PyModule_AddType(PyObject *module, PyTypeObject *type)¶: Часть Стабильный ABI с версии 3.10.
Добавьте объект типа в модуль. Объект типа завершается вызовом внутренней части PyType_Ready(). Имя объекта типа берется из последнего компонента tp_name после точки. При ошибке возвращается -1, при успехе - 0.

Added in version 3.9.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)¶: Это Нестабильный API. Она может меняться без предупреждения в небольших выпусках.

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

Added in version 3.13.

Поиск модуля¶

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

Эти функции не будут работать с модулями, созданными с помощью многофазной инициализации, поскольку из одного определения может быть создано несколько таких модулей.

PyObject *PyState_FindModule(PyModuleDef *def)¶: Возвращаемое значение: Заимствованная ссылка. Часть Стабильный ABI.
Возвращает объект модуля, который был создан из def для текущего интерпретатора. Этот метод требует, чтобы объект модуля был предварительно присоединен к состоянию интерпретатора с помощью PyState_AddModule(). Если соответствующий объект модуля не найден или еще не был присоединен к состоянию интерпретатора, возвращается NULL.

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

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

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

Действует только для модулей, созданных с использованием однофазной инициализации.

Python вызывает PyState_AddModule автоматически после импорта модуля, поэтому нет необходимости (но безвредно) вызывать его из кода инициализации модуля. Явный вызов необходим только в том случае, если собственный код инициализации модуля впоследствии вызывает PyState_FindModule. Функция в основном предназначена для реализации альтернативных механизмов импорта (либо вызывая ее напрямую, либо обращаясь к ее реализации за деталями требуемых обновлений состояния).

Вызывающий должен удерживать GIL.

Возвращает 0 в случае успеха или -1 в случае неудачи.

Added in version 3.3.

int PyState_RemoveModule(PyModuleDef *def)¶

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

Удаляет объект модуля, созданный из def, из состояния интерпретатора. Возвращает 0 в случае успеха или -1 в случае неудачи.

Вызывающий должен удерживать GIL.

Added in version 3.3.

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

Инициализация модулей C¶

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

Многофазная инициализация¶

Низкоуровневые функции создания модулей¶

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

Поиск модуля¶

Оглавление

Предыдущий раздел

Следующий раздел