Модуль объекты¶

PyTypeObject PyModule_Type¶: Экземпляр PyTypeObject представляет тип модуля Python. Он отображается в программах Python как types.ModuleType.

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

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

PyObject* PyModule_NewObject(PyObject *name)¶: Return value: New reference.
Возвращает новый объект модуля с атрибутом __name__, установленным на name. Атрибуты модуля __name__, __doc__, __package__ и __loader__ заполняются (все, кроме __name__, содержат значение None); вызывающий отвечает за предоставление атрибута __file__.

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

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

PyObject* PyModule_New(const char *name)¶: Return value: New reference.
Подобна PyModule_NewObject(), но имя представляет собой строку в кодировке UTF-8 вместо Юникод объекта.

PyObject* PyModule_GetDict(PyObject *module)¶

Return value: Borrowed reference.

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

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

PyObject* PyModule_GetNameObject(PyObject *module)¶: Return value: New reference.
Возвращает значение __name__ module. Если модуль не предоставляет его или это не строка, вызывает SystemError и возвращается NULL.

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

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

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

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

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

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

const char* PyModule_GetFilename(PyObject *module)¶: Аналогична PyModule_GetFilenameObject(), но возвращает имя файла в кодировке «utf-8».

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

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

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

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

PyModuleDef¶

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

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, если не требуется. Эта функция может быть вызвана до того, как будет выделено состояние модуля (PyModule_GetState() может возвращает NULL) и до того, как функция Py_mod_exec будет выполнена.

inquiry m_clear¶: Функция очистки для вызова во время очистки GC объекта модуля или NULL, если не требуется. Эта функция может быть вызвана до выделения состояния модуля (PyModule_GetState() может возвращает NULL) и до выполнения функции Py_mod_exec.

freefunc m_free¶: Функция, вызываемая при освобождении объекта модуля, или NULL, если не требуется. Данная функция может быть вызвана до того, как будет выделено состояние модуля (PyModule_GetState() может возвращает «NULL») и до выполнения функции Py_mod_exec.

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

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

PyObject* PyModule_Create(PyModuleDef *def)¶: Return value: New reference.
Создаёт новый объект модуля, учитывая определение в def. Ведёт себя как PyModule_Create2() с module_api_version, установленным на PYTHON_API_VERSION.

PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)¶: Return value: New reference.
Создаёт новый объект модуля, учитывая определение в 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)¶

Return value: Borrowed reference.

Гарантирует, что определение модуля — это правильно инициализированный объект 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)¶: Return value: New reference.
Создаёт новый объект модуля, учитывая определение в module и ModuleSpec spec. Ведёт себя как PyModule_FromDefAndSpec2() с module_api_version, установленным на PYTHON_API_VERSION.

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

PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)¶: Return value: New reference.
Создаёт новый объект модуля, учитывая определение в 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)¶: Добавить функции из массива NULL с завершением functions в module. Обратитесь к документации PyMethodDef для получения подробной информации об отдельных записях (из-за отсутствия общего пространства имён модуля, «функции» уровня модуля, реализованные в C, обычно получают модуль в качестве своего первого параметра, что делает их похожими на методы экземпляра в классах Python). Данная функция вызывается автоматически при создании модуля из PyModuleDef с использованием PyModule_Create или PyModule_FromDefAndSpec.

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

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

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

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)¶: Добавить константу int к module. Название и значение взяты из macro. Например, PyModule_AddIntMacro(module, AF_INET) добавляет константу int AF_INET со значением AF_INET к module. Возвращает -1 при ошибке, 0 при успехе.

int PyModule_AddStringMacro(PyObject *module, macro)¶: Добавить строковую константу в module.

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

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

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

PyObject* PyState_FindModule(PyModuleDef *def)¶: Return value: Borrowed reference.
Возвращает объект модуля, созданный из def для текущего интерпретатора. Данный метод требует, чтобы объект модуля был заранее прикреплён к состоянию интерпретатора с помощью PyState_AddModule(). Если соответствующий объект модуля не найден или ещё не прикреплен к состоянию интерпретатора, он возвращает NULL.

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

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

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

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

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

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

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

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