> **Источник:** https://python-all.ru/3.14/c-api/module.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Объекты модулей

#### `PyTypeObject PyModule_Type`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.14/c-api/type.html#c.PyTypeObject) представляет тип Python-модуля. Он доступен программам Python как [`types.ModuleType`](https://python-all.ru/3.14/library/types.html#types.ModuleType).

#### `int PyModule_Check(PyObject *p)`

Возвращает истину, если *p* – объект модуля или подтип объекта модуля. Эта функция всегда выполняется успешно.

#### `int PyModule_CheckExact(PyObject *p)`

Возвращает истину, если *p* – объект модуля, но не подтип [`PyModule_Type`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_Type). Эта функция всегда выполняется успешно.

#### `PyObject *PyModule_NewObject(PyObject *name)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.7.*

Возвращает новый объект модуля с [`module.__name__`](https://python-all.ru/3.14/reference/datamodel.html#module.__name__), установленным в *name*. Атрибуты модуля `__name__`, [`__doc__`](https://python-all.ru/3.14/reference/datamodel.html#module.__doc__), [`__package__`](https://python-all.ru/3.14/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3.14/reference/datamodel.html#module.__loader__) заполняются (все, кроме `__name__`, устанавливаются в `None`). Вызывающий отвечает за установку атрибута [`__file__`](https://python-all.ru/3.14/reference/datamodel.html#module.__file__).

Возвращает `NULL` с установленным исключением в случае ошибки.

Добавлено в версии 3.3.

Изменено в версии 3.4: [`__package__`](https://python-all.ru/3.14/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3.14/reference/datamodel.html#module.__loader__) теперь устанавливаются в `None`.

#### `PyObject *PyModule_New(const char *name)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Аналогично [`PyModule_NewObject()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_NewObject), но имя – строка в кодировке UTF-8, а не объект Unicode.

#### `PyObject *PyModule_GetDict(PyObject *module)`

*Возвращаемое значение: заимствованная ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Возвращает объект словаря, реализующий пространство имён *module*; этот объект совпадает с атрибутом [`__dict__`](https://python-all.ru/3.14/reference/datamodel.html#object.__dict__) объекта модуля. Если *module* не является объектом модуля (или подтипом объекта модуля), возбуждается [`SystemError`](https://python-all.ru/3.14/library/exceptions.html#SystemError) и возвращается `NULL`.

Расширениям рекомендуется использовать другие функции `PyModule_*` и `PyObject_*` вместо прямого манипулирования [`__dict__`](https://python-all.ru/3.14/reference/datamodel.html#object.__dict__) модуля.

Возвращаемая ссылка является заимствованной из модуля; она действительна до тех пор, пока модуль не будет уничтожен.

#### `PyObject *PyModule_GetNameObject(PyObject *module)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.7.*

Возвращает значение [`__name__`](https://python-all.ru/3.14/reference/datamodel.html#module.__name__) для *module*. Если модуль не предоставляет такого значения или оно не является строкой, возбуждается [`SystemError`](https://python-all.ru/3.14/library/exceptions.html#SystemError) и возвращается `NULL`.

Добавлено в версии 3.3.

#### `const char *PyModule_GetName(PyObject *module)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Аналогично [`PyModule_GetNameObject()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_GetNameObject), но возвращает имя, закодированное в `'utf-8'`.

Возвращаемый буфер действителен только до тех пор, пока модуль не переименован или не уничтожен. Обратите внимание, что код Python может переименовать модуль, установив его атрибут [`__name__`](https://python-all.ru/3.14/reference/datamodel.html#module.__name__).

#### `void *PyModule_GetState(PyObject *module)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или `NULL`. См. [`PyModuleDef.m_size`](https://python-all.ru/3.14/c-api/module.html#c.PyModuleDef.m_size).

#### `PyModuleDef *PyModule_GetDef(PyObject *module)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Возвращает указатель на структуру [`PyModuleDef`](https://python-all.ru/3.14/c-api/module.html#c.PyModuleDef), из которой был создан модуль, или `NULL`, если модуль не был создан из определения.

В случае ошибки возвращает `NULL` с установленным исключением. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.14/c-api/exceptions.html#c.PyErr_Occurred), чтобы отличить этот случай от отсутствия `PyModuleDef`.

#### `PyObject *PyModule_GetFilenameObject(PyObject *module)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Возвращает имя файла, из которого был загружен *module*, используя атрибут [`__file__`](https://python-all.ru/3.14/reference/datamodel.html#module.__file__) модуля *module*. Если он не определён или не является строкой, возбуждает [`SystemError`](https://python-all.ru/3.14/library/exceptions.html#SystemError) и возвращает `NULL`; в противном случае возвращает ссылку на объект Unicode.

Добавлено в версии 3.2.

#### `const char *PyModule_GetFilename(PyObject *module)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Аналогично [`PyModule_GetFilenameObject()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_GetFilenameObject), но возвращает имя файла, закодированное в 'utf-8'.

Возвращаемый буфер действителен только до тех пор, пока атрибут [`__file__`](https://python-all.ru/3.14/reference/datamodel.html#module.__file__) модуля не будет переназначен или модуль не будет уничтожен.

Устарело с версии 3.2: [`PyModule_GetFilename()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_GetFilename) возбуждает [`UnicodeEncodeError`](https://python-all.ru/3.14/library/exceptions.html#UnicodeEncodeError) для некодируемых имён файлов; вместо него используйте [`PyModule_GetFilenameObject()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_GetFilenameObject).

# Определения модулей

Функции из предыдущего раздела работают с любым объектом модуля, в том числе с модулями, импортированными из кода Python.

Модули, определённые через C API, обычно используют *определение модуля*, [`PyModuleDef`](https://python-all.ru/3.14/c-api/module.html#c.PyModuleDef) – статически выделенное, неизменное «описание» того, как должен быть создан модуль.

Это определение обычно используется для создания «главного» объекта модуля расширения (см. [Определение модулей расширения](https://python-all.ru/3.14/c-api/extension-modules.html#extension-modules)). Оно также используется для [динамического создания модулей расширения](https://python-all.ru/3.14/c-api/module.html#moduledef-dynamic).

В отличие от [`PyModule_New()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_New), определение позволяет управлять *состоянием модуля* – областью памяти, которая выделяется и очищается вместе с объектом модуля. В отличие от атрибутов модуля Python, код Python не может заменить или удалить данные, хранящиеся в состоянии модуля.

#### `type PyModuleDef`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) (включая все члены).*

Структура определения модуля, содержащая всю информацию, необходимую для создания объекта модуля. Эта структура должна быть статически выделена (или иным образом гарантированно оставаться корректной, пока существуют созданные на её основе модули). Обычно для каждого модуля расширения существует только одна переменная такого типа.

#### `PyModuleDef_Base m_base`

Всегда инициализируйте этот элемент значением `PyModuleDef_HEAD_INIT`.

#### `const char *m_name`

Имя нового модуля.

#### `const char *m_doc`

Докстринг для модуля; обычно используется переменная докстринга, созданная с помощью [`PyDoc_STRVAR`](https://python-all.ru/3.14/c-api/intro.html#c.PyDoc_STRVAR).

#### `Py_ssize_t m_size`

Состояние модуля может храниться в выделенной под каждый модуль области памяти, доступ к которой можно получить через [`PyModule_GetState()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_GetState), а не в статических глобальных переменных. Это делает модули безопасными для использования в нескольких под-интерпретаторах.

Эта область памяти выделяется на основе *m\_size* при создании модуля и освобождается при удалении объекта модуля, после вызова функции [`m_free`](https://python-all.ru/3.14/c-api/module.html#c.PyModuleDef.m_free) (если она присутствует).

Установка неотрицательного значения означает, что модуль можно переинициализировать, и задаёт дополнительный объём памяти, необходимый для его состояния.

Установка `m_size` в `-1` означает, что модуль не поддерживает под-интерпретаторы, поскольку у него глобальное состояние. Отрицательное `m_size` допускается только при использовании [устаревшей однофазной инициализации](https://python-all.ru/3.14/c-api/extension-modules.html#single-phase-initialization) или при [динамическом создании модулей](https://python-all.ru/3.14/c-api/module.html#moduledef-dynamic).

Подробнее см. [**PEP 3121**](https://python-all.ru/3.14/c-api/module.html).

#### `PyMethodDef *m_methods`

Указатель на таблицу функций уровня модуля, описываемых значениями [`PyMethodDef`](https://python-all.ru/3.14/c-api/structures.html#c.PyMethodDef). Может быть `NULL`, если функции отсутствуют.

#### `PyModuleDef_Slot *m_slots`

Массив определений слотов для многофазной инициализации, завершающийся записью `{0, NULL}`. При использовании устаревшей однофазной инициализации *m\_slots* должен быть `NULL`.

Изменено в версии 3.5: До версии 3.5 этот элемент всегда устанавливался в `NULL`, и определялся как:

> #### `inquiry m_reload`

#### `traverseproc m_traverse`

Функция обхода, вызываемая при GC-обходе объекта модуля, или `NULL`, если она не нужна.

Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.14/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3.14/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_GetState)) равно `NULL`.

Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.

#### `inquiry m_clear`

Функция очистки, вызываемая при GC-очистке объекта модуля, или `NULL`, если она не нужна.

Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.14/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3.14/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_GetState)) равно `NULL`.

Как и [`PyTypeObject.tp_clear`](https://python-all.ru/3.14/c-api/typeobj.html#c.PyTypeObject.tp_clear), эта функция вызывается не *всегда* перед освобождением модуля. Например, когда подсчёта ссылок достаточно, чтобы определить, что объект больше не используется, циклический сборщик мусора не задействуется, и [`m_free`](https://python-all.ru/3.14/c-api/module.html#c.PyModuleDef.m_free) вызывается напрямую.

Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.

#### `freefunc m_free`

Функция, вызываемая при освобождении объекта модуля, или `NULL`, если она не нужна.

Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.14/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3.14/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_GetState)) равно `NULL`.

Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.

#### `PyTypeObject PyModuleDef_Type`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.5.*

Тип объектов `PyModuleDef`.

## Слоты модуля

#### `type PyModuleDef_Slot`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) (включая все элементы) начиная с версии 3.5.*

#### `int slot`

Идентификатор слота, выбираемый из доступных значений, описанных ниже.

#### `void *value`

Значение слота, смысл которого зависит от идентификатора слота.

Добавлено в версии 3.5.

Доступны следующие типы слотов:

#### `Py_mod_create`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.5.*

Задаёт функцию, которая вызывается для создания самого объекта модуля. Указатель *value* этого слота должен указывать на функцию со следующей сигнатурой:

#### `PyObject *create_module(PyObject *spec, PyModuleDef *def)`

Функция получает экземпляр [`ModuleSpec`](https://python-all.ru/3.14/library/importlib.html#importlib.machinery.ModuleSpec), как определено в [**PEP 451**](https://python-all.ru/3.14/c-api/module.html), и определение модуля. Она должна вернуть новый объект модуля или установить ошибку и вернуть `NULL`.

Эта функция должна быть минимальной. В частности, она не должна вызывать произвольный код Python, так как повторная попытка импорта того же модуля может привести к бесконечному циклу.

В одном определении модуля нельзя задавать несколько слотов `Py_mod_create`.

Если `Py_mod_create` не указан, механизм импорта создаст обычный объект модуля с помощью [`PyModule_New()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_New). Имя берётся из *spec*, а не из определения, чтобы расширения могли динамически подстраиваться под своё место в иерархии модулей и импортироваться под другими именами через симлинки, оставаясь привязанными к одному определению модуля.

Возвращаемый объект не обязан быть экземпляром [`PyModule_Type`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_Type). Можно использовать любой тип, если он поддерживает установку и получение атрибутов, связанных с импортом. Однако только экземпляры `PyModule_Type` могут быть возвращены, если `PyModuleDef` содержит ненулевые `NULL` `m_traverse`, `m_clear`, `m_free`; ненулевой `m_size`; или слоты, отличные от `Py_mod_create`.

Добавлено в версии 3.5.

#### `Py_mod_exec`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.5.*

Задаёт функцию, которая вызывается для *выполнения* модуля. Это эквивалентно выполнению кода модуля Python: обычно эта функция добавляет в модуль классы и константы. Сигнатура функции такова:

#### `int exec_module(PyObject *module)`

Если указано несколько слотов `Py_mod_exec`, они обрабатываются в том порядке, в котором расположены в массиве *m\_slots*.

Добавлено в версии 3.5.

#### `Py_mod_multiple_interpreters`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.12.*

Задаёт одно из следующих значений:

#### `Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`

Модуль не поддерживает импорт в подынтерпретаторах.

#### `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`

Модуль поддерживает импорт в подынтерпретаторах, но только если они используют общий GIL основного интерпретатора. (См. [Изоляция модулей расширения](https://python-all.ru/3.14/howto/isolating-extensions.html#isolating-extensions-howto).)

#### `Py_MOD_PER_INTERPRETER_GIL_SUPPORTED`

Модуль поддерживает импорт в подынтерпретаторах, даже если у них собственный GIL. (См. [Изоляция модулей расширения](https://python-all.ru/3.14/howto/isolating-extensions.html#isolating-extensions-howto).)

Этот слот определяет, будет ли импорт этого модуля в подынтерпретаторе завершаться ошибкой.

В одном определении модуля нельзя указывать несколько слотов `Py_mod_multiple_interpreters`.

Если `Py_mod_multiple_interpreters` не указан, механизм импорта по умолчанию использует `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`.

Добавлено в версии 3.12.

#### `Py_mod_gil`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable), начиная с версии 3.13.*

Задаёт одно из следующих значений:

#### `Py_MOD_GIL_USED`

Модуль зависит от наличия глобальной блокировки интерпретатора (GIL), и может обращаться к глобальному состоянию без синхронизации.

#### `Py_MOD_GIL_NOT_USED`

Модуль можно безопасно использовать без активного GIL.

Этот слот игнорируется сборками Python, не настроенными с [`--disable-gil`](https://python-all.ru/3.14/using/configure.html#cmdoption-disable-gil). В противном случае он определяет, приведёт ли импорт этого модуля к автоматическому включению GIL. Подробнее см. [Free-threaded CPython](https://python-all.ru/3.14/whatsnew/3.13.html#whatsnew313-free-threaded-cpython).

В одном определении модуля нельзя указывать несколько слотов `Py_mod_gil`.

Если `Py_mod_gil` не указан, механизм импорта по умолчанию использует `Py_MOD_GIL_USED`.

Добавлено в версии 3.13.

# Создание модулей расширения динамически

Следующие функции можно использовать для создания модуля за пределами [инициализирующей функции расширения](https://python-all.ru/3.14/c-api/extension-modules.html#extension-export-hook). Они также используются в [однофазной инициализации](https://python-all.ru/3.14/c-api/extension-modules.html#single-phase-initialization).

#### `PyObject *PyModule_Create(PyModuleDef *def)`

*Возвращаемое значение: новая ссылка.*

Создаёт новый объект модуля на основе определения в *def*. Это макрос, который вызывает [`PyModule_Create2()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_Create2) с *module\_api\_version*, установленным в [`PYTHON_API_VERSION`](https://python-all.ru/3.14/c-api/module.html#c.PYTHON_API_VERSION), или в [`PYTHON_ABI_VERSION`](https://python-all.ru/3.14/c-api/module.html#c.PYTHON_ABI_VERSION), если используется [ограниченный API](https://python-all.ru/3.14/c-api/stable.html#limited-c-api).

#### `PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Создаёт новый объект модуля на основе определения в *def*, предполагая версию API *module\_api\_version*. Если эта версия не совпадает с версией работающего интерпретатора, генерируется [`RuntimeWarning`](https://python-all.ru/3.14/library/exceptions.html#RuntimeWarning).

Возвращает `NULL` с установленным исключением в случае ошибки.

Эта функция не поддерживает слоты. Элемент [`m_slots`](https://python-all.ru/3.14/c-api/module.html#c.PyModuleDef.m_slots) структуры *def* должен быть равен `NULL`.

> **Примечание**
>
> В большинстве случаев вместо этой функции следует использовать [`PyModule_Create()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_Create); используйте её, только если точно уверены, что она нужна.

#### `PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)`

*Возвращаемое значение: новая ссылка.*

Этот макрос вызывает [`PyModule_FromDefAndSpec2()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_FromDefAndSpec2) с *module\_api\_version*, установленным в [`PYTHON_API_VERSION`](https://python-all.ru/3.14/c-api/module.html#c.PYTHON_API_VERSION), или в [`PYTHON_ABI_VERSION`](https://python-all.ru/3.14/c-api/module.html#c.PYTHON_ABI_VERSION), если используется [ограниченный API](https://python-all.ru/3.14/c-api/stable.html#limited-c-api).

Добавлено в версии 3.5.

#### `PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)`

*Возвращаемое значение: новая ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.7.*

Создает новый объект модуля по определению из *def* и ModuleSpec *spec*, используя версию API *module\_api\_version*. Если эта версия не соответствует версии работающего интерпретатора, выдается [`RuntimeWarning`](https://python-all.ru/3.14/library/exceptions.html#RuntimeWarning).

Возвращает `NULL` с установленным исключением в случае ошибки.

Обратите внимание, что это не обрабатывает слоты выполнения ([`Py_mod_exec`](https://python-all.ru/3.14/c-api/module.html#c.Py_mod_exec)). Для полной инициализации модуля необходимо вызвать как `PyModule_FromDefAndSpec`, так и `PyModule_ExecDef`.

> **Примечание**
>
> В большинстве случаев вместо этой функции следует использовать [`PyModule_FromDefAndSpec()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_FromDefAndSpec); используйте её, только если точно уверены, что она нужна.

Добавлено в версии 3.5.

#### `int PyModule_ExecDef(PyObject *module, PyModuleDef *def)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.7.*

Обрабатывает любые слоты выполнения ([`Py_mod_exec`](https://python-all.ru/3.14/c-api/module.html#c.Py_mod_exec)), заданные в *def*.

Добавлено в версии 3.5.

#### `PYTHON_API_VERSION`

Версия C API. Определяется для обратной совместимости.

В настоящее время эта константа не обновляется в новых версиях Python и не полезна для версионирования. В будущем это может измениться.

#### `PYTHON_ABI_VERSION`

Определяется как `3` для обратной совместимости.

В настоящее время эта константа не обновляется в новых версиях Python и не полезна для версионирования. В будущем это может измениться.

# Вспомогательные функции

Следующие функции предназначены для инициализации состояния модуля. Они используются в слотах выполнения модуля ([`Py_mod_exec`](https://python-all.ru/3.14/c-api/module.html#c.Py_mod_exec)), в инициализирующей функции для устаревшей [однофазной инициализации](https://python-all.ru/3.14/c-api/extension-modules.html#single-phase-initialization) или в коде, динамически создающем модули.

#### `int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.10.*

Добавляет объект в *module* как *name*. Это удобная функция, которую можно использовать из функции инициализации модуля.

При успехе возвращает `0`. При ошибке вызывает исключение и возвращает `-1`.

Пример использования:

```c
static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (obj == NULL) {
        return -1;
    }
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_DECREF(obj);
    return res;
 }
```

Для удобства функция принимает `NULL` *value* с установленным исключением. В этом случае возвращает `-1` и просто оставляет вызванное исключение без изменений.

Пример можно также написать без явной проверки, что *obj* равен `NULL`:

```c
static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_XDECREF(obj);
    return res;
 }
```

Обратите внимание, что в этом случае следует использовать `Py_XDECREF()` вместо `Py_DECREF()`, поскольку *obj* может быть `NULL`.

Количество различных строк *name*, передаваемых этой функции, должно быть небольшим – обычно используйте только статически выделенные строки в качестве *name*. Для имен, неизвестных во время компиляции, предпочтительнее вызывать [`PyUnicode_FromString()`](https://python-all.ru/3.14/c-api/unicode.html#c.PyUnicode_FromString) и [`PyObject_SetAttr()`](https://python-all.ru/3.14/c-api/object.html#c.PyObject_SetAttr) напрямую. Подробнее см. [`PyUnicode_InternFromString()`](https://python-all.ru/3.14/c-api/unicode.html#c.PyUnicode_InternFromString), который может использоваться внутри для создания объекта ключа.

Добавлено в версии 3.10.

#### `int PyModule_Add(PyObject *module, const char *name, PyObject *value)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable), начиная с версии 3.13.*

Похожа на [`PyModule_AddObjectRef()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_AddObjectRef), но “[крадет](https://python-all.ru/3.14/glossary.html#term-steal)” ссылку на *value* (даже при ошибке). Её можно вызывать с результатом функции, возвращающей новую ссылку, не беспокоясь о проверке результата или даже сохранении его в переменную.

Пример использования:

```c
if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
    goto error;
}
```

Добавлено в версии 3.13.

#### `int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Похоже на [`PyModule_AddObjectRef()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_AddObjectRef), но при успехе [присваивает](https://python-all.ru/3.14/glossary.html#term-steal) ссылку на *value* (если возвращает `0`).

Рекомендуются новые функции [`PyModule_Add()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_Add) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_AddObjectRef), поскольку неправильное использование [`PyModule_AddObject()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_AddObject) может легко привести к утечкам ссылок.

> **Примечание**
>
> В отличие от других функций, крадущих ссылки, `PyModule_AddObject()` освобождает ссылку на *value* **только при успехе**.
>
> Это означает, что возвращаемое значение необходимо проверять, а код вызова должен вручную [`Py_XDECREF()`](https://python-all.ru/3.14/c-api/refcounting.html#c.Py_XDECREF) *value* при ошибке.

Пример использования:

```c
PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
    // Если 'obj' не NULL и PyModule_AddObject() завершился неудачей,
    // сильную ссылку 'obj' необходимо удалить с помощью Py_XDECREF().
    // Если 'obj' равен NULL, Py_XDECREF() ничего не делает.
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() перехватил ссылку на obj:
// Py_XDECREF(obj) здесь не требуется.
```

[Мягкое устаревание](https://python-all.ru/3.14/glossary.html#term-soft-deprecated) начиная с версии 3.13.

#### `int PyModule_AddIntConstant(PyObject *module, const char *name, long value)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Добавляет целочисленную константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.

Это удобная функция, которая вызывает [`PyLong_FromLong()`](https://python-all.ru/3.14/c-api/long.html#c.PyLong_FromLong) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.

#### `int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Добавляет строковую константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Строка *value* должна быть завершена символами `NULL`. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.

Это удобная функция, которая вызывает [`PyUnicode_InternFromString()`](https://python-all.ru/3.14/c-api/unicode.html#c.PyUnicode_InternFromString) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.14/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.

#### `PyModule_AddIntMacro(module, macro)`

Добавляет целочисленную константу в *module*. Имя и значение берутся из *macro*. Например, `PyModule_AddIntMacro(module, AF_INET)` добавляет целочисленную константу *AF\_INET* со значением *AF\_INET* в *module*. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.

#### `PyModule_AddStringMacro(module, macro)`

Добавляет строковую константу в *module*.

#### `int PyModule_AddType(PyObject *module, PyTypeObject *type)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.10.*

Добавляет объект типа в *module*. Объект типа финализируется внутренним вызовом [`PyType_Ready()`](https://python-all.ru/3.14/c-api/type.html#c.PyType_Ready). Имя объекта типа берётся из последнего компонента [`tp_name`](https://python-all.ru/3.14/c-api/typeobj.html#c.PyTypeObject.tp_name) после точки. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.

Добавлено в версии 3.9.

#### `int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.7.*

Добавляет функции из массива *functions*, завершённого `NULL`, в *module*. Подробнее об отдельных записях см. документацию [`PyMethodDef`](https://python-all.ru/3.14/c-api/structures.html#c.PyMethodDef) (из-за отсутствия общего пространства имён модуля функции уровня модуля, реализованные на C, обычно получают модуль в качестве первого параметра, что делает их похожими на методы экземпляров классов Python).

Эта функция вызывается автоматически при создании модуля из `PyModuleDef` (например, при использовании [многофазной инициализации](https://python-all.ru/3.14/c-api/extension-modules.html#multi-phase-initialization), `PyModule_Create` или `PyModule_FromDefAndSpec`). Некоторые авторы модулей могут предпочитать определять функции в нескольких массивах [`PyMethodDef`](https://python-all.ru/3.14/c-api/structures.html#c.PyMethodDef); в этом случае им следует вызывать эту функцию напрямую.

Массив *functions* должен быть статически выделен (или иным образом гарантированно переживать объект модуля).

Добавлено в версии 3.5.

#### `int PyModule_SetDocString(PyObject *module, const char *docstring)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.7.*

Устанавливает docstring для *module* как *docstring*. Эта функция вызывается автоматически при создании модуля из `PyModuleDef` (например, при использовании [многофазной инициализации](https://python-all.ru/3.14/c-api/extension-modules.html#multi-phase-initialization), `PyModule_Create` или `PyModule_FromDefAndSpec`).

Возвращает `0` при успехе. Возвращает `-1` с установленным исключением при ошибке.

Добавлено в версии 3.5.

#### `int PyUnstable_Module_SetGIL(PyObject *module, void *gil)`

> *Это [нестабильное API](https://python-all.ru/3.14/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*

Указывает, поддерживает ли *module* работу без глобальной блокировки интерпретатора (GIL), используя одно из значений из [`Py_mod_gil`](https://python-all.ru/3.14/c-api/module.html#c.Py_mod_gil). Необходимо вызывать в функции инициализации *module* при использовании [устаревшей однофазной инициализации](https://python-all.ru/3.14/c-api/extension-modules.html#single-phase-initialization). Если эта функция не вызывается во время инициализации модуля, механизм импорта считает, что модуль не поддерживает работу без GIL. Эта функция доступна только в сборках Python, настроенных с [`--disable-gil`](https://python-all.ru/3.14/using/configure.html#cmdoption-disable-gil). Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.

Добавлено в версии 3.13.

## Поиск модуля (однофазная инициализация)

Устаревшая схема [однофазной инициализации](https://python-all.ru/3.14/c-api/extension-modules.html#single-phase-initialization) создаёт модули-одиночки, которые можно найти в контексте текущего интерпретатора. Это позволяет позже получить объект модуля, имея только ссылку на определение модуля.

Эти функции не будут работать с модулями, созданными с помощью многофазной инициализации, поскольку из одного определения можно создать несколько таких модулей.

#### `PyObject *PyState_FindModule(PyModuleDef *def)`

*Возвращаемое значение: заимствованная ссылка.*

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*

Возвращает объект модуля, созданный из *def* для текущего интерпретатора. Этот метод требует, чтобы объект модуля был предварительно прикреплён к состоянию интерпретатора с помощью [`PyState_AddModule()`](https://python-all.ru/3.14/c-api/module.html#c.PyState_AddModule). Если соответствующий объект модуля не найден или ещё не прикреплён к состоянию интерпретатора, он возвращает `NULL`.

#### `int PyState_AddModule(PyObject *module, PyModuleDef *def)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.3.*

Прикрепляет объект модуля, переданный функции, к состоянию интерпретатора. Это позволяет обращаться к объекту модуля через [`PyState_FindModule()`](https://python-all.ru/3.14/c-api/module.html#c.PyState_FindModule).

Действует только на модули, созданные с помощью однофазной инициализации.

Python вызывает `PyState_AddModule` автоматически после импорта модуля, использующего [однофазную инициализацию](https://python-all.ru/3.14/c-api/extension-modules.html#single-phase-initialization), поэтому вызывать его из кода инициализации модуля не обязательно (но безвредно). Явный вызов требуется только в том случае, если собственный код инициализации модуля впоследствии вызывает `PyState_FindModule`. Функция в основном предназначена для реализации альтернативных механизмов импорта (путём непосредственного вызова или обращения к её реализации за подробностями требуемых обновлений состояния).

Если модуль был ранее прикреплён с помощью того же *def*, он заменяется новым *module*.

Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3.14/glossary.html#term-attached-thread-state).

Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.

Добавлено в версии 3.3.

#### `int PyState_RemoveModule(PyModuleDef *def)`

*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.3.*

Удаляет объект модуля, созданный из *def*, из состояния интерпретатора. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.

Вызывающий должен иметь [прикреплённое состояние потока](https://python-all.ru/3.14/glossary.html#term-attached-thread-state).

Добавлено в версии 3.3.