`module.md`

855 строк · 74.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/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.16/c-api/stable.html#stable).*1213Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.16/c-api/type.html#c.PyTypeObject) представляет тип Python-модуля. Он доступен программам Python как [`types.ModuleType`](https://python-all.ru/3.16/library/types.html#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.16/c-api/module.html#c.PyModule_Type). Эта функция всегда выполняется успешно.2223#### `PyObject *PyModule_NewObject(PyObject *name)`2425*Возвращаемое значение: новая ссылка.*2627*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*2829Возвращает новый объект модуля с [`module.__name__`](https://python-all.ru/3.16/reference/datamodel.html#module.__name__), установленным в *name*. Атрибуты модуля `__name__`, [`__doc__`](https://python-all.ru/3.16/reference/datamodel.html#module.__doc__), [`__package__`](https://python-all.ru/3.16/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3.16/reference/datamodel.html#module.__loader__) заполняются (все, кроме `__name__`, устанавливаются в `None`). Вызывающий отвечает за установку атрибута [`__file__`](https://python-all.ru/3.16/reference/datamodel.html#module.__file__).3031В случае ошибки возвращает `NULL` с установленным исключением.3233Добавлено в версии 3.3.3435Изменено в версии 3.4: [`__package__`](https://python-all.ru/3.16/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3.16/reference/datamodel.html#module.__loader__) теперь устанавливаются в `None`.3637#### `PyObject *PyModule_New(const char *name)`3839*Возвращаемое значение: новая ссылка.*4041*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*4243Аналогично [`PyModule_NewObject()`](https://python-all.ru/3.16/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.16/c-api/stable.html#stable).*5051Возвращает объект словаря, реализующий пространство имён *module*; этот объект совпадает с атрибутом [`__dict__`](https://python-all.ru/3.16/reference/datamodel.html#object.__dict__) объекта модуля. Если *module* не является объектом модуля (или подтипом объекта модуля), возбуждается [`SystemError`](https://python-all.ru/3.16/library/exceptions.html#SystemError) и возвращается `NULL`.5253Расширениям рекомендуется использовать другие функции `PyModule_*` и `PyObject_*` вместо прямого манипулирования [`__dict__`](https://python-all.ru/3.16/reference/datamodel.html#object.__dict__) модуля.5455Возвращаемая ссылка является заимствованной из модуля; она действительна до тех пор, пока модуль не будет уничтожен.5657#### `PyObject *PyModule_GetNameObject(PyObject *module)`5859*Возвращаемое значение: новая ссылка.*6061*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*6263Возвращает значение [`__name__`](https://python-all.ru/3.16/reference/datamodel.html#module.__name__) для *module*. Если модуль не предоставляет такого значения или оно не является строкой, возбуждается [`SystemError`](https://python-all.ru/3.16/library/exceptions.html#SystemError) и возвращается `NULL`.6465Добавлено в версии 3.3.6667#### `const char *PyModule_GetName(PyObject *module)`6869*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*7071Аналогично [`PyModule_GetNameObject()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetNameObject), но возвращает имя, закодированное в `'utf-8'`.7273Возвращаемый буфер действителен только до тех пор, пока модуль не переименован или не уничтожен. Обратите внимание, что код Python может переименовать модуль, установив его атрибут [`__name__`](https://python-all.ru/3.16/reference/datamodel.html#module.__name__).7475#### `PyModuleDef *PyModule_GetDef(PyObject *module)`7677*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*7879Возвращает указатель на структуру [`PyModuleDef`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef), из которой был создан модуль, или `NULL`, если модуль не был создан из определения.8081В случае ошибки возвращает `NULL` с установленным исключением. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred), чтобы отличить этот случай от отсутствия `PyModuleDef`.8283#### `PyObject *PyModule_GetFilenameObject(PyObject *module)`8485*Возвращаемое значение: новая ссылка.*8687*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*8889Возвращает имя файла, из которого был загружен *module*, используя атрибут [`__file__`](https://python-all.ru/3.16/reference/datamodel.html#module.__file__) модуля *module*. Если он не определён или не является строкой, возбуждает [`SystemError`](https://python-all.ru/3.16/library/exceptions.html#SystemError) и возвращает `NULL`; в противном случае возвращает ссылку на объект Unicode.9091Добавлено в версии 3.2.9293#### `const char *PyModule_GetFilename(PyObject *module)`9495*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*9697Аналогично [`PyModule_GetFilenameObject()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetFilenameObject), но возвращает имя файла, закодированное в 'utf-8'.9899Возвращаемый буфер действителен только до тех пор, пока атрибут [`__file__`](https://python-all.ru/3.16/reference/datamodel.html#module.__file__) модуля не будет переназначен или модуль не будет уничтожен.100101Устарело с версии 3.2: [`PyModule_GetFilename()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetFilename) возбуждает [`UnicodeEncodeError`](https://python-all.ru/3.16/library/exceptions.html#UnicodeEncodeError) для некодируемых имён файлов; вместо него используйте [`PyModule_GetFilenameObject()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetFilenameObject).102103## Определение модуля104105Модули, создаваемые с помощью C API, обычно определяются массивом структур [`PySlot`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot), который предоставляет «описание» того, как следует создавать модуль. Подробнее о слотах см. [Слоты определения](https://python-all.ru/3.16/c-api/slots.html#capi-slots).106107Изменено в версии 3.15: Ранее для определения модулей требовалась структура [`PyModuleDef`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef). Старый способ определения модулей всё ещё доступен: обратитесь к разделу [Структура определения модуля](https://python-all.ru/3.16/c-api/module.html#pymoduledef) или к более ранним версиям этой документации, если вы планируете поддерживать более старые версии Python.108109Массив слотов обычно используется для определения «основного» объекта модуля расширения (подробнее см. [Определение модулей расширения](https://python-all.ru/3.16/c-api/extension-modules.html#extension-modules)). Он также может использоваться для [динамического создания модулей расширения](https://python-all.ru/3.16/c-api/module.html#module-from-slots).110111Если не указано иное, один и тот же идентификатор слота не может повторяться в массиве слотов.112113### Слоты метаданных114115#### `Py_mod_name`116117*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*118119[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) для имени нового модуля в виде NUL-терминированной строки в кодировке UTF-8 `const char *`.120121Обратите внимание, что модули обычно создаются с помощью [`ModuleSpec`](https://python-all.ru/3.16/library/importlib.html#importlib.machinery.ModuleSpec), и в этом случае имя из спецификации будет использоваться вместо `Py_mod_name`. Однако по-прежнему рекомендуется включать этот слот для интроспекции и отладки.122123Добавлено в версии 3.15: Используйте [`PyModuleDef.m_name`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_name) вместо этого для поддержки предыдущих версий.124125#### `Py_mod_doc`126127*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*128129[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) для строки документации нового модуля в виде NUL-терминированной строки в кодировке UTF-8 `const char *`.130131Обычно она устанавливается в переменную, созданную с помощью [`PyDoc_STRVAR`](https://python-all.ru/3.16/c-api/intro.html#c.PyDoc_STRVAR).132133Добавлено в версии 3.15: Используйте [`PyModuleDef.m_doc`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_doc) вместо этого для поддержки предыдущих версий.134135### Слоты возможностей136137#### `Py_mod_abi`138139*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*140141[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id), значение которого указывает на структуру [`PyABIInfo`](https://python-all.ru/3.16/c-api/stable.html#c.PyABIInfo), описывающую ABI, используемый модулем расширения.142143Подходящую переменную `PyABIInfo` можно определить с помощью макроса [`PyABIInfo_VAR`](https://python-all.ru/3.16/c-api/stable.html#c.PyABIInfo_VAR), например:144145```c146PyABIInfo_VAR(abi_info);147148static PySlot mymodule_slots[] = {149   PySlot_DATA(Py_mod_abi, &abi_info),150   ...151};152```153154При создании модуля Python проверяет значение этого слота с помощью [`PyABIInfo_Check()`](https://python-all.ru/3.16/c-api/stable.html#c.PyABIInfo_Check).155156Этот слот обязателен, за исключением модулей, созданных из [`PyModuleDef`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef).157158Добавлено в версии 3.15.159160#### `Py_mod_multiple_interpreters`161162*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.12.*163164[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id), значение которого – одно из:165166#### `Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`167168Модуль не поддерживает импорт в подынтерпретаторах.169170#### `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`171172Модуль поддерживает импорт в подынтерпретаторах, но только если они используют общий GIL основного интерпретатора. (См. [Изоляция модулей расширения](https://python-all.ru/3.16/howto/isolating-extensions.html#isolating-extensions-howto).)173174#### `Py_MOD_PER_INTERPRETER_GIL_SUPPORTED`175176Модуль поддерживает импорт в подынтерпретаторах, даже если у них собственный GIL. (См. [Изоляция модулей расширения](https://python-all.ru/3.16/howto/isolating-extensions.html#isolating-extensions-howto).)177178Этот слот определяет, будет ли импорт этого модуля в подынтерпретаторе завершаться ошибкой.179180Если `Py_mod_multiple_interpreters` не указан, механизм импорта по умолчанию использует `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`.181182По историческим причинам значения объявлены как указатели (`void *`). При использовании массивов [`PySlot`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot) используйте [`PySlot_DATA`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot_DATA) для `Py_mod_multiple_interpreters`:183184```c185PySlot_DATA(Py_mod_multiple_interpreters,186            Py_MOD_PER_INTERPRETER_GIL_SUPPORTED)187```188189Добавлено в версии 3.12.190191#### `Py_mod_gil`192193*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable), начиная с версии 3.13.*194195[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id), значение которого – одно из:196197#### `Py_MOD_GIL_USED`198199Модуль зависит от наличия глобальной блокировки интерпретатора (GIL), и может обращаться к глобальному состоянию без синхронизации.200201#### `Py_MOD_GIL_NOT_USED`202203Модуль можно безопасно использовать без активного GIL.204205Этот слот игнорируется сборками Python, не настроенными с [`--disable-gil`](https://python-all.ru/3.16/using/configure.html#cmdoption-disable-gil). В противном случае он определяет, приведёт ли импорт этого модуля к автоматическому включению GIL. Подробнее см. [Free-threaded CPython](https://python-all.ru/3.16/whatsnew/3.13.html#whatsnew313-free-threaded-cpython).206207Если `Py_mod_gil` не указан, механизм импорта по умолчанию использует `Py_MOD_GIL_USED`.208209По историческим причинам значения объявлены как указатели (`void *`). При использовании массивов [`PySlot`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot) используйте [`PySlot_DATA`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot_DATA) для `Py_mod_gil`:210211```c212PySlot_DATA(Py_mod_gil, Py_MOD_GIL_NOT_USED)213```214215Добавлено в версии 3.13.216217### Слоты создания и инициализации218219#### `Py_mod_create`220221*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.5.*222223[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) – для функции, создающей сам объект модуля. Функция должна иметь сигнатуру:224225#### `PyObject *create_module(PyObject *spec, PyModuleDef *def)`226227Функции будут переданы:228229- *spec*: объект, подобный `ModuleSpec`, то есть любые определённые для [`importlib.machinery.ModuleSpec`](https://python-all.ru/3.16/library/importlib.html#importlib.machinery.ModuleSpec) атрибуты имеют соответствующую семантику. Однако любой из атрибутов может отсутствовать.230- *def*: `NULL` или определение модуля, если модуль создан из него.231232Функция должна возвращать новый объект модуля или установить ошибку и вернуть `NULL`.233234Эта функция должна быть минимальной. В частности, она не должна вызывать произвольный код Python, так как повторная попытка импорта того же модуля может привести к бесконечному циклу.235236Если `Py_mod_create` не указан, механизм импорта создаст обычный объект модуля с помощью [`PyModule_New()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_New). Имя берётся из *spec*, а не из определения, чтобы расширения могли динамически подстраиваться под своё место в иерархии модулей и импортироваться под другими именами через симлинки, оставаясь привязанными к одному определению модуля.237238Возвращаемый объект не обязательно должен быть экземпляром [`PyModule_Type`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_Type). Однако некоторые слоты могут использоваться только с экземплярами `PyModule_Type`; в частности:239240- [`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec),241- [слоты состояния модуля](https://python-all.ru/3.16/c-api/module.html#ext-module-state-slots) (`Py_mod_state_*`),242- [`Py_mod_token`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_token).243244Добавлено в версии 3.5.245246Изменено в версии 3.15: Аргумент *слоты* может быть объектом, подобным `ModuleSpec`, а не настоящим экземпляром [`ModuleSpec`](https://python-all.ru/3.16/library/importlib.html#importlib.machinery.ModuleSpec). Обратите внимание: предыдущие версии CPython этого не требовали.247248Аргумент *def* теперь может быть `NULL`, так как модули не обязательно создаются из определений.249250#### `Py_mod_exec`251252*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.5.*253254[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) – для функции, которая будет *выполнять* (инициализировать) модуль. Эта функция выполняет то же, что и выполнение кода модуля Python: обычно она добавляет классы и константы в модуль. Сигнатура функции:255256#### `int exec_module(PyObject *module)`257258См. раздел [Вспомогательные функции](https://python-all.ru/3.16/c-api/module.html#capi-module-support-functions) с полезными функциями для вызова.259260Для обратной совместимости массив [`PyModuleDef.m_slots`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_slots) может содержать несколько слотов `Py_mod_exec`; они обрабатываются в порядке появления в массиве. В других местах (то есть в аргументах [`PyModule_FromSlotsAndSpec()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_FromSlotsAndSpec) и возвращаемых значениях `PyModExport_<name>`) повторение слота не допускается.261262Добавлено в версии 3.5.263264Изменено в версии 3.15: Повторяющиеся слоты `Py_mod_exec` запрещены, за исключением [`PyModuleDef.m_slots`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_slots).265266#### `Py_mod_methods`267268*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*269270[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) – для таблицы функций уровня модуля, как массив значений [`PyMethodDef`](https://python-all.ru/3.16/c-api/structures.html#c.PyMethodDef), подходящих в качестве аргумента *functions* для [`PyModule_AddFunctions()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_AddFunctions).271272Как и другие идентификаторы слотов, массив слотов может содержать только одну запись `Py_mod_methods`. Чтобы добавить функции из нескольких массивов [`PyMethodDef`](https://python-all.ru/3.16/c-api/structures.html#c.PyMethodDef), вызывайте [`PyModule_AddFunctions()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_AddFunctions) в функции [`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec).273274Таблица должна быть статически выделена (или иным образом гарантированно пережить объект модуля).275276Добавлено в версии 3.15: Используйте [`PyModuleDef.m_methods`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_methods) для поддержки предыдущих версий.277278## Состояние модуля279280Модули расширения могут иметь *состояние модуля* – фрагмент памяти, который выделяется при создании модуля и освобождается при удалении объекта модуля. Состояние модуля задаётся с помощью [специализированных слотов](https://python-all.ru/3.16/c-api/module.html#ext-module-state-slots).281282Типичное применение состояния модуля – хранение типа исключения или *любого* объекта типа, определённого модулем –283284В отличие от атрибутов модуля Python, код Python не может заменить или удалить данные, хранящиеся в состоянии модуля.285286Хранение информации о модуле в атрибутах и состоянии модуля, а не в статических глобальных переменных, делает объекты модулей *изолированными* и более безопасными для использования в нескольких под-интерпретаторах. Это также помогает Python выполнять упорядоченную очистку при завершении работы.287288Расширения, которые хранят ссылки на объекты Python как часть состояния модуля, должны реализовывать [`Py_mod_state_traverse`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_traverse) и [`Py_mod_state_clear`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_clear) функции, чтобы избежать утечек ссылок.289290Чтобы получить состояние из данного модуля, используйте следующие функции:291292#### `void *PyModule_GetState(PyObject *module)`293294*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*295296Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или `NULL`. См. [`Py_mod_state_size`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_size).297298При ошибке возвращает `NULL` с установленным исключением. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.16/c-api/exceptions.html#c.PyErr_Occurred), чтобы отличить этот случай от отсутствующего состояния модуля.299300#### `int PyModule_GetStateSize(PyObject *module, Py_ssize_t *result)`301302*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*303304Устанавливает *\*result* в размер состояния *module*, как задано с помощью [`Py_mod_state_size`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_size) (или [`PyModuleDef.m_size`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_size)), и возвращает 0.305306При ошибке устанавливает *\*result* в -1 и возвращает -1 с установленным исключением.307308Добавлено в версии 3.15.309310### Слоты для определения состояния модуля311312Следующие [`slot IDs`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) доступны для определения состояния модуля.313314#### `Py_mod_state_size`315316*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*317318[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) для размера состояния модуля в байтах.319320Установка значения в неотрицательное число означает, что модуль может быть повторно инициализирован, и задаёт дополнительный объём памяти, необходимый для его состояния.321322Подробнее см. [**PEP 3121**](https://python-all.ru/3.16/c-api/module.html).323324Используйте [`PyModule_GetStateSize()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetStateSize) для получения размера данного модуля.325326Добавлено в версии 3.15: Используйте [`PyModuleDef.m_size`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_size) для поддержки предыдущих версий.327328#### `Py_mod_state_traverse`329330*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*331332[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) для функции обхода, вызываемой при обходе GC объекта модуля.333334Сигнатура функции и значения аргументов аналогичны [`PyTypeObject.tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse):335336#### `int traverse_module_state(PyObject *module, visitproc visit, void *arg)`337338Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Это происходит сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec)). Более точно, эта функция не вызывается, если размер состояния ([`Py_mod_state_size`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_size)) больше 0, а состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetState)) равно `NULL`.339340Добавлено в версии 3.15: Используйте [`PyModuleDef.m_traverse`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_traverse) для поддержки предыдущих версий.341342#### `Py_mod_state_clear`343344*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*345346[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) для функции очистки, вызываемой при очистке GC объекта модуля.347348Сигнатура функции:349350#### `int clear_module_state(PyObject *module)`351352Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Это происходит сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec)). Точнее, эта функция не вызывается, если размер состояния ([`Py_mod_state_size`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_size)) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetState)) равно `NULL`.353354Как и [`PyTypeObject.tp_clear`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_clear), эта функция не *всегда* вызывается перед освобождением модуля. Например, когда подсчёта ссылок достаточно, чтобы определить, что объект больше не используется, циклический сборщик мусора не задействуется и функция [`Py_mod_state_free`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_free) вызывается напрямую.355356Добавлено в версии 3.15: Используйте [`PyModuleDef.m_clear`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_clear) для поддержки предыдущих версий.357358#### `Py_mod_state_free`359360*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*361362[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) для функции, вызываемой при освобождении объекта модуля.363364Сигнатура функции:365366#### `int free_module_state(PyObject *module)`367368Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Это происходит сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec)). Точнее, эта функция не вызывается, если размер состояния ([`Py_mod_state_size`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_size)) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetState)) равно `NULL`.369370Добавлено в версии 3.15: Используйте [`PyModuleDef.m_free`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_free) для поддержки предыдущих версий.371372### Токен модуля373374Каждый модуль может иметь связанный *токен*: значение размером с указатель, предназначенное для идентификации расположения памяти состояния модуля. Это означает, что если у вас есть объект модуля, но вы не уверены, «принадлежит» ли он вашему расширению, вы можете проверить это с помощью такого кода:375376```c377PyObject *module = <the module in question>378379void *module_token;380if (PyModule_GetToken(module, &module_token) < 0) {381    return NULL;382}383if (module_token != your_token) {384    PyErr_SetString(PyExc_ValueError, "unexpected module")385    return NULL;386}387388// Состояние этого модуля имеет ожидаемую структуру памяти; приведение типов безопасно.389struct my_state state = (struct my_state*)PyModule_GetState(module)390```391392Токен модуля – и значение *your\_token* для использования в приведённом выше коде – это:393394- Для модулей, созданных с помощью [`PyModuleDef`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef): адрес этого `PyModuleDef`;395- Для модулей, определённых с помощью слота [`Py_mod_token`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_token): значение этого слота;396- Для модулей, созданных из `PyModExport_*` [экспортного хука](https://python-all.ru/3.16/c-api/extension-modules.html#extension-export-hook): массив слотов, который вернул экспортный хук (если не переопределён с помощью [`Py_mod_token`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_token)).397398#### `Py_mod_token`399400*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*401402[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id) для токена модуля.403404Если вы используете этот слот для установки токена модуля (а не полагаетесь на значение по умолчанию), вы должны убедиться в следующем:405406- Указатель переживает класс, чтобы он не был повторно использован для чего-то другого пока класс существует.407- Он «принадлежит» тому модулю расширения, где находится класс, чтобы не конфликтовать с другими расширениями.408- Если токен указывает на структуру [`PyModuleDef`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef), модуль должен вести себя так, как если бы он был создан из этой `PyModuleDef`. В частности, состояние модуля должно иметь соответствующую структуру и семантику.409410Модули, созданные из [`PyModuleDef`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef), всегда используют адрес `PyModuleDef` в качестве токена. Это означает, что `Py_mod_token` не может использоваться в [`PyModuleDef.m_slots`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_slots).411412Добавлено в версии 3.15.413414#### `int PyModule_GetToken(PyObject *module, void **result)`415416*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*417418Устанавливает *\*result* в токен модуля для *module* и возвращает 0.419420В случае ошибки устанавливает *\*result* в NULL и возвращает -1 с установленным исключением.421422Добавлено в версии 3.15.423424См. также [`PyType_GetModuleByToken()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GetModuleByToken).425426## Создание модулей расширения динамически427428Следующие функции могут использоваться для динамического создания модуля расширения, а не из [экспортного хука](https://python-all.ru/3.16/c-api/extension-modules.html#extension-export-hook) расширения.429430#### `PyObject *PyModule_FromSlotsAndSpec(const PySlot *slots, PyObject *spec)`431432*Возвращаемое значение: новая ссылка.*433434*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*435436Создаёт новый объект модуля, принимая массив [слотов](https://python-all.ru/3.16/c-api/module.html#pymoduledef-slot) и [`ModuleSpec`](https://python-all.ru/3.16/library/importlib.html#importlib.machinery.ModuleSpec) *spec*.437438Аргумент *slots* должен указывать на массив структур [`PySlot`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot) структур, завершающийся записью с ID слота 0 (обычно записывается как [`PySlot_END`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot_END)). Массив должен содержать запись [`Py_mod_abi`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_abi).439440Аргумент *spec* может быть любым объектом, подобным `ModuleSpec`, как описано в документации [`Py_mod_create`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_create). В текущей версии *spec* должен иметь атрибут `name`.441442При успехе возвращает новый модуль. При ошибке возвращает `NULL` с установленным исключением.443444Обратите внимание: эта функция не обрабатывает слот выполнения модуля ([`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec)). Для полной инициализации модуля необходимо вызвать как `PyModule_FromSlotsAndSpec()`, так и [`PyModule_Exec()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_Exec). (См. также [многофазную инициализацию](https://python-all.ru/3.16/c-api/extension-modules.html#multi-phase-initialization).)445446Добавлено в версии 3.15.447448#### `int PyModule_Exec(PyObject *module)`449450*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*451452Выполняет слот(ы) [`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec) модуля *module*.453454При успехе возвращает 0. При ошибке возвращает -1 с установленным исключением.455456Для ясности: если у *module* нет слотов, например, если используется [однофазная инициализация (устаревшая)](https://python-all.ru/3.16/c-api/extension-modules.html#single-phase-initialization), то эта функция ничего не делает и возвращает 0.457458Добавлено в версии 3.15.459460## Структура определения модуля461462Традиционно модули расширения определялись с помощью *определения модуля* как «описания» того, как должен создаваться модуль. Вместо прямого использования массива [слотов](https://python-all.ru/3.16/c-api/module.html#pymoduledef-slot) определение содержит выделенные поля для наиболее распространённой функциональности и допускает дополнительные слоты как механизм расширения.463464Этот способ определения модулей по-прежнему доступен, и удалять его не планируется.465466#### `type PyModuleDef`467468*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) (см. ниже).*469470Структура определения модуля, содержащая информацию, необходимую для создания объекта модуля.471472Эта структура должна быть статически размещена (или иным образом гарантированно оставаться действительной, пока существуют созданные из неё модули). Обычно для каждого модуля расширения, определённого таким образом, существует только одна переменная этого типа.473474Структура, включая все поля, является частью [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable-abi) для сборок без свободных потоков (`abi3`). В Stable ABI для сборок со свободными потоками (`abi3t`) эта структура непрозрачна и практически непригодна к использованию; см. [Module definition](https://python-all.ru/3.16/c-api/module.html#pymoduledef-slot) для замены.475476#### `PyModuleDef_Base m_base`477478Всегда инициализируйте этот элемент значением [`PyModuleDef_HEAD_INIT`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef_HEAD_INIT):479480#### `type PyModuleDef_Base`481482*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) (см. ниже).*483484Тип `PyModuleDef.m_base`.485486Структура является частью [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable-abi) для сборок без свободных потоков (`abi3`). В Stable ABI для сборок со свободными потоками (`abi3t`) эта структура непрозрачна и практически непригодна к использованию.487488#### `PyModuleDef_HEAD_INIT`489490Требуемое начальное значение для `PyModuleDef.m_base`.491492#### `const char *m_name`493494Соответствует слоту [`Py_mod_name`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_name).495496#### `const char *m_doc`497498Эти элементы соответствуют слоту [`Py_mod_doc`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_doc). Установка в NULL равнозначна опусканию слота.499500#### `Py_ssize_t m_size`501502Соответствует слоту [`Py_mod_state_size`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_size). Установка в ноль равнозначна опусканию слота.503504При использовании [однофазной инициализации (устаревшей)](https://python-all.ru/3.16/c-api/extension-modules.html#single-phase-initialization) или при динамическом создании модулей с помощью [`PyModule_Create()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_Create) или [`PyModule_Create2()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_Create2), `m_size` может быть установлен в -1. Это указывает на то, что модуль не поддерживает под-интерпретаторы, поскольку имеет глобальное состояние.505506#### `PyMethodDef *m_methods`507508Соответствует слоту [`Py_mod_methods`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_methods). Установка в NULL равнозначна опусканию слота.509510#### `PyModuleDef_Slot *m_slots`511512Массив дополнительных слотов, завершающийся элементом `{0, NULL}`. Обратите внимание, что элементы используют более старую структуру [`PyModuleDef_Slot`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef_Slot), а не [`PySlot`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot).513514Если массив содержит слоты, соответствующие элементам [`PyModuleDef`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef), значения должны совпадать. Например, если используется [`Py_mod_name`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_name) в `m_slots`, [`PyModuleDef.m_name`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_name) должен быть установлен на тот же указатель (а не просто на равную строку).515516Изменено в версии 3.5: До версии 3.5 этот элемент всегда устанавливался в `NULL`, и определялся как:517518> #### `inquiry m_reload`519520#### `type PyModuleDef_Slot`521522*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) (включая все элементы) начиная с версии 3.5.*523524Более старая структура, определяющая дополнительные слоты модуля.525526Обратите внимание, что массив `PyModuleDef_Slot` может быть включён в массив `PySlot` с помощью [`Py_mod_slots`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_slots), и наоборот с помощью [`Py_slot_subslots`](https://python-all.ru/3.16/c-api/slots.html#c.Py_slot_subslots).527528Каждая структура `PyModuleDef_Slot` `modslot` интерпретируется как следующая структура [`PySlot`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot):529530```c531(PySlot){532   .sl_id=modslot.slot,533   .sl_flags=PySlot_INTPTR | sub_static,534   .sl_ptr=modslot.value535}536```537538где `sub_static` равно `PySlot_STATIC`, если слот требует флаг (например, для [`Py_mod_methods`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_methods)), или если этот флаг присутствует в «родительском» слоте `Py_mod_slots` (если есть).539540#### `int slot`541542Соответствует [`PySlot.sl_id`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id).543544#### `void *value`545546Соответствует [`PySlot.sl_ptr`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_ptr).547548Добавлено в версии 3.5.549550#### `traverseproc m_traverse`551552#### `inquiry m_clear`553554#### `freefunc m_free`555556Эти элементы соответствуют слотам [`Py_mod_state_traverse`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_traverse), [`Py_mod_state_clear`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_clear) и [`Py_mod_state_free`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_state_free), соответственно.557558Установка этих элементов в NULL равнозначна пропуску соответствующих слотов.559560Изменено в версии 3.9: Функции [`m_traverse`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_traverse), [`m_clear`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_clear) и [`m_free`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_free) больше не вызываются до выделения состояния модуля.561562#### `PyTypeObject PyModuleDef_Type`563564*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.5.*565566Тип объектов `PyModuleDef`.567568#### `Py_mod_slots`569570*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*571572[`Slot ID`](https://python-all.ru/3.16/c-api/slots.html#c.PySlot.sl_id), который работает как [`Py_slot_subslots`](https://python-all.ru/3.16/c-api/slots.html#c.Py_slot_subslots), за исключением того, что он задаёт массив структур [`PyModuleDef_Slot`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef_Slot).573574Добавлено в версии 3.15.575576Следующий API можно использовать для создания модулей из структуры `PyModuleDef`:577578#### `PyObject *PyModule_Create(PyModuleDef *def)`579580*Возвращаемое значение: новая ссылка.*581582Создаёт новый объект модуля на основе определения в *def*. Это макрос, который вызывает [`PyModule_Create2()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_Create2) с *module\_api\_version*, установленным в [`PYTHON_API_VERSION`](https://python-all.ru/3.16/c-api/module.html#c.PYTHON_API_VERSION), или в [`PYTHON_ABI_VERSION`](https://python-all.ru/3.16/c-api/module.html#c.PYTHON_ABI_VERSION), если используется [ограниченный API](https://python-all.ru/3.16/c-api/stable.html#limited-c-api).583584#### `PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)`585586*Возвращаемое значение: новая ссылка.*587588*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*589590Создаёт новый объект модуля на основе определения в *def*, предполагая версию API *module\_api\_version*. Если эта версия не совпадает с версией работающего интерпретатора, генерируется [`RuntimeWarning`](https://python-all.ru/3.16/library/exceptions.html#RuntimeWarning).591592Возвращает `NULL` с установленным исключением в случае ошибки.593594Эта функция не поддерживает слоты. Элемент [`m_slots`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef.m_slots) структуры *def* должен быть равен `NULL`.595596> **Примечание**597>598> В большинстве случаев вместо этой функции следует использовать [`PyModule_Create()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_Create); применяйте её, только если уверены, что она нужна.599600#### `PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)`601602*Возвращаемое значение: новая ссылка.*603604Этот макрос вызывает [`PyModule_FromDefAndSpec2()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_FromDefAndSpec2) с *module\_api\_version*, установленным в [`PYTHON_API_VERSION`](https://python-all.ru/3.16/c-api/module.html#c.PYTHON_API_VERSION), или в [`PYTHON_ABI_VERSION`](https://python-all.ru/3.16/c-api/module.html#c.PYTHON_ABI_VERSION), если используется [ограниченный API](https://python-all.ru/3.16/c-api/stable.html#limited-c-api).605606Добавлено в версии 3.5.607608[Мягкое устаревание](https://python-all.ru/3.16/glossary.html#term-soft-deprecated) с версии 3.16.0a0 (не выпущена): В новом коде используйте [`PyModule_FromSlotsAndSpec()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_FromSlotsAndSpec).609610#### `PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)`611612*Возвращаемое значение: новая ссылка.*613614*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*615616Создает новый объект модуля по определению из *def* и ModuleSpec *spec*, используя версию API *module\_api\_version*. Если эта версия не соответствует версии работающего интерпретатора, выдается [`RuntimeWarning`](https://python-all.ru/3.16/library/exceptions.html#RuntimeWarning).617618Возвращает `NULL` с установленным исключением в случае ошибки.619620Обратите внимание, что это не обрабатывает слоты выполнения ([`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec)). Для полной инициализации модуля необходимо вызвать как `PyModule_FromDefAndSpec`, так и `PyModule_ExecDef`.621622> **Примечание**623>624> В большинстве случаев вместо этой функции следует использовать [`PyModule_FromDefAndSpec()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_FromDefAndSpec); используйте её, только если точно уверены, что она нужна.625626Добавлено в версии 3.5.627628[Мягкое устаревание](https://python-all.ru/3.16/glossary.html#term-soft-deprecated) с версии 3.16.0a0 (не выпущена): В новом коде используйте [`PyModule_FromSlotsAndSpec()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_FromSlotsAndSpec).629630#### `int PyModule_ExecDef(PyObject *module, PyModuleDef *def)`631632*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*633634Обрабатывает любые слоты выполнения ([`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec)), заданные в *def*.635636Добавлено в версии 3.5.637638[Мягкое устаревание](https://python-all.ru/3.16/glossary.html#term-soft-deprecated) с версии 3.16.0a0 (не выпущена): Для выполнения собственных слотов выполнения модуля используйте [`PyModule_Exec()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_Exec), который работает с модулями, созданными не из структуры [`PyModuleDef`](https://python-all.ru/3.16/c-api/module.html#c.PyModuleDef).639640#### `PYTHON_API_VERSION`641642#### `PYTHON_API_STRING`643644Версия C API, соответственно как целое число (`1013`) и строка (`"1013"`). Определена для обратной совместимости.645646В настоящее время эта константа не обновляется в новых версиях Python и не полезна для версионирования. В будущем это может измениться.647648#### `PYTHON_ABI_VERSION`649650#### `PYTHON_ABI_STRING`651652Определены как `3` и `"3"` соответственно для обратной совместимости.653654В настоящее время эта константа не обновляется в новых версиях Python и не полезна для версионирования. В будущем это может измениться.655656## Вспомогательные функции657658Следующие функции предоставляются для помощи в инициализации объекта модуля. Они предназначены для слота выполнения модуля ([`Py_mod_exec`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_exec)), функции инициализации для устаревшей [однофазной инициализации](https://python-all.ru/3.16/c-api/extension-modules.html#single-phase-initialization), или кода, создающего модули динамически.659660#### `int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)`661662*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.10.*663664Добавляет объект в *module* как *name*. Это удобная функция, которую можно использовать из функции инициализации модуля.665666При успехе возвращает `0`. При ошибке вызывает исключение и возвращает `-1`.667668Пример использования:669670```c671static int672add_spam(PyObject *module, int value)673{674    PyObject *obj = PyLong_FromLong(value);675    if (obj == NULL) {676        return -1;677    }678    int res = PyModule_AddObjectRef(module, "spam", obj);679    Py_DECREF(obj);680    return res;681 }682```683684Для удобства функция принимает `NULL` *value* с установленным исключением. В этом случае возвращает `-1` и просто оставляет вызванное исключение без изменений.685686Пример можно также написать без явной проверки, что *obj* равен `NULL`:687688```c689static int690add_spam(PyObject *module, int value)691{692    PyObject *obj = PyLong_FromLong(value);693    int res = PyModule_AddObjectRef(module, "spam", obj);694    Py_XDECREF(obj);695    return res;696 }697```698699Обратите внимание, что в этом случае следует использовать `Py_XDECREF()` вместо `Py_DECREF()`, поскольку *obj* может быть `NULL`.700701Количество различных строк *name*, передаваемых этой функции, должно быть небольшим – обычно используйте только статически выделенные строки в качестве *name*. Для имен, неизвестных во время компиляции, предпочтительнее вызывать [`PyUnicode_FromString()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_FromString) и [`PyObject_SetAttr()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_SetAttr) напрямую. Подробнее см. [`PyUnicode_InternFromString()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_InternFromString), который может использоваться внутри для создания объекта ключа.702703Добавлено в версии 3.10.704705#### `int PyModule_Add(PyObject *module, const char *name, PyObject *value)`706707*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable), начиная с версии 3.13.*708709Похожа на [`PyModule_AddObjectRef()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_AddObjectRef), но “[крадет](https://python-all.ru/3.16/glossary.html#term-steal)” ссылку на *value* (даже при ошибке). Её можно вызывать с результатом функции, возвращающей новую ссылку, не беспокоясь о проверке результата или даже сохранении его в переменную.710711Пример использования:712713```c714if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {715    goto error;716}717```718719Добавлено в версии 3.13.720721#### `int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)`722723*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*724725Похоже на [`PyModule_AddObjectRef()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_AddObjectRef), но при успехе [присваивает](https://python-all.ru/3.16/glossary.html#term-steal) ссылку на *value* (если возвращает `0`).726727Рекомендуются новые функции [`PyModule_Add()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_Add) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_AddObjectRef), поскольку неправильное использование [`PyModule_AddObject()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_AddObject) может легко привести к утечкам ссылок.728729> **Примечание**730>731> В отличие от других функций, крадущих ссылки, `PyModule_AddObject()` освобождает ссылку на *value* **только при успехе**.732>733> Это означает, что возвращаемое значение необходимо проверять, а код вызова должен вручную [`Py_XDECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_XDECREF) *value* при ошибке.734735Пример использования:736737```c738PyObject *obj = PyBytes_FromString(value);739if (PyModule_AddObject(module, "spam", obj) < 0) {740    // Если 'obj' не NULL и PyModule_AddObject() завершился неудачей,741    // сильную ссылку 'obj' необходимо удалить с помощью Py_XDECREF().742    // Если 'obj' равен NULL, Py_XDECREF() ничего не делает.743    Py_XDECREF(obj);744    goto error;745}746// PyModule_AddObject() перехватил ссылку на obj:747// Py_XDECREF(obj) здесь не требуется.748```749750[Мягкое устаревание](https://python-all.ru/3.16/glossary.html#term-soft-deprecated) начиная с версии 3.13.751752#### `int PyModule_AddIntConstant(PyObject *module, const char *name, long value)`753754*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*755756Добавляет целочисленную константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.757758Это удобная функция, которая вызывает [`PyLong_FromLong()`](https://python-all.ru/3.16/c-api/long.html#c.PyLong_FromLong) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.759760#### `int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)`761762*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*763764Добавляет строковую константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Строка *value* должна быть завершена символами `NULL`. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.765766Это удобная функция, которая вызывает [`PyUnicode_InternFromString()`](https://python-all.ru/3.16/c-api/unicode.html#c.PyUnicode_InternFromString) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.767768#### `PyModule_AddIntMacro(module, macro)`769770Добавляет целочисленную константу в *module*. Имя и значение берутся из *macro*. Например, `PyModule_AddIntMacro(module, AF_INET)` добавляет целочисленную константу *AF\_INET* со значением *AF\_INET* в *module*. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.771772#### `PyModule_AddStringMacro(module, macro)`773774Добавляет строковую константу в *module*.775776#### `int PyModule_AddType(PyObject *module, PyTypeObject *type)`777778*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.10.*779780Добавляет объект типа в *module*. Объект типа финализируется внутренним вызовом [`PyType_Ready()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_Ready). Имя объекта типа берётся из последнего компонента [`tp_name`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_name) после точки. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.781782Добавлено в версии 3.9.783784#### `int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)`785786*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*787788Добавляет функции из массива *functions*, завершённого `NULL`, в *module*. Подробнее об отдельных записях см. документацию [`PyMethodDef`](https://python-all.ru/3.16/c-api/structures.html#c.PyMethodDef) (из-за отсутствия общего пространства имён модуля функции уровня модуля, реализованные на C, обычно получают модуль в качестве первого параметра, что делает их похожими на методы экземпляров классов Python).789790Эта функция вызывается автоматически при создании модуля из `PyModuleDef` (например, при использовании [многофазной инициализации](https://python-all.ru/3.16/c-api/extension-modules.html#multi-phase-initialization), `PyModule_Create` или `PyModule_FromDefAndSpec`). Некоторые авторы модулей могут предпочитать определять функции в нескольких массивах [`PyMethodDef`](https://python-all.ru/3.16/c-api/structures.html#c.PyMethodDef); в этом случае им следует вызывать эту функцию напрямую.791792Массив *functions* должен быть статически выделен (или иным образом гарантированно переживать объект модуля).793794Добавлено в версии 3.5.795796#### `int PyModule_SetDocString(PyObject *module, const char *docstring)`797798*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*799800Устанавливает docstring для *module* как *docstring*. Эта функция вызывается автоматически при создании модуля из `PyModuleDef` (например, при использовании [многофазной инициализации](https://python-all.ru/3.16/c-api/extension-modules.html#multi-phase-initialization), `PyModule_Create` или `PyModule_FromDefAndSpec`).801802Возвращает `0` при успехе. Возвращает `-1` с установленным исключением при ошибке.803804Добавлено в версии 3.5.805806#### `int PyUnstable_Module_SetGIL(PyObject *module, void *gil)`807808> *Это [нестабильное API](https://python-all.ru/3.16/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*809810Указывает, поддерживает ли *module* работу без глобальной блокировки интерпретатора (GIL), используя одно из значений из [`Py_mod_gil`](https://python-all.ru/3.16/c-api/module.html#c.Py_mod_gil). Необходимо вызывать в функции инициализации *module* при использовании [устаревшей однофазной инициализации](https://python-all.ru/3.16/c-api/extension-modules.html#single-phase-initialization). Если эта функция не вызывается во время инициализации модуля, механизм импорта считает, что модуль не поддерживает работу без GIL. Эта функция доступна только в сборках Python, настроенных с [`--disable-gil`](https://python-all.ru/3.16/using/configure.html#cmdoption-disable-gil). Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.811812Добавлено в версии 3.13.813814### Поиск модуля (однофазная инициализация)815816Устаревшая схема [однофазной инициализации](https://python-all.ru/3.16/c-api/extension-modules.html#single-phase-initialization) создаёт модули-одиночки, которые можно найти в контексте текущего интерпретатора. Это позволяет позже получить объект модуля, имея только ссылку на определение модуля.817818Эти функции не будут работать с модулями, созданными с помощью многофазной инициализации, поскольку из одного определения можно создать несколько таких модулей.819820#### `PyObject *PyState_FindModule(PyModuleDef *def)`821822*Возвращаемое значение: заимствованная ссылка.*823824*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*825826Возвращает объект модуля, созданный из *def* для текущего интерпретатора. Этот метод требует, чтобы объект модуля был предварительно прикреплён к состоянию интерпретатора с помощью [`PyState_AddModule()`](https://python-all.ru/3.16/c-api/module.html#c.PyState_AddModule). Если соответствующий объект модуля не найден или ещё не прикреплён к состоянию интерпретатора, он возвращает `NULL`.827828#### `int PyState_AddModule(PyObject *module, PyModuleDef *def)`829830*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.3.*831832Прикрепляет объект модуля, переданный функции, к состоянию интерпретатора. Это позволяет обращаться к объекту модуля через [`PyState_FindModule()`](https://python-all.ru/3.16/c-api/module.html#c.PyState_FindModule).833834Действует только на модули, созданные с помощью однофазной инициализации.835836Python вызывает `PyState_AddModule` автоматически после импорта модуля, использующего [однофазную инициализацию](https://python-all.ru/3.16/c-api/extension-modules.html#single-phase-initialization), поэтому вызывать его из кода инициализации модуля не обязательно (но безвредно). Явный вызов требуется только в том случае, если собственный код инициализации модуля впоследствии вызывает `PyState_FindModule`. Функция в основном предназначена для реализации альтернативных механизмов импорта (путём непосредственного вызова или обращения к её реализации за подробностями требуемых обновлений состояния).837838Если модуль был ранее прикреплён с помощью того же *def*, он заменяется новым *module*.839840Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3.16/glossary.html#term-attached-thread-state).841842Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.843844Добавлено в версии 3.3.845846#### `int PyState_RemoveModule(PyModuleDef *def)`847848*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.3.*849850Удаляет объект модуля, созданный из *def*, из состояния интерпретатора. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.851852Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3.16/glossary.html#term-attached-thread-state).853854Добавлено в версии 3.3.855