`module.md`

516 строк · 43.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.12/c-api/module.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты модулей89#### `PyTypeObject PyModule_Type`1011*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*1213Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.12/c-api/type.html#c.PyTypeObject) представляет тип Python-модуля. Он доступен программам Python как `types.ModuleType`.1415#### `int PyModule_Check(PyObject *p)`1617Возвращает истину, если *p* – объект модуля или подтип объекта модуля. Эта функция всегда выполняется успешно.1819#### `int PyModule_CheckExact(PyObject *p)`2021Возвращает истину, если *p* – объект модуля, но не подтип [`PyModule_Type`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_Type). Эта функция всегда выполняется успешно.2223#### `PyObject *PyModule_NewObject(PyObject *name)`2425*Возвращаемое значение: новая ссылка.*2627*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*2829Возвращает новый объект модуля с [`module.__name__`](https://python-all.ru/3.12/reference/datamodel.html#module.__name__), установленным в *name*. Атрибуты модуля `__name__`, [`__doc__`](https://python-all.ru/3.12/reference/datamodel.html#module.__doc__), [`__package__`](https://python-all.ru/3.12/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3.12/reference/datamodel.html#module.__loader__) заполняются (все, кроме `__name__`, устанавливаются в `None`). Вызывающий отвечает за установку атрибута [`__file__`](https://python-all.ru/3.12/reference/datamodel.html#module.__file__).3031Возвращает `NULL` с установленным исключением в случае ошибки.3233Добавлено в версии 3.3.3435Изменено в версии 3.4: [`__package__`](https://python-all.ru/3.12/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3.12/reference/datamodel.html#module.__loader__) теперь устанавливаются в `None`.3637#### `PyObject *PyModule_New(const char *name)`3839*Возвращаемое значение: новая ссылка.*4041*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*4243Аналогично [`PyModule_NewObject()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_NewObject), но имя – строка в кодировке UTF-8, а не объект Unicode.4445#### `PyObject *PyModule_GetDict(PyObject *module)`4647*Возвращаемое значение: заимствованная ссылка.*4849*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*5051Возвращает объект словаря, реализующий пространство имён *module*; этот объект совпадает с атрибутом [`__dict__`](https://python-all.ru/3.12/reference/datamodel.html#object.__dict__) объекта модуля. Если *module* не является объектом модуля (или подтипом объекта модуля), возбуждается [`SystemError`](https://python-all.ru/3.12/library/exceptions.html#SystemError) и возвращается `NULL`.5253Расширениям рекомендуется использовать другие функции `PyModule_*` и `PyObject_*` вместо прямого манипулирования [`__dict__`](https://python-all.ru/3.12/reference/datamodel.html#object.__dict__) модуля.5455#### `PyObject *PyModule_GetNameObject(PyObject *module)`5657*Возвращаемое значение: новая ссылка.*5859*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*6061Возвращает значение [`__name__`](https://python-all.ru/3.12/reference/datamodel.html#module.__name__) для *module*. Если модуль не предоставляет такого значения или оно не является строкой, возбуждается [`SystemError`](https://python-all.ru/3.12/library/exceptions.html#SystemError) и возвращается `NULL`.6263Добавлено в версии 3.3.6465#### `const char *PyModule_GetName(PyObject *module)`6667*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*6869Аналогично [`PyModule_GetNameObject()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_GetNameObject), но возвращает имя, закодированное в `'utf-8'`.7071#### `void *PyModule_GetState(PyObject *module)`7273*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*7475Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или `NULL`. См. [`PyModuleDef.m_size`](https://python-all.ru/3.12/c-api/module.html#c.PyModuleDef.m_size).7677#### `PyModuleDef *PyModule_GetDef(PyObject *module)`7879*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*8081Возвращает указатель на структуру [`PyModuleDef`](https://python-all.ru/3.12/c-api/module.html#c.PyModuleDef), из которой был создан модуль, или `NULL`, если модуль не был создан из определения.8283#### `PyObject *PyModule_GetFilenameObject(PyObject *module)`8485*Возвращаемое значение: новая ссылка.*8687*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*8889Возвращает имя файла, из которого был загружен *module*, используя атрибут [`__file__`](https://python-all.ru/3.12/reference/datamodel.html#module.__file__) модуля *module*. Если он не определён или не является строкой, возбуждает [`SystemError`](https://python-all.ru/3.12/library/exceptions.html#SystemError) и возвращает `NULL`; в противном случае возвращает ссылку на объект Unicode.9091Добавлено в версии 3.2.9293#### `const char *PyModule_GetFilename(PyObject *module)`9495*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*9697Аналогично [`PyModule_GetFilenameObject()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_GetFilenameObject), но возвращает имя файла, закодированное в 'utf-8'.9899Устарело с версии 3.2: [`PyModule_GetFilename()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_GetFilename) возбуждает [`UnicodeEncodeError`](https://python-all.ru/3.12/library/exceptions.html#UnicodeEncodeError) для некодируемых имён файлов; вместо него используйте [`PyModule_GetFilenameObject()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_GetFilenameObject).100101## Инициализация C-модулей102103Объекты модулей обычно создаются из модулей расширения (общих библиотек,\\nкоторые экспортируют функцию инициализации) или из встраиваемых модулей\\n(где функция инициализации добавляется с помощью [`PyImport_AppendInittab()`](https://python-all.ru/3.12/c-api/import.html#c.PyImport_AppendInittab)).\\nПодробнее см. [Building C and C++ Extensions](https://python-all.ru/3.12/extending/building.html#building) или [Extending Embedded Python](https://python-all.ru/3.12/extending/embedding.html#extending-with-embedding).104105Функция инициализации может либо передать экземпляр определения модуля\\nв [`PyModule_Create()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_Create) и вернуть результирующий объект модуля,\\nлибо запросить «многофазную инициализацию», вернув саму структуру определения.106107#### `type PyModuleDef`108109*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) (включая все члены).*110111Структура определения модуля, содержащая всю информацию, необходимую для создания\\nобъекта модуля. Обычно для каждого модуля существует только одна статически\\nинициализированная переменная этого типа.112113#### `PyModuleDef_Base m_base`114115Всегда инициализируйте этот элемент значением `PyModuleDef_HEAD_INIT`.116117#### `const char *m_name`118119Имя нового модуля.120121#### `const char *m_doc`122123Докстринг для модуля; обычно используется переменная докстринга, созданная с помощью [`PyDoc_STRVAR`](https://python-all.ru/3.12/c-api/intro.html#c.PyDoc_STRVAR).124125#### `Py_ssize_t m_size`126127Состояние модуля может храниться в выделенной под каждый модуль области памяти, доступ к которой можно получить через [`PyModule_GetState()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_GetState), а не в статических глобальных переменных. Это делает модули безопасными для использования в нескольких под-интерпретаторах.128129Эта область памяти выделяется на основе *m\_size* при создании модуля и освобождается при удалении объекта модуля, после вызова функции [`m_free`](https://python-all.ru/3.12/c-api/module.html#c.PyModuleDef.m_free) (если она присутствует).130131Установка `m_size` в `-1` означает, что модуль не поддерживает\\nпод-интерпретаторы, так как имеет глобальное состояние.132133Установка в неотрицательное значение означает, что модуль можно\\nпереинициализировать, и указывает дополнительный объём памяти, необходимый\\nдля его состояния. Неотрицательное значение `m_size` требуется для многофазной\\nинициализации.134135Подробнее см. [**PEP 3121**](https://python-all.ru/3.12/c-api/module.html).136137#### `PyMethodDef *m_methods`138139Указатель на таблицу функций уровня модуля, описываемых значениями [`PyMethodDef`](https://python-all.ru/3.12/c-api/structures.html#c.PyMethodDef). Может быть `NULL`, если функции отсутствуют.140141#### `PyModuleDef_Slot *m_slots`142143Массив определений слотов для многофазной инициализации, завершающийся\\nзаписью `{0, NULL}`.\\nПри использовании однофазной инициализации *m\_slots* должен быть `NULL`.144145Изменено в версии 3.5: До версии 3.5 этот элемент всегда устанавливался в `NULL`, и определялся как:146147> #### `inquiry m_reload`148149#### `traverseproc m_traverse`150151Функция обхода, вызываемая при GC-обходе объекта модуля, или `NULL`, если она не нужна.152153Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.12/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3.12/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_GetState)) равно `NULL`.154155Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.156157#### `inquiry m_clear`158159Функция очистки, вызываемая при GC-очистке объекта модуля, или `NULL`, если она не нужна.160161Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.12/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3.12/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_GetState)) равно `NULL`.162163Как и [`PyTypeObject.tp_clear`](https://python-all.ru/3.12/c-api/typeobj.html#c.PyTypeObject.tp_clear), эта функция вызывается не *всегда* перед освобождением модуля. Например, когда подсчёта ссылок достаточно, чтобы определить, что объект больше не используется, циклический сборщик мусора не задействуется, и [`m_free`](https://python-all.ru/3.12/c-api/module.html#c.PyModuleDef.m_free) вызывается напрямую.164165Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.166167#### `freefunc m_free`168169Функция, вызываемая при освобождении объекта модуля, или `NULL`, если она не нужна.170171Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.12/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3.12/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_GetState)) равно `NULL`.172173Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.174175### Однофазная инициализация176177Функция инициализации модуля может напрямую создать и вернуть объект модуля. Это называется «однофазной инициализацией» и использует одну из двух следующих функций создания модуля:178179#### `PyObject *PyModule_Create(PyModuleDef *def)`180181*Возвращаемое значение: новая ссылка.*182183Создаёт новый объект модуля на основе определения в *def*. Ведёт себя как [`PyModule_Create2()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_Create2), когда *module\_api\_version* установлен в `PYTHON_API_VERSION`.184185#### `PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)`186187*Возвращаемое значение: новая ссылка.*188189*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*190191Создаёт новый объект модуля на основе определения в *def*, предполагая версию API *module\_api\_version*. Если эта версия не совпадает с версией работающего интерпретатора, генерируется [`RuntimeWarning`](https://python-all.ru/3.12/library/exceptions.html#RuntimeWarning).192193Возвращает `NULL` с установленным исключением в случае ошибки.194195> **Примечание**196>197> В большинстве случаев вместо этой функции следует использовать [`PyModule_Create()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_Create); используйте её, только если точно уверены, что она нужна.198199Перед возвратом из функции инициализации полученный объект модуля обычно заполняется с помощью таких функций, как [`PyModule_AddObjectRef()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_AddObjectRef).200201### Многофазная инициализация202203Альтернативный способ задания расширений – запросить «многофазную инициализацию». Модули расширения, созданные таким образом, ведут себя больше как модули Python: инициализация разделяется на *фазу создания*, когда создаётся объект модуля, и *фазу выполнения*, когда он заполняется. Это различие похоже на методы `__new__()` и `__init__()` классов.204205В отличие от модулей, созданных с помощью однофазной инициализации, эти модули не являются синглтонами: если запись *sys.modules* удалена и модуль импортирован заново, создаётся новый объект модуля, а старый модуль подлежит обычной сборке мусора – как и модули Python. По умолчанию несколько модулей, созданных из одного определения, должны быть независимы: изменения в одном не должны влиять на другие. Это означает, что всё состояние должно быть привязано к объекту модуля (например, с помощью [`PyModule_GetState()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_GetState)) или к его содержимому (например, [`__dict__`](https://python-all.ru/3.12/reference/datamodel.html#object.__dict__) модуля или отдельные классы, созданные с помощью [`PyType_FromSpec()`](https://python-all.ru/3.12/c-api/type.html#c.PyType_FromSpec)).206207Все модули, созданные с помощью многофазной инициализации, должны поддерживать [суб-интерпретаторы](https://python-all.ru/3.12/c-api/init.html#sub-interpreter-support). Обычно достаточно обеспечить независимость нескольких модулей, чтобы достичь этого.208209Чтобы запросить многофазную инициализацию, функция инициализации (PyInit\_modulename) возвращает экземпляр [`PyModuleDef`](https://python-all.ru/3.12/c-api/module.html#c.PyModuleDef) с непустым [`m_slots`](https://python-all.ru/3.12/c-api/module.html#c.PyModuleDef.m_slots). Перед возвратом экземпляр `PyModuleDef` должен быть инициализирован следующей функцией:210211#### `PyObject *PyModuleDef_Init(PyModuleDef *def)`212213*Возвращаемое значение: Borrowed reference.*214215*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.5.*216217Гарантирует, что определение модуля является правильно инициализированным объектом Python, который корректно сообщает свой тип и счётчик ссылок.218219Возвращает *def*, приведённый к `PyObject*`, или `NULL`, если произошла ошибка.220221Добавлено в версии 3.5.222223Член *m\_slots* определения модуля должен указывать на массив структур `PyModuleDef_Slot`:224225#### `type PyModuleDef_Slot`226227#### `int slot`228229Идентификатор слота, выбираемый из доступных значений, описанных ниже.230231#### `void *value`232233Значение слота, смысл которого зависит от идентификатора слота.234235Добавлено в версии 3.5.236237Массив *m\_slots* должен завершаться слотом с id 0.238239Доступны следующие типы слотов:240241#### `Py_mod_create`242243Задаёт функцию, которая вызывается для создания самого объекта модуля. Указатель *value* этого слота должен указывать на функцию со следующей сигнатурой:244245#### `PyObject *create_module(PyObject *spec, PyModuleDef *def)`246247Функция получает экземпляр [`ModuleSpec`](https://python-all.ru/3.12/library/importlib.html#importlib.machinery.ModuleSpec), как определено в [**PEP 451**](https://python-all.ru/3.12/c-api/module.html), и определение модуля. Она должна вернуть новый объект модуля или установить ошибку и вернуть `NULL`.248249Эта функция должна быть минимальной. В частности, она не должна вызывать произвольный код Python, так как повторная попытка импорта того же модуля может привести к бесконечному циклу.250251В одном определении модуля нельзя задавать несколько слотов `Py_mod_create`.252253Если `Py_mod_create` не указан, механизм импорта создаст обычный объект модуля с помощью [`PyModule_New()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_New). Имя берётся из *spec*, а не из определения, чтобы расширения могли динамически подстраиваться под своё место в иерархии модулей и импортироваться под другими именами через симлинки, оставаясь привязанными к одному определению модуля.254255Возвращаемый объект не обязан быть экземпляром [`PyModule_Type`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_Type). Можно использовать любой тип, если он поддерживает установку и получение атрибутов, связанных с импортом. Однако только экземпляры `PyModule_Type` могут быть возвращены, если `PyModuleDef` содержит ненулевые `NULL` `m_traverse`, `m_clear`, `m_free`; ненулевой `m_size`; или слоты, отличные от `Py_mod_create`.256257#### `Py_mod_exec`258259Задаёт функцию, которая вызывается для *выполнения* модуля. Это эквивалентно выполнению кода модуля Python: обычно эта функция добавляет в модуль классы и константы. Сигнатура функции такова:260261#### `int exec_module(PyObject *module)`262263Если указано несколько слотов `Py_mod_exec`, они обрабатываются в том порядке, в котором расположены в массиве *m\_slots*.264265#### `Py_mod_multiple_interpreters`266267Задаёт одно из следующих значений:268269#### `Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`270271Модуль не поддерживает импорт в подынтерпретаторах.272273#### `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`274275Модуль поддерживает импорт в подынтерпретаторах, но только если они используют общий GIL основного интерпретатора. (См. [Изоляция модулей расширения](https://python-all.ru/3.12/howto/isolating-extensions.html#isolating-extensions-howto).)276277#### `Py_MOD_PER_INTERPRETER_GIL_SUPPORTED`278279Модуль поддерживает импорт в подынтерпретаторах, даже если у них собственный GIL. (См. [Изоляция модулей расширения](https://python-all.ru/3.12/howto/isolating-extensions.html#isolating-extensions-howto).)280281Этот слот определяет, будет ли импорт этого модуля в подынтерпретаторе завершаться ошибкой.282283В одном определении модуля нельзя указывать несколько слотов `Py_mod_multiple_interpreters`.284285Если `Py_mod_multiple_interpreters` не указан, механизм импорта по умолчанию использует `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`.286287Добавлено в версии 3.12.288289См. [**PEP 489**](https://python-all.ru/3.12/c-api/module.html) для более подробной информации о многофазной инициализации.290291### Низкоуровневые функции создания модулей292293Следующие функции вызываются «под капотом» при использовании многофазной инициализации. Их можно использовать напрямую, например, при динамическом создании объектов модуля. Обратите внимание, что для полной инициализации модуля необходимо вызвать как `PyModule_FromDefAndSpec`, так и `PyModule_ExecDef`.294295#### `PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)`296297*Возвращаемое значение: новая ссылка.*298299Создаёт новый объект модуля по определению *def* и *spec* (ModuleSpec). Работает так же, как [`PyModule_FromDefAndSpec2()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_FromDefAndSpec2), с *module\_api\_version*, установленным в `PYTHON_API_VERSION`.300301Добавлено в версии 3.5.302303#### `PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)`304305*Возвращаемое значение: новая ссылка.*306307*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*308309Создает новый объект модуля по определению из *def* и ModuleSpec *spec*, используя версию API *module\_api\_version*. Если эта версия не соответствует версии работающего интерпретатора, выдается [`RuntimeWarning`](https://python-all.ru/3.12/library/exceptions.html#RuntimeWarning).310311Возвращает `NULL` с установленным исключением в случае ошибки.312313> **Примечание**314>315> В большинстве случаев вместо этой функции следует использовать [`PyModule_FromDefAndSpec()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_FromDefAndSpec); используйте её, только если точно уверены, что она нужна.316317Добавлено в версии 3.5.318319#### `int PyModule_ExecDef(PyObject *module, PyModuleDef *def)`320321*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*322323Обрабатывает любые слоты выполнения ([`Py_mod_exec`](https://python-all.ru/3.12/c-api/module.html#c.Py_mod_exec)), заданные в *def*.324325Добавлено в версии 3.5.326327#### `int PyModule_SetDocString(PyObject *module, const char *docstring)`328329*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*330331Устанавливает docstring для *module* равным *docstring*. Эта функция вызывается автоматически при создании модуля из `PyModuleDef` с помощью `PyModule_Create` или `PyModule_FromDefAndSpec`.332333Добавлено в версии 3.5.334335#### `int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)`336337*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.7.*338339Добавляет функции из массива *functions*, завершающегося `NULL`, в *module*. Подробнее об отдельных элементах см. документацию [`PyMethodDef`](https://python-all.ru/3.12/c-api/structures.html#c.PyMethodDef) (из-за отсутствия общего пространства имён модуля «функции» уровня модуля, реализованные на C, обычно получают сам модуль в качестве первого параметра, что делает их похожими на методы экземпляра классов Python). Эта функция вызывается автоматически при создании модуля из `PyModuleDef` с помощью `PyModule_Create` или `PyModule_FromDefAndSpec`.340341Добавлено в версии 3.5.342343### Вспомогательные функции344345Функция инициализации модуля (при однофазной инициализации) или функция, вызываемая из слота выполнения модуля (при многофазной инициализации), могут использовать следующие функции для инициализации состояния модуля:346347#### `int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)`348349*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.10.*350351Добавляет объект в *module* как *name*. Это удобная функция, которую можно использовать из функции инициализации модуля.352353При успехе возвращает `0`. При ошибке вызывает исключение и возвращает `-1`.354355Пример использования:356357```c358static int359add_spam(PyObject *module, int value)360{361    PyObject *obj = PyLong_FromLong(value);362    if (obj == NULL) {363        return -1;364    }365    int res = PyModule_AddObjectRef(module, "spam", obj);366    Py_DECREF(obj);367    return res;368 }369```370371Для удобства функция принимает `NULL` *value* с установленным исключением. В этом случае возвращает `-1` и просто оставляет вызванное исключение без изменений.372373Пример можно также написать без явной проверки, что *obj* равен `NULL`:374375```c376static int377add_spam(PyObject *module, int value)378{379    PyObject *obj = PyLong_FromLong(value);380    int res = PyModule_AddObjectRef(module, "spam", obj);381    Py_XDECREF(obj);382    return res;383 }384```385386Обратите внимание, что в этом случае следует использовать `Py_XDECREF()` вместо `Py_DECREF()`, поскольку *obj* может быть `NULL`.387388Количество различных строк *name*, передаваемых этой функции, должно быть небольшим – обычно используйте только статически выделенные строки в качестве *name*. Для имен, неизвестных во время компиляции, предпочтительнее вызывать [`PyUnicode_FromString()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_FromString) и [`PyObject_SetAttr()`](https://python-all.ru/3.12/c-api/object.html#c.PyObject_SetAttr) напрямую. Подробнее см. [`PyUnicode_InternFromString()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_InternFromString), который может использоваться внутри для создания объекта ключа.389390Добавлено в версии 3.10.391392#### `int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)`393394*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*395396Похоже на [`PyModule_AddObjectRef()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_AddObjectRef), но при успешном выполнении забирает ссылку на *value* (если возвращает `0`).397398Рекомендуется использовать новую функцию [`PyModule_AddObjectRef()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_AddObjectRef), так как при неправильном использовании функции [`PyModule_AddObject()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_AddObject) легко допустить утечку ссылок.399400> **Примечание**401>402> В отличие от других функций, крадущих ссылки, `PyModule_AddObject()` освобождает ссылку на *value* **только при успехе**.403>404> Это означает, что возвращаемое значение необходимо проверять, а код вызова должен вручную [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF) *value* при ошибке.405406Пример использования:407408```c409static int410add_spam(PyObject *module, int value)411{412    PyObject *obj = PyLong_FromLong(value);413    if (obj == NULL) {414        return -1;415    }416    if (PyModule_AddObject(module, "spam", obj) < 0) {417        Py_DECREF(obj);418        return -1;419    }420    // PyModule_AddObject() перехватил ссылку на obj:421    // Py_DECREF(obj) здесь не требуется422    return 0;423}424```425426Пример можно также написать без явной проверки, что *obj* равен `NULL`:427428```c429static int430add_spam(PyObject *module, int value)431{432    PyObject *obj = PyLong_FromLong(value);433    if (PyModule_AddObject(module, "spam", obj) < 0) {434        Py_XDECREF(obj);435        return -1;436    }437    // PyModule_AddObject() перехватил ссылку на obj:438    // Py_DECREF(obj) здесь не требуется439    return 0;440}441```442443Обратите внимание, что в этом случае следует использовать `Py_XDECREF()` вместо `Py_DECREF()`, поскольку *obj* может быть `NULL`.444445#### `int PyModule_AddIntConstant(PyObject *module, const char *name, long value)`446447*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*448449Добавляет целочисленную константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.450451Это удобная функция, которая вызывает [`PyLong_FromLong()`](https://python-all.ru/3.12/c-api/long.html#c.PyLong_FromLong) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.452453#### `int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)`454455*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*456457Добавляет строковую константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Строка *value* должна быть завершена символами `NULL`. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.458459Это удобная функция, которая вызывает [`PyUnicode_InternFromString()`](https://python-all.ru/3.12/c-api/unicode.html#c.PyUnicode_InternFromString) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.12/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.460461#### `PyModule_AddIntMacro(module, macro)`462463Добавляет целочисленную константу в *module*. Имя и значение берутся из *macro*. Например, `PyModule_AddIntMacro(module, AF_INET)` добавляет целочисленную константу *AF\_INET* со значением *AF\_INET* в *module*. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.464465#### `PyModule_AddStringMacro(module, macro)`466467Добавляет строковую константу в *module*.468469#### `int PyModule_AddType(PyObject *module, PyTypeObject *type)`470471*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.10.*472473Добавляет объект типа в *module*. Объект типа финализируется внутренним вызовом [`PyType_Ready()`](https://python-all.ru/3.12/c-api/type.html#c.PyType_Ready). Имя объекта типа берётся из последнего компонента [`tp_name`](https://python-all.ru/3.12/c-api/typeobj.html#c.PyTypeObject.tp_name) после точки. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.474475Добавлено в версии 3.9.476477## Поиск модуля478479Однофазная инициализация создаёт модули-одиночки, которые можно найти в контексте текущего интерпретатора. Это позволяет впоследствии получить объект модуля, имея только ссылку на определение модуля.480481Эти функции не будут работать с модулями, созданными с помощью многофазной инициализации, поскольку из одного определения можно создать несколько таких модулей.482483#### `PyObject *PyState_FindModule(PyModuleDef *def)`484485*Возвращаемое значение: заимствованная ссылка.*486487*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*488489Возвращает объект модуля, созданный из *def* для текущего интерпретатора. Этот метод требует, чтобы объект модуля был предварительно прикреплён к состоянию интерпретатора с помощью [`PyState_AddModule()`](https://python-all.ru/3.12/c-api/module.html#c.PyState_AddModule). Если соответствующий объект модуля не найден или ещё не прикреплён к состоянию интерпретатора, он возвращает `NULL`.490491#### `int PyState_AddModule(PyObject *module, PyModuleDef *def)`492493*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.3.*494495Прикрепляет объект модуля, переданный функции, к состоянию интерпретатора. Это позволяет обращаться к объекту модуля через [`PyState_FindModule()`](https://python-all.ru/3.12/c-api/module.html#c.PyState_FindModule).496497Действует только на модули, созданные с помощью однофазной инициализации.498499Python автоматически вызывает `PyState_AddModule` после импорта модуля, поэтому её вызов из кода инициализации модуля излишен (но безвреден). Явный вызов требуется только в том случае, если собственный код инициализации модуля впоследствии вызывает `PyState_FindModule`. Функция в основном предназначена для реализации альтернативных механизмов импорта (путём прямого вызова или обращения к её реализации для получения информации о требуемых обновлениях состояния).500501Вызывающий должен удерживать GIL.502503Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.504505Добавлено в версии 3.3.506507#### `int PyState_RemoveModule(PyModuleDef *def)`508509*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.3.*510511Удаляет объект модуля, созданный из *def*, из состояния интерпретатора. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.512513Вызывающий должен удерживать GIL.514515Добавлено в версии 3.3.516