Содержание страницы

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

Есть лишь несколько функций, специфичных для объектов модуля.

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

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

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

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

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

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

PyObject* PyModule_New(const char *name)¶: Возвращаемое значение: новая ссылка.
Аналогично PyImport_NewObject(), но имя – это строка в кодировке UTF-8, а не объект Unicode.

PyObject* PyModule_GetDict(PyObject *module)¶: Возвращаемое значение: заимствованная ссылка.
Возвращает объект словаря, который реализует пространство имён module; этот объект совпадает с атрибутом __dict__ объекта модуля. Эта функция никогда не завершается ошибкой. Расширениям рекомендуется использовать другие PyModule_*() и PyObject_*() функции, а не напрямую манипулировать __dict__ модуля.

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

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

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

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

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

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

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

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

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

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

int PyState_AddModule(PyObject *module, PyModuleDef *def)¶: Присоединяет переданный функции объект модуля к состоянию интерпретатора. Это позволяет получить доступ к объекту модуля через PyState_FindModule().

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

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

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

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

Эти функции обычно используются в функции инициализации модуля.

PyObject* PyModule_Create(PyModuleDef *module)¶: Создаёт новый объект модуля по определению в module. Работает как PyModule_Create2(), где module_api_version установлено в PYTHON_API_VERSION.

PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)¶: Создаёт новый объект модуля по определению в module, принимая версию API module_api_version. Если эта версия не совпадает с версией работающего интерпретатора, выдаётся RuntimeWarning.

Примечание

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

PyModuleDef¶

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

PyModuleDef_Base m_base¶: Этот член следует всегда инициализировать значением PyModuleDef_HEAD_INIT.

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

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

Py_ssize_t m_size¶

Некоторые модули допускают повторную инициализацию (вызов их функции PyInit_* более одного раза). Такие модули должны хранить своё состояние в области памяти, выделенной на модуль, которую можно получить с помощью PyModule_GetState().

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

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

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

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

inquiry m_reload¶: В настоящее время не используется, должно быть NULL.

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

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

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

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

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 должна завершаться нулевым символом. Возвращает -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.