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

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): Значение возврата: Новый указатель.
Возвращает новый объект модуля со свойством __name__, установленным на name. Свойства модуля __name__, __doc__, __package__ и __loader__ заполняются (кроме __name__, которые устанавливаются на None); вызывающий метод отвечает за предоставление свойства __file__.

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

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

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

PyObject* PyModule_GetDict(PyObject *module)

Значение возврата: Заимствованный указатель.

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

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

PyObject* PyModule_GetNameObject(PyObject *module): Значение возврата: Новый указатель.
Возвращает значение __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): Значение возврата: Новый указатель.
Возвращает имя файла, из которого был загружен модуль module, используя свойство __file__ модуля. Если оно не определено или не является строкой Unicode, генерируется SystemError и возвращается NULL; в противном случае возвращается ссылка на объект Unicode.

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

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

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

END_OF_DOCUMENT_MARKER

Инициализация модулей 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 , если она не нужна.

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

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

inquiry m_clear

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

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

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

freefunc m_free

Функция для вызова при удалении объекта модуля или 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): Значение возврата: Новая ссылка.
Создает новый объект модуля, используя определение в 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)

Значение результата: Заимствованная ссылка.

Обеспечивает, что определение модуля является должным образом инициализированным объектом 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): Значение результата: Новая ссылка.
Создаёт новый объект модуля, заданный определением в module и ModuleSpec spec. Это эквивалентно PyModule_FromDefAndSpec2() с установленным module_api_version в PYTHON_API_VERSION.

Введено в версии 3.5.

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

Введено в версии 3.5.

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

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

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

Добавление объекта в модуль как имя. Это удобная функция, которую можно использовать из функции инициализации модуля. При успехе происходит взятие ссылки на значение. Возвращает -1 при ошибке, 0 при успехе.

Примечание

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

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

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): Добавление целочисленной константы в модуль как имя. Эта удобная функция может использоваться из функции инициализации модуля. Возвращает -1 при ошибке, 0 при успехе.

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

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

int PyModule_AddStringMacro(PyObject *module, macro): Добавление строковой константы в модуль.

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

Введено в версии 3.9.

Поиск модулей

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

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

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

int PyState_AddModule(PyObject *module, PyModuleDef *def)

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

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

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

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

Возвращает 0 при успехе или -1 при ошибке.

Введено в версии 3.3.

int PyState_RemoveModule(PyModuleDef *def)

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

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

Введено в версии 3.3.