Модуль объекты¶
-
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
.
-
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
.
-
PyModuleDef_Base
Однофазная инициализация¶
Функция инициализации модуля может создавать и возвращать объект модуля напрямую. Это называется «однофазной инициализацией» и использует одну из следующих двух функций создания модуля:
-
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.
-
int
Массив 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
.-
PyObject*
-
Py_mod_exec
¶ Задаёт функцию, которая вызывается для выполнения модуля. Он эквивалентен выполнению кода модуля Python: обычно эта функция добавляет в модуль классы и константы. Сигнатура функции:
Если указано несколько слотов
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
в случае успеха.
Поиск модуля¶
Однофазная инициализация создаёт одноэлементные модули, которые можно найти в контексте текущего интерпретатора. Она позволяет получить объект модуля позже только со ссылкой на определение модуля.
Данные функции не будут работать с модулями, созданными с использованием многофазной инициализации, поскольку несколько таких модулей могут быть созданы из одного определения.
-
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.