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

PyTypeObject PyModule_Type

Сущность 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)

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 и spec ModureSpec. Ведет себя как 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 и spec ModureSpec, предполагая, что версия 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.