`module.md`

562 строк · 48.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3/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/c-api/stable.html#stable).*1213Этот экземпляр [`PyTypeObject`](https://python-all.ru/3/c-api/type.html#c.PyTypeObject) представляет тип Python-модуля. Он доступен программам Python как [`types.ModuleType`](https://python-all.ru/3/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/c-api/module.html#c.PyModule_Type). Эта функция всегда выполняется успешно.2223#### `PyObject *PyModule_NewObject(PyObject *name)`2425*Возвращаемое значение: новая ссылка.*2627*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.*2829Возвращает новый объект модуля с [`module.__name__`](https://python-all.ru/3/reference/datamodel.html#module.__name__), установленным в *name*. Атрибуты модуля `__name__`, [`__doc__`](https://python-all.ru/3/reference/datamodel.html#module.__doc__), [`__package__`](https://python-all.ru/3/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3/reference/datamodel.html#module.__loader__) заполняются (все, кроме `__name__`, устанавливаются в `None`). Вызывающий отвечает за установку атрибута [`__file__`](https://python-all.ru/3/reference/datamodel.html#module.__file__).3031Возвращает `NULL` с установленным исключением в случае ошибки.3233Добавлено в версии 3.3.3435Изменено в версии 3.4: [`__package__`](https://python-all.ru/3/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3/reference/datamodel.html#module.__loader__) теперь устанавливаются в `None`.3637#### `PyObject *PyModule_New(const char *name)`3839*Возвращаемое значение: новая ссылка.*4041*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*4243Аналогично [`PyModule_NewObject()`](https://python-all.ru/3/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/c-api/stable.html#stable).*5051Возвращает объект словаря, реализующий пространство имён *module*; этот объект совпадает с атрибутом [`__dict__`](https://python-all.ru/3/reference/datamodel.html#object.__dict__) объекта модуля. Если *module* не является объектом модуля (или подтипом объекта модуля), возбуждается [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError) и возвращается `NULL`.5253Расширениям рекомендуется использовать другие функции `PyModule_*` и `PyObject_*` вместо прямого манипулирования [`__dict__`](https://python-all.ru/3/reference/datamodel.html#object.__dict__) модуля.5455Возвращаемая ссылка является заимствованной из модуля; она действительна до тех пор, пока модуль не будет уничтожен.5657#### `PyObject *PyModule_GetNameObject(PyObject *module)`5859*Возвращаемое значение: новая ссылка.*6061*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.*6263Возвращает значение [`__name__`](https://python-all.ru/3/reference/datamodel.html#module.__name__) для *module*. Если модуль не предоставляет такого значения или оно не является строкой, возбуждается [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError) и возвращается `NULL`.6465Добавлено в версии 3.3.6667#### `const char *PyModule_GetName(PyObject *module)`6869*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*7071Аналогично [`PyModule_GetNameObject()`](https://python-all.ru/3/c-api/module.html#c.PyModule_GetNameObject), но возвращает имя, закодированное в `'utf-8'`.7273Возвращаемый буфер действителен только до тех пор, пока модуль не переименован или не уничтожен. Обратите внимание, что код Python может переименовать модуль, установив его атрибут [`__name__`](https://python-all.ru/3/reference/datamodel.html#module.__name__).7475#### `void *PyModule_GetState(PyObject *module)`7677*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*7879Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или `NULL`. См. [`PyModuleDef.m_size`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef.m_size).8081#### `PyModuleDef *PyModule_GetDef(PyObject *module)`8283*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*8485Возвращает указатель на структуру [`PyModuleDef`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef), из которой был создан модуль, или `NULL`, если модуль не был создан из определения.8687В случае ошибки возвращает `NULL` с установленным исключением. Используйте [`PyErr_Occurred()`](https://python-all.ru/3/c-api/exceptions.html#c.PyErr_Occurred), чтобы отличить этот случай от отсутствия `PyModuleDef`.8889#### `PyObject *PyModule_GetFilenameObject(PyObject *module)`9091*Возвращаемое значение: новая ссылка.*9293*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*9495Возвращает имя файла, из которого был загружен *module*, используя атрибут [`__file__`](https://python-all.ru/3/reference/datamodel.html#module.__file__) модуля *module*. Если он не определён или не является строкой, возбуждает [`SystemError`](https://python-all.ru/3/library/exceptions.html#SystemError) и возвращает `NULL`; в противном случае возвращает ссылку на объект Unicode.9697Добавлено в версии 3.2.9899#### `const char *PyModule_GetFilename(PyObject *module)`100101*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*102103Аналогично [`PyModule_GetFilenameObject()`](https://python-all.ru/3/c-api/module.html#c.PyModule_GetFilenameObject), но возвращает имя файла, закодированное в 'utf-8'.104105Возвращаемый буфер действителен только до тех пор, пока атрибут [`__file__`](https://python-all.ru/3/reference/datamodel.html#module.__file__) модуля не будет переназначен или модуль не будет уничтожен.106107Устарело с версии 3.2: [`PyModule_GetFilename()`](https://python-all.ru/3/c-api/module.html#c.PyModule_GetFilename) возбуждает [`UnicodeEncodeError`](https://python-all.ru/3/library/exceptions.html#UnicodeEncodeError) для некодируемых имён файлов; вместо него используйте [`PyModule_GetFilenameObject()`](https://python-all.ru/3/c-api/module.html#c.PyModule_GetFilenameObject).108109# Определения модулей110111Функции из предыдущего раздела работают с любым объектом модуля, в том числе с модулями, импортированными из кода Python.112113Модули, определённые через C API, обычно используют *определение модуля*, [`PyModuleDef`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef) – статически выделенное, неизменное «описание» того, как должен быть создан модуль.114115Это определение обычно используется для создания «главного» объекта модуля расширения (см. [Определение модулей расширения](https://python-all.ru/3/c-api/extension-modules.html#extension-modules)). Оно также используется для [динамического создания модулей расширения](https://python-all.ru/3/c-api/module.html#moduledef-dynamic).116117В отличие от [`PyModule_New()`](https://python-all.ru/3/c-api/module.html#c.PyModule_New), определение позволяет управлять *состоянием модуля* – областью памяти, которая выделяется и очищается вместе с объектом модуля. В отличие от атрибутов модуля Python, код Python не может заменить или удалить данные, хранящиеся в состоянии модуля.118119#### `type PyModuleDef`120121*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) (включая все члены).*122123Структура определения модуля, содержащая всю информацию, необходимую для создания объекта модуля. Эта структура должна быть статически выделена (или иным образом гарантированно оставаться корректной, пока существуют созданные на её основе модули). Обычно для каждого модуля расширения существует только одна переменная такого типа.124125#### `PyModuleDef_Base m_base`126127Всегда инициализируйте этот элемент значением `PyModuleDef_HEAD_INIT`.128129#### `const char *m_name`130131Имя нового модуля.132133#### `const char *m_doc`134135Докстринг для модуля; обычно используется переменная докстринга, созданная с помощью [`PyDoc_STRVAR`](https://python-all.ru/3/c-api/intro.html#c.PyDoc_STRVAR).136137#### `Py_ssize_t m_size`138139Состояние модуля может храниться в выделенной под каждый модуль области памяти, доступ к которой можно получить через [`PyModule_GetState()`](https://python-all.ru/3/c-api/module.html#c.PyModule_GetState), а не в статических глобальных переменных. Это делает модули безопасными для использования в нескольких под-интерпретаторах.140141Эта область памяти выделяется на основе *m\_size* при создании модуля и освобождается при удалении объекта модуля, после вызова функции [`m_free`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef.m_free) (если она присутствует).142143Установка неотрицательного значения означает, что модуль можно переинициализировать, и задаёт дополнительный объём памяти, необходимый для его состояния.144145Установка `m_size` в `-1` означает, что модуль не поддерживает под-интерпретаторы, поскольку у него глобальное состояние. Отрицательное `m_size` допускается только при использовании [устаревшей однофазной инициализации](https://python-all.ru/3/c-api/extension-modules.html#single-phase-initialization) или при [динамическом создании модулей](https://python-all.ru/3/c-api/module.html#moduledef-dynamic).146147Подробнее см. [**PEP 3121**](https://python-all.ru/3/c-api/module.html).148149#### `PyMethodDef *m_methods`150151Указатель на таблицу функций уровня модуля, описываемых значениями [`PyMethodDef`](https://python-all.ru/3/c-api/structures.html#c.PyMethodDef). Может быть `NULL`, если функции отсутствуют.152153#### `PyModuleDef_Slot *m_slots`154155Массив определений слотов для многофазной инициализации, завершающийся записью `{0, NULL}`. При использовании устаревшей однофазной инициализации *m\_slots* должен быть `NULL`.156157Изменено в версии 3.5: До версии 3.5 этот элемент всегда устанавливался в `NULL`, и определялся как:158159> #### `inquiry m_reload`160161#### `traverseproc m_traverse`162163Функция обхода, вызываемая при GC-обходе объекта модуля, или `NULL`, если она не нужна.164165Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3/c-api/module.html#c.PyModule_GetState)) равно `NULL`.166167Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.168169#### `inquiry m_clear`170171Функция очистки, вызываемая при GC-очистке объекта модуля, или `NULL`, если она не нужна.172173Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3/c-api/module.html#c.PyModule_GetState)) равно `NULL`.174175Как и [`PyTypeObject.tp_clear`](https://python-all.ru/3/c-api/typeobj.html#c.PyTypeObject.tp_clear), эта функция вызывается не *всегда* перед освобождением модуля. Например, когда подсчёта ссылок достаточно, чтобы определить, что объект больше не используется, циклический сборщик мусора не задействуется, и [`m_free`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef.m_free) вызывается напрямую.176177Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.178179#### `freefunc m_free`180181Функция, вызываемая при освобождении объекта модуля, или `NULL`, если она не нужна.182183Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3/c-api/module.html#c.PyModule_GetState)) равно `NULL`.184185Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.186187#### `PyTypeObject PyModuleDef_Type`188189*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.5.*190191Тип объектов `PyModuleDef`.192193## Слоты модуля194195#### `type PyModuleDef_Slot`196197*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) (включая все элементы) начиная с версии 3.5.*198199#### `int slot`200201Идентификатор слота, выбираемый из доступных значений, описанных ниже.202203#### `void *value`204205Значение слота, смысл которого зависит от идентификатора слота.206207Добавлено в версии 3.5.208209Доступны следующие типы слотов:210211#### `Py_mod_create`212213*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.5.*214215Задаёт функцию, которая вызывается для создания самого объекта модуля. Указатель *value* этого слота должен указывать на функцию со следующей сигнатурой:216217#### `PyObject *create_module(PyObject *spec, PyModuleDef *def)`218219Функция получает экземпляр [`ModuleSpec`](https://python-all.ru/3/library/importlib.html#importlib.machinery.ModuleSpec), как определено в [**PEP 451**](https://python-all.ru/3/c-api/module.html), и определение модуля. Она должна вернуть новый объект модуля или установить ошибку и вернуть `NULL`.220221Эта функция должна быть минимальной. В частности, она не должна вызывать произвольный код Python, так как повторная попытка импорта того же модуля может привести к бесконечному циклу.222223В одном определении модуля нельзя задавать несколько слотов `Py_mod_create`.224225Если `Py_mod_create` не указан, механизм импорта создаст обычный объект модуля с помощью [`PyModule_New()`](https://python-all.ru/3/c-api/module.html#c.PyModule_New). Имя берётся из *spec*, а не из определения, чтобы расширения могли динамически подстраиваться под своё место в иерархии модулей и импортироваться под другими именами через симлинки, оставаясь привязанными к одному определению модуля.226227Возвращаемый объект не обязан быть экземпляром [`PyModule_Type`](https://python-all.ru/3/c-api/module.html#c.PyModule_Type). Можно использовать любой тип, если он поддерживает установку и получение атрибутов, связанных с импортом. Однако только экземпляры `PyModule_Type` могут быть возвращены, если `PyModuleDef` содержит ненулевые `NULL` `m_traverse`, `m_clear`, `m_free`; ненулевой `m_size`; или слоты, отличные от `Py_mod_create`.228229Добавлено в версии 3.5.230231#### `Py_mod_exec`232233*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.5.*234235Задаёт функцию, которая вызывается для *выполнения* модуля. Это эквивалентно выполнению кода модуля Python: обычно эта функция добавляет в модуль классы и константы. Сигнатура функции такова:236237#### `int exec_module(PyObject *module)`238239Если указано несколько слотов `Py_mod_exec`, они обрабатываются в том порядке, в котором расположены в массиве *m\_slots*.240241Добавлено в версии 3.5.242243#### `Py_mod_multiple_interpreters`244245*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.12.*246247Задаёт одно из следующих значений:248249#### `Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`250251Модуль не поддерживает импорт в подынтерпретаторах.252253#### `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`254255Модуль поддерживает импорт в подынтерпретаторах, но только если они используют общий GIL основного интерпретатора. (См. [Изоляция модулей расширения](https://python-all.ru/3/howto/isolating-extensions.html#isolating-extensions-howto).)256257#### `Py_MOD_PER_INTERPRETER_GIL_SUPPORTED`258259Модуль поддерживает импорт в подынтерпретаторах, даже если у них собственный GIL. (См. [Изоляция модулей расширения](https://python-all.ru/3/howto/isolating-extensions.html#isolating-extensions-howto).)260261Этот слот определяет, будет ли импорт этого модуля в подынтерпретаторе завершаться ошибкой.262263В одном определении модуля нельзя указывать несколько слотов `Py_mod_multiple_interpreters`.264265Если `Py_mod_multiple_interpreters` не указан, механизм импорта по умолчанию использует `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`.266267Добавлено в версии 3.12.268269#### `Py_mod_gil`270271*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable), начиная с версии 3.13.*272273Задаёт одно из следующих значений:274275#### `Py_MOD_GIL_USED`276277Модуль зависит от наличия глобальной блокировки интерпретатора (GIL), и может обращаться к глобальному состоянию без синхронизации.278279#### `Py_MOD_GIL_NOT_USED`280281Модуль можно безопасно использовать без активного GIL.282283Этот слот игнорируется сборками Python, не настроенными с [`--disable-gil`](https://python-all.ru/3/using/configure.html#cmdoption-disable-gil). В противном случае он определяет, приведёт ли импорт этого модуля к автоматическому включению GIL. Подробнее см. [Free-threaded CPython](https://python-all.ru/3/whatsnew/3.13.html#whatsnew313-free-threaded-cpython).284285В одном определении модуля нельзя указывать несколько слотов `Py_mod_gil`.286287Если `Py_mod_gil` не указан, механизм импорта по умолчанию использует `Py_MOD_GIL_USED`.288289Добавлено в версии 3.13.290291# Создание модулей расширения динамически292293Следующие функции можно использовать для создания модуля за пределами [инициализирующей функции расширения](https://python-all.ru/3/c-api/extension-modules.html#extension-export-hook). Они также используются в [однофазной инициализации](https://python-all.ru/3/c-api/extension-modules.html#single-phase-initialization).294295#### `PyObject *PyModule_Create(PyModuleDef *def)`296297*Возвращаемое значение: новая ссылка.*298299Создаёт новый объект модуля на основе определения в *def*. Это макрос, который вызывает [`PyModule_Create2()`](https://python-all.ru/3/c-api/module.html#c.PyModule_Create2) с *module\_api\_version*, установленным в [`PYTHON_API_VERSION`](https://python-all.ru/3/c-api/module.html#c.PYTHON_API_VERSION), или в [`PYTHON_ABI_VERSION`](https://python-all.ru/3/c-api/module.html#c.PYTHON_ABI_VERSION), если используется [ограниченный API](https://python-all.ru/3/c-api/stable.html#limited-c-api).300301#### `PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)`302303*Возвращаемое значение: новая ссылка.*304305*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*306307Создаёт новый объект модуля на основе определения в *def*, предполагая версию API *module\_api\_version*. Если эта версия не совпадает с версией работающего интерпретатора, генерируется [`RuntimeWarning`](https://python-all.ru/3/library/exceptions.html#RuntimeWarning).308309Возвращает `NULL` с установленным исключением в случае ошибки.310311Эта функция не поддерживает слоты. Элемент [`m_slots`](https://python-all.ru/3/c-api/module.html#c.PyModuleDef.m_slots) структуры *def* должен быть равен `NULL`.312313> **Примечание**314>315> В большинстве случаев вместо этой функции следует использовать [`PyModule_Create()`](https://python-all.ru/3/c-api/module.html#c.PyModule_Create); используйте её, только если точно уверены, что она нужна.316317#### `PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)`318319*Возвращаемое значение: новая ссылка.*320321Этот макрос вызывает [`PyModule_FromDefAndSpec2()`](https://python-all.ru/3/c-api/module.html#c.PyModule_FromDefAndSpec2) с *module\_api\_version*, установленным в [`PYTHON_API_VERSION`](https://python-all.ru/3/c-api/module.html#c.PYTHON_API_VERSION), или в [`PYTHON_ABI_VERSION`](https://python-all.ru/3/c-api/module.html#c.PYTHON_ABI_VERSION), если используется [ограниченный API](https://python-all.ru/3/c-api/stable.html#limited-c-api).322323Добавлено в версии 3.5.324325#### `PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)`326327*Возвращаемое значение: новая ссылка.*328329*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.*330331Создает новый объект модуля по определению из *def* и ModuleSpec *spec*, используя версию API *module\_api\_version*. Если эта версия не соответствует версии работающего интерпретатора, выдается [`RuntimeWarning`](https://python-all.ru/3/library/exceptions.html#RuntimeWarning).332333Возвращает `NULL` с установленным исключением в случае ошибки.334335Обратите внимание, что это не обрабатывает слоты выполнения ([`Py_mod_exec`](https://python-all.ru/3/c-api/module.html#c.Py_mod_exec)). Для полной инициализации модуля необходимо вызвать как `PyModule_FromDefAndSpec`, так и `PyModule_ExecDef`.336337> **Примечание**338>339> В большинстве случаев вместо этой функции следует использовать [`PyModule_FromDefAndSpec()`](https://python-all.ru/3/c-api/module.html#c.PyModule_FromDefAndSpec); используйте её, только если точно уверены, что она нужна.340341Добавлено в версии 3.5.342343#### `int PyModule_ExecDef(PyObject *module, PyModuleDef *def)`344345*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.*346347Обрабатывает любые слоты выполнения ([`Py_mod_exec`](https://python-all.ru/3/c-api/module.html#c.Py_mod_exec)), заданные в *def*.348349Добавлено в версии 3.5.350351#### `PYTHON_API_VERSION`352353Версия C API. Определяется для обратной совместимости.354355В настоящее время эта константа не обновляется в новых версиях Python и не полезна для версионирования. В будущем это может измениться.356357#### `PYTHON_ABI_VERSION`358359Определяется как `3` для обратной совместимости.360361В настоящее время эта константа не обновляется в новых версиях Python и не полезна для версионирования. В будущем это может измениться.362363# Вспомогательные функции364365Следующие функции предназначены для инициализации состояния модуля. Они используются в слотах выполнения модуля ([`Py_mod_exec`](https://python-all.ru/3/c-api/module.html#c.Py_mod_exec)), в инициализирующей функции для устаревшей [однофазной инициализации](https://python-all.ru/3/c-api/extension-modules.html#single-phase-initialization) или в коде, динамически создающем модули.366367#### `int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)`368369*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.10.*370371Добавляет объект в *module* как *name*. Это удобная функция, которую можно использовать из функции инициализации модуля.372373При успехе возвращает `0`. При ошибке вызывает исключение и возвращает `-1`.374375Пример использования:376377```c378static int379add_spam(PyObject *module, int value)380{381    PyObject *obj = PyLong_FromLong(value);382    if (obj == NULL) {383        return -1;384    }385    int res = PyModule_AddObjectRef(module, "spam", obj);386    Py_DECREF(obj);387    return res;388 }389```390391Для удобства функция принимает `NULL` *value* с установленным исключением. В этом случае возвращает `-1` и просто оставляет вызванное исключение без изменений.392393Пример можно также написать без явной проверки, что *obj* равен `NULL`:394395```c396static int397add_spam(PyObject *module, int value)398{399    PyObject *obj = PyLong_FromLong(value);400    int res = PyModule_AddObjectRef(module, "spam", obj);401    Py_XDECREF(obj);402    return res;403 }404```405406Обратите внимание, что в этом случае следует использовать `Py_XDECREF()` вместо `Py_DECREF()`, поскольку *obj* может быть `NULL`.407408Количество различных строк *name*, передаваемых этой функции, должно быть небольшим – обычно используйте только статически выделенные строки в качестве *name*. Для имен, неизвестных во время компиляции, предпочтительнее вызывать [`PyUnicode_FromString()`](https://python-all.ru/3/c-api/unicode.html#c.PyUnicode_FromString) и [`PyObject_SetAttr()`](https://python-all.ru/3/c-api/object.html#c.PyObject_SetAttr) напрямую. Подробнее см. [`PyUnicode_InternFromString()`](https://python-all.ru/3/c-api/unicode.html#c.PyUnicode_InternFromString), который может использоваться внутри для создания объекта ключа.409410Добавлено в версии 3.10.411412#### `int PyModule_Add(PyObject *module, const char *name, PyObject *value)`413414*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable), начиная с версии 3.13.*415416Похожа на [`PyModule_AddObjectRef()`](https://python-all.ru/3/c-api/module.html#c.PyModule_AddObjectRef), но “[крадет](https://python-all.ru/3/glossary.html#term-steal)” ссылку на *value* (даже при ошибке). Её можно вызывать с результатом функции, возвращающей новую ссылку, не беспокоясь о проверке результата или даже сохранении его в переменную.417418Пример использования:419420```c421if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {422    goto error;423}424```425426Добавлено в версии 3.13.427428#### `int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)`429430*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*431432Похоже на [`PyModule_AddObjectRef()`](https://python-all.ru/3/c-api/module.html#c.PyModule_AddObjectRef), но при успехе [присваивает](https://python-all.ru/3/glossary.html#term-steal) ссылку на *value* (если возвращает `0`).433434Рекомендуются новые функции [`PyModule_Add()`](https://python-all.ru/3/c-api/module.html#c.PyModule_Add) и [`PyModule_AddObjectRef()`](https://python-all.ru/3/c-api/module.html#c.PyModule_AddObjectRef), поскольку неправильное использование [`PyModule_AddObject()`](https://python-all.ru/3/c-api/module.html#c.PyModule_AddObject) может легко привести к утечкам ссылок.435436> **Примечание**437>438> В отличие от других функций, крадущих ссылки, `PyModule_AddObject()` освобождает ссылку на *value* **только при успехе**.439>440> Это означает, что возвращаемое значение необходимо проверять, а код вызова должен вручную [`Py_XDECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XDECREF) *value* при ошибке.441442Пример использования:443444```c445PyObject *obj = PyBytes_FromString(value);446if (PyModule_AddObject(module, "spam", obj) < 0) {447    // Если 'obj' не NULL и PyModule_AddObject() завершился неудачей,448    // сильную ссылку 'obj' необходимо удалить с помощью Py_XDECREF().449    // Если 'obj' равен NULL, Py_XDECREF() ничего не делает.450    Py_XDECREF(obj);451    goto error;452}453// PyModule_AddObject() перехватил ссылку на obj:454// Py_XDECREF(obj) здесь не требуется.455```456457[Мягкое устаревание](https://python-all.ru/3/glossary.html#term-soft-deprecated) начиная с версии 3.13.458459#### `int PyModule_AddIntConstant(PyObject *module, const char *name, long value)`460461*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*462463Добавляет целочисленную константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.464465Это удобная функция, которая вызывает [`PyLong_FromLong()`](https://python-all.ru/3/c-api/long.html#c.PyLong_FromLong) и [`PyModule_AddObjectRef()`](https://python-all.ru/3/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.466467#### `int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)`468469*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*470471Добавляет строковую константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Строка *value* должна быть завершена символами `NULL`. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.472473Это удобная функция, которая вызывает [`PyUnicode_InternFromString()`](https://python-all.ru/3/c-api/unicode.html#c.PyUnicode_InternFromString) и [`PyModule_AddObjectRef()`](https://python-all.ru/3/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.474475#### `PyModule_AddIntMacro(module, macro)`476477Добавляет целочисленную константу в *module*. Имя и значение берутся из *macro*. Например, `PyModule_AddIntMacro(module, AF_INET)` добавляет целочисленную константу *AF\_INET* со значением *AF\_INET* в *module*. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.478479#### `PyModule_AddStringMacro(module, macro)`480481Добавляет строковую константу в *module*.482483#### `int PyModule_AddType(PyObject *module, PyTypeObject *type)`484485*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.10.*486487Добавляет объект типа в *module*. Объект типа финализируется внутренним вызовом [`PyType_Ready()`](https://python-all.ru/3/c-api/type.html#c.PyType_Ready). Имя объекта типа берётся из последнего компонента [`tp_name`](https://python-all.ru/3/c-api/typeobj.html#c.PyTypeObject.tp_name) после точки. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.488489Добавлено в версии 3.9.490491#### `int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)`492493*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.*494495Добавляет функции из массива *functions*, завершённого `NULL`, в *module*. Подробнее об отдельных записях см. документацию [`PyMethodDef`](https://python-all.ru/3/c-api/structures.html#c.PyMethodDef) (из-за отсутствия общего пространства имён модуля функции уровня модуля, реализованные на C, обычно получают модуль в качестве первого параметра, что делает их похожими на методы экземпляров классов Python).496497Эта функция вызывается автоматически при создании модуля из `PyModuleDef` (например, при использовании [многофазной инициализации](https://python-all.ru/3/c-api/extension-modules.html#multi-phase-initialization), `PyModule_Create` или `PyModule_FromDefAndSpec`). Некоторые авторы модулей могут предпочитать определять функции в нескольких массивах [`PyMethodDef`](https://python-all.ru/3/c-api/structures.html#c.PyMethodDef); в этом случае им следует вызывать эту функцию напрямую.498499Массив *functions* должен быть статически выделен (или иным образом гарантированно переживать объект модуля).500501Добавлено в версии 3.5.502503#### `int PyModule_SetDocString(PyObject *module, const char *docstring)`504505*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.*506507Устанавливает docstring для *module* как *docstring*. Эта функция вызывается автоматически при создании модуля из `PyModuleDef` (например, при использовании [многофазной инициализации](https://python-all.ru/3/c-api/extension-modules.html#multi-phase-initialization), `PyModule_Create` или `PyModule_FromDefAndSpec`).508509Возвращает `0` при успехе. Возвращает `-1` с установленным исключением при ошибке.510511Добавлено в версии 3.5.512513#### `int PyUnstable_Module_SetGIL(PyObject *module, void *gil)`514515> *Это [нестабильное API](https://python-all.ru/3/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*516517Указывает, поддерживает ли *module* работу без глобальной блокировки интерпретатора (GIL), используя одно из значений из [`Py_mod_gil`](https://python-all.ru/3/c-api/module.html#c.Py_mod_gil). Необходимо вызывать в функции инициализации *module* при использовании [устаревшей однофазной инициализации](https://python-all.ru/3/c-api/extension-modules.html#single-phase-initialization). Если эта функция не вызывается во время инициализации модуля, механизм импорта считает, что модуль не поддерживает работу без GIL. Эта функция доступна только в сборках Python, настроенных с [`--disable-gil`](https://python-all.ru/3/using/configure.html#cmdoption-disable-gil). Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.518519Добавлено в версии 3.13.520521## Поиск модуля (однофазная инициализация)522523Устаревшая схема [однофазной инициализации](https://python-all.ru/3/c-api/extension-modules.html#single-phase-initialization) создаёт модули-одиночки, которые можно найти в контексте текущего интерпретатора. Это позволяет позже получить объект модуля, имея только ссылку на определение модуля.524525Эти функции не будут работать с модулями, созданными с помощью многофазной инициализации, поскольку из одного определения можно создать несколько таких модулей.526527#### `PyObject *PyState_FindModule(PyModuleDef *def)`528529*Возвращаемое значение: заимствованная ссылка.*530531*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*532533Возвращает объект модуля, созданный из *def* для текущего интерпретатора. Этот метод требует, чтобы объект модуля был предварительно прикреплён к состоянию интерпретатора с помощью [`PyState_AddModule()`](https://python-all.ru/3/c-api/module.html#c.PyState_AddModule). Если соответствующий объект модуля не найден или ещё не прикреплён к состоянию интерпретатора, он возвращает `NULL`.534535#### `int PyState_AddModule(PyObject *module, PyModuleDef *def)`536537*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.3.*538539Прикрепляет объект модуля, переданный функции, к состоянию интерпретатора. Это позволяет обращаться к объекту модуля через [`PyState_FindModule()`](https://python-all.ru/3/c-api/module.html#c.PyState_FindModule).540541Действует только на модули, созданные с помощью однофазной инициализации.542543Python вызывает `PyState_AddModule` автоматически после импорта модуля, использующего [однофазную инициализацию](https://python-all.ru/3/c-api/extension-modules.html#single-phase-initialization), поэтому вызывать его из кода инициализации модуля не обязательно (но безвредно). Явный вызов требуется только в том случае, если собственный код инициализации модуля впоследствии вызывает `PyState_FindModule`. Функция в основном предназначена для реализации альтернативных механизмов импорта (путём непосредственного вызова или обращения к её реализации за подробностями требуемых обновлений состояния).544545Если модуль был ранее прикреплён с помощью того же *def*, он заменяется новым *module*.546547Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3/glossary.html#term-attached-thread-state).548549Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.550551Добавлено в версии 3.3.552553#### `int PyState_RemoveModule(PyModuleDef *def)`554555*Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.3.*556557Удаляет объект модуля, созданный из *def*, из состояния интерпретатора. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.558559Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3/glossary.html#term-attached-thread-state).560561Добавлено в версии 3.3.562