`module.md`

296 строк · 28.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.5/c-api/module.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты модулей89**[PyTypeObject](https://python-all.ru/3.5/c-api/type.html#c.PyTypeObject) `PyModule_Type`**1011Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.5/c-api/type.html#c.PyTypeObject) представляет тип Python-модуля. Он доступен программам Python как `types.ModuleType`.1213#### `int PyModule_Check(PyObject *p)`1415Возвращает истину, если *p* является объектом модуля или подтипом объекта модуля.1617#### `int PyModule_CheckExact(PyObject *p)`1819Возвращает истину, если *p* является объектом модуля, но не подтипом [`PyModule_Type`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_Type).2021#### `PyObject* PyModule_NewObject(PyObject *name)`2223Возвращает новый объект модуля с атрибутом [`__name__`](https://python-all.ru/3.5/reference/import.html#__name__), установленным в *name*. Атрибуты модуля [`__name__`](https://python-all.ru/3.5/reference/import.html#__name__), `__doc__`, [`__package__`](https://python-all.ru/3.5/reference/import.html#__package__) и [`__loader__`](https://python-all.ru/3.5/reference/import.html#__loader__) заполняются (все, кроме [`__name__`](https://python-all.ru/3.5/reference/import.html#__name__), устанавливаются в `None`); вызывающий отвечает за предоставление атрибута [`__file__`](https://python-all.ru/3.5/reference/import.html#__file__).2425Новое в версии 3.3.2627Изменено в версии 3.4: [`__package__`](https://python-all.ru/3.5/reference/import.html#__package__) и [`__loader__`](https://python-all.ru/3.5/reference/import.html#__loader__) устанавливаются в `None`.2829#### `PyObject* PyModule_New(const char *name)`3031*Возвращаемое значение: новая ссылка.*3233Аналогично [`PyModule_NewObject()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_NewObject), но имя – строка в кодировке UTF-8, а не объект Unicode.3435#### `PyObject* PyModule_GetDict(PyObject *module)`3637*Возвращаемое значение: заимствованная ссылка.*3839Возвращает объект словаря, реализующий пространство имён *module*; этот объект совпадает с атрибутом [`__dict__`](https://python-all.ru/3.5/library/stdtypes.html#object.__dict__) объекта модуля. Если *module* не является объектом модуля (или подтипом объекта модуля), возбуждается [`SystemError`](https://python-all.ru/3.5/library/exceptions.html#SystemError) и возвращается *NULL*.4041Расширениям рекомендуется использовать другие функции `PyModule_*()` и `PyObject_*()` вместо прямого манипулирования [`__dict__`](https://python-all.ru/3.5/library/stdtypes.html#object.__dict__) модуля.4243#### `PyObject* PyModule_GetNameObject(PyObject *module)`4445Возвращает значение [`__name__`](https://python-all.ru/3.5/reference/import.html#__name__) *module*. Если модуль не предоставляет такого значения или оно не является строкой, возбуждается [`SystemError`](https://python-all.ru/3.5/library/exceptions.html#SystemError) и возвращается *NULL*.4647Новое в версии 3.3.4849#### `char* PyModule_GetName(PyObject *module)`5051Аналогично [`PyModule_GetNameObject()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_GetNameObject), но возвращает имя, закодированное в `'utf-8'`.5253#### `void* PyModule_GetState(PyObject *module)`5455Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или *NULL*. См. [`PyModuleDef.m_size`](https://python-all.ru/3.5/c-api/module.html#c.PyModuleDef.m_size).5657#### `PyModuleDef* PyModule_GetDef(PyObject *module)`5859Возвращает указатель на структуру [`PyModuleDef`](https://python-all.ru/3.5/c-api/module.html#c.PyModuleDef), из которой был создан модуль, или *NULL*, если модуль не был создан из определения.6061#### `PyObject* PyModule_GetFilenameObject(PyObject *module)`6263Возвращает имя файла, из которого был загружен *module*, с использованием атрибута [`__file__`](https://python-all.ru/3.5/reference/import.html#__file__) *module*. Если атрибут не определён или не является строкой Unicode, возбуждается [`SystemError`](https://python-all.ru/3.5/library/exceptions.html#SystemError) и возвращается *NULL*; в противном случае возвращается ссылка на объект Unicode.6465Новое в версии 3.2.6667#### `char* PyModule_GetFilename(PyObject *module)`6869Аналогично [`PyModule_GetFilenameObject()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_GetFilenameObject), но возвращает имя файла, закодированное в 'utf-8'.7071Устарело с версии 3.2: [`PyModule_GetFilename()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_GetFilename) возбуждает `UnicodeEncodeError` для некодируемых имён файлов; вместо него используйте [`PyModule_GetFilenameObject()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_GetFilenameObject).7273## Инициализация C-модулей7475Объекты модулей обычно создаются из модулей расширения (общих библиотек,\\nкоторые экспортируют функцию инициализации) или из встраиваемых модулей\\n(где функция инициализации добавляется с помощью [`PyImport_AppendInittab()`](https://python-all.ru/3.5/c-api/import.html#c.PyImport_AppendInittab)).\\nПодробнее см. [Building C and C++ Extensions](https://python-all.ru/3.5/extending/building.html#building) или [Extending Embedded Python](https://python-all.ru/3.5/extending/embedding.html#extending-with-embedding).7677Функция инициализации может либо передать экземпляр определения модуля\\nв [`PyModule_Create()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_Create) и вернуть результирующий объект модуля,\\nлибо запросить «многофазную инициализацию», вернув саму структуру определения.7879**`PyModuleDef`**8081Структура определения модуля, содержащая всю информацию, необходимую для создания\\nобъекта модуля. Обычно для каждого модуля существует только одна статически\\nинициализированная переменная этого типа.8283**PyModuleDef\_Base `m_base`**8485Всегда инициализируйте этот элемент значением `PyModuleDef_HEAD_INIT`.8687**char\* `m_name`**8889Имя нового модуля.9091**char\* `m_doc`**9293Докстринг для модуля; обычно используется переменная докстринга, созданная с помощью `PyDoc_STRVAR()`.9495**Py\_ssize\_t `m_size`**9697Состояние модуля может храниться в выделенной под каждый модуль области памяти, доступ к которой можно получить через [`PyModule_GetState()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_GetState), а не в статических глобальных переменных. Это делает модули безопасными для использования в нескольких под-интерпретаторах.9899Эта область памяти выделяется на основе *m\_size* при создании модуля и освобождается при удалении объекта модуля, после вызова функции `m_free` (если она присутствует).100101Установка `m_size` в `-1` означает, что модуль не поддерживает\\nпод-интерпретаторы, так как имеет глобальное состояние.102103Установка в неотрицательное значение означает, что модуль можно\\nпереинициализировать, и указывает дополнительный объём памяти, необходимый\\nдля его состояния. Неотрицательное значение `m_size` требуется для многофазной\\nинициализации.104105Подробнее см. [**PEP 3121**](https://python-all.ru/3.5/c-api/module.html).106107**[PyMethodDef](https://python-all.ru/3.5/c-api/structures.html#c.PyMethodDef)\* `m_methods`**108109Указатель на таблицу функций уровня модуля, описываемую значениями [`PyMethodDef`](https://python-all.ru/3.5/c-api/structures.html#c.PyMethodDef). Может быть *NULL*, если функции отсутствуют.110111**[PyModuleDef\_Slot](https://python-all.ru/3.5/c-api/module.html#c.PyModuleDef_Slot)\* `m_slots`**112113Массив определений слотов для многофазной инициализации, завершающийся записью `{0, NULL}`. При использовании однофазной инициализации *m\_slots* должно быть *NULL*.114115Изменено в версии 3.5: До версии 3.5 этот элемент всегда устанавливался в *NULL* и определялся как:116117> **[inquiry](https://python-all.ru/3.5/c-api/gcsupport.html#c.inquiry) `m_reload`**118119**[traverseproc](https://python-all.ru/3.5/c-api/gcsupport.html#c.traverseproc) `m_traverse`**120121Функция обхода, вызываемая во время GC-обхода объекта модуля, или *NULL*, если не требуется.122123**[inquiry](https://python-all.ru/3.5/c-api/gcsupport.html#c.inquiry) `m_clear`**124125Функция очистки, вызываемая во время GC-очистки объекта модуля, или *NULL*, если не требуется.126127**freefunc `m_free`**128129Функция, вызываемая при освобождении объекта модуля, или *NULL*, если не требуется.130131### Однофазная инициализация132133Функция инициализации модуля может напрямую создать и вернуть объект модуля. Это называется «однофазной инициализацией» и использует одну из двух следующих функций создания модуля:134135#### `PyObject* PyModule_Create(PyModuleDef *def)`136137Создаёт новый объект модуля на основе определения в *def*. Ведёт себя как [`PyModule_Create2()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_Create2), когда *module\_api\_version* установлен в `PYTHON_API_VERSION`.138139#### `PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)`140141Создаёт новый объект модуля на основе определения в *def*, предполагая версию API *module\_api\_version*. Если эта версия не совпадает с версией работающего интерпретатора, генерируется [`RuntimeWarning`](https://python-all.ru/3.5/library/exceptions.html#RuntimeWarning).142143> **Примечание**144>145> В большинстве случаев вместо этой функции следует использовать [`PyModule_Create()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_Create); используйте её, только если точно уверены, что она нужна.146147Перед возвратом из функции инициализации полученный объект модуля обычно заполняется с помощью таких функций, как [`PyModule_AddObject()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_AddObject).148149### Многофазная инициализация150151Альтернативный способ задания расширений – запросить «многофазную инициализацию». Модули расширения, созданные таким образом, ведут себя больше как модули Python: инициализация разделяется на *фазу создания*, когда создаётся объект модуля, и *фазу выполнения*, когда он заполняется. Это различие похоже на методы [`__new__()`](https://python-all.ru/3.5/reference/datamodel.html#object.__new__) и [`__init__()`](https://python-all.ru/3.5/reference/datamodel.html#object.__init__) классов.152153В отличие от модулей, созданных с помощью однофазной инициализации, эти модули не являются синглтонами: если запись *sys.modules* удалена и модуль импортирован заново, создаётся новый объект модуля, а старый модуль подлежит обычной сборке мусора – как и модули Python. По умолчанию несколько модулей, созданных из одного определения, должны быть независимы: изменения в одном не должны влиять на другие. Это означает, что всё состояние должно быть привязано к объекту модуля (например, с помощью [`PyModule_GetState()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_GetState)) или к его содержимому (например, `__dict__` модуля или отдельные классы, созданные с помощью [`PyType_FromSpec()`](https://python-all.ru/3.5/c-api/type.html#c.PyType_FromSpec)).154155Все модули, созданные с помощью многофазной инициализации, должны поддерживать [суб-интерпретаторы](https://python-all.ru/3.5/c-api/init.html#sub-interpreter-support). Обычно достаточно обеспечить независимость нескольких модулей, чтобы достичь этого.156157Чтобы запросить многофазную инициализацию, функция инициализации (PyInit\_modulename) возвращает экземпляр [`PyModuleDef`](https://python-all.ru/3.5/c-api/module.html#c.PyModuleDef) с непустым [`m_slots`](https://python-all.ru/3.5/c-api/module.html#c.PyModuleDef.m_slots). Перед возвратом экземпляр `PyModuleDef` должен быть инициализирован следующей функцией:158159#### `PyObject* PyModuleDef_Init(PyModuleDef *def)`160161Гарантирует, что определение модуля является правильно инициализированным объектом Python, который корректно сообщает свой тип и счётчик ссылок.162163Возвращает *def*, приведённый к `PyObject*`, или *NULL* в случае ошибки.164165Новое в версии 3.5.166167Член *m\_slots* определения модуля должен указывать на массив структур `PyModuleDef_Slot`:168169**`PyModuleDef_Slot`**170171**int `slot`**172173Идентификатор слота, выбираемый из доступных значений, описанных ниже.174175**void\* `value`**176177Значение слота, смысл которого зависит от идентификатора слота.178179Новое в версии 3.5.180181Массив *m\_slots* должен завершаться слотом с id 0.182183Доступны следующие типы слотов:184185**`Py_mod_create`**186187Задаёт функцию, которая вызывается для создания самого объекта модуля. Указатель *value* этого слота должен указывать на функцию со следующей сигнатурой:188189#### `PyObject* create_module(PyObject *spec, PyModuleDef *def)`190191Функция получает экземпляр [`ModuleSpec`](https://python-all.ru/3.5/library/importlib.html#importlib.machinery.ModuleSpec), как определено в [**PEP 451**](https://python-all.ru/3.5/c-api/module.html), и определение модуля. Она должна возвращать новый объект модуля или установить ошибку и вернуть *NULL*.192193Эта функция должна быть минимальной. В частности, она не должна вызывать произвольный код Python, так как повторная попытка импорта того же модуля может привести к бесконечному циклу.194195В одном определении модуля нельзя задавать несколько слотов `Py_mod_create`.196197Если `Py_mod_create` не указан, механизм импорта создаст обычный объект модуля с помощью [`PyModule_New()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_New). Имя берётся из *spec*, а не из определения, чтобы расширения могли динамически подстраиваться под своё место в иерархии модулей и импортироваться под другими именами через симлинки, оставаясь привязанными к одному определению модуля.198199Не требуется, чтобы возвращаемый объект был экземпляром [`PyModule_Type`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_Type). Можно использовать любой тип, поддерживающий установку и получение атрибутов, связанных с импортом. Однако только экземпляры `PyModule_Type` могут быть возвращены, если `PyModuleDef` имеет не-*NULL* `m_traverse`, `m_clear`, `m_free`; ненулевое `m_size`; или слоты, отличные от `Py_mod_create`.200201**`Py_mod_exec`**202203Задаёт функцию, которая вызывается для *выполнения* модуля. Это эквивалентно выполнению кода модуля Python: обычно эта функция добавляет в модуль классы и константы. Сигнатура функции такова:204205#### `int exec_module(PyObject* module)`206207Если указано несколько слотов `Py_mod_exec`, они обрабатываются в том порядке, в котором расположены в массиве *m\_slots*.208209См. [**PEP 489**](https://python-all.ru/3.5/c-api/module.html) для более подробной информации о многофазной инициализации.210211### Низкоуровневые функции создания модулей212213Следующие функции вызываются «под капотом» при использовании многофазной инициализации. Их можно использовать напрямую, например, при динамическом создании объектов модуля. Обратите внимание, что для полной инициализации модуля необходимо вызвать как `PyModule_FromDefAndSpec`, так и `PyModule_ExecDef`.214215#### `PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)`216217Создаёт новый объект модуля на основе определения *module* и спецификации модуля *spec*. Работает как [`PyModule_FromDefAndSpec2()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_FromDefAndSpec2) с *module\_api\_version*, установленным в `PYTHON_API_VERSION`.218219Новое в версии 3.5.220221#### `PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)`222223Создаёт новый объект модуля на основе определения *module* и спецификации модуля *spec*, предполагая версию API *module\_api\_version*. Если эта версия не совпадает с версией выполняющегося интерпретатора, выдаётся [`RuntimeWarning`](https://python-all.ru/3.5/library/exceptions.html#RuntimeWarning).224225> **Примечание**226>227> В большинстве случаев вместо этой функции следует использовать [`PyModule_FromDefAndSpec()`](https://python-all.ru/3.5/c-api/module.html#c.PyModule_FromDefAndSpec); используйте её, только если точно уверены, что она нужна.228229Новое в версии 3.5.230231#### `int PyModule_ExecDef(PyObject *module, PyModuleDef *def)`232233Обрабатывает любые слоты выполнения ([`Py_mod_exec`](https://python-all.ru/3.5/c-api/module.html#c.Py_mod_exec)), заданные в *def*.234235Новое в версии 3.5.236237#### `int PyModule_SetDocString(PyObject *module, const char *docstring)`238239Устанавливает docstring для *module* равным *docstring*. Эта функция вызывается автоматически при создании модуля из `PyModuleDef` с помощью `PyModule_Create` или `PyModule_FromDefAndSpec`.240241Новое в версии 3.5.242243#### `int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)`244245Добавляет функции из массива *functions*, завершающегося *NULL*, в *module*. Обратитесь к документации [`PyMethodDef`](https://python-all.ru/3.5/c-api/structures.html#c.PyMethodDef) за подробностями об отдельных записях (из-за отсутствия общего пространства имён модуля «функции» уровня модуля, реализованные на C, обычно получают модуль в качестве первого параметра, что делает их похожими на методы экземпляра классов Python). Эта функция вызывается автоматически при создании модуля из `PyModuleDef` с использованием `PyModule_Create` или `PyModule_FromDefAndSpec`.246247Новое в версии 3.5.248249### Вспомогательные функции250251Функция инициализации модуля (при однофазной инициализации) или функция, вызываемая из слота выполнения модуля (при многофазной инициализации), могут использовать следующие функции для инициализации состояния модуля:252253#### `int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)`254255Добавляет объект в *module* под именем *name*. Это удобная функция, которую можно использовать в функции инициализации модуля. Она похищает ссылку на *value*. Возвращает `-1` при ошибке, `0` при успехе.256257#### `int PyModule_AddIntConstant(PyObject *module, const char *name, long value)`258259Добавляет целочисленную константу в модуль *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Возвращает `-1` в случае ошибки, `0` при успешном выполнении.260261#### `int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)`262263Добавляет строковую константу в *модуль* под именем *имя*. Эту удобную функцию можно использовать из функции инициализации модуля. Строка *значение* должна быть нуль-терминированной (*NULL*). Возвращает `-1` при ошибке, `0` при успехе.264265#### `int PyModule_AddIntMacro(PyObject *module, macro)`266267Добавляет целочисленную константу в модуль *module*. Имя и значение берутся из *macro*. Например, `PyModule_AddIntMacro(module, AF_INET)` добавляет целочисленную константу *AF\_INET* со значением *AF\_INET* в модуль *module*. Возвращает `-1` в случае ошибки, `0` при успешном выполнении.268269#### `int PyModule_AddStringMacro(PyObject *module, macro)`270271Добавляет строковую константу в *module*.272273## Поиск модуля274275Однофазная инициализация создаёт модули-одиночки, которые можно найти в контексте текущего интерпретатора. Это позволяет впоследствии получить объект модуля, имея только ссылку на определение модуля.276277Эти функции не будут работать с модулями, созданными с помощью многофазной инициализации, поскольку из одного определения можно создать несколько таких модулей.278279#### `PyObject* PyState_FindModule(PyModuleDef *def)`280281Возвращает объект модуля, созданный из *def* для текущего интерпретатора. Этот метод требует, чтобы объект модуля был предварительно присоединён к состоянию интерпретатора с помощью [`PyState_AddModule()`](https://python-all.ru/3.5/c-api/module.html#c.PyState_AddModule). Если соответствующий объект модуля не найден или ещё не присоединён к состоянию интерпретатора, возвращается *NULL*.282283#### `int PyState_AddModule(PyObject *module, PyModuleDef *def)`284285Прикрепляет объект модуля, переданный функции, к состоянию интерпретатора. Это позволяет обращаться к объекту модуля через [`PyState_FindModule()`](https://python-all.ru/3.5/c-api/module.html#c.PyState_FindModule).286287Действует только на модули, созданные с помощью однофазной инициализации.288289Новое в версии 3.3.290291#### `int PyState_RemoveModule(PyModuleDef *def)`292293Удаляет объект модуля, созданный из *def*, из состояния интерпретатора.294295Новое в версии 3.3.296