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

---

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

Есть лишь несколько функций, специфичных для объектов модуля.

**[PyTypeObject](https://python-all.ru/3.4/c-api/type.html#c.PyTypeObject) `PyModule_Type`**

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

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

Возвращает истину, если *p* является объектом модуля или подтипом объекта модуля.

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

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

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

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

Новое в версии 3.3.

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

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

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

Аналогично `PyImport_NewObject()`, но имя – это строка в кодировке UTF-8, а не объект Unicode.

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

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

Возвращает объект словаря, который реализует пространство имён *module*; этот объект совпадает с атрибутом `__dict__` объекта модуля. Эта функция никогда не завершается ошибкой. Расширениям рекомендуется использовать другие `PyModule_*()` и `PyObject_*()` функции, а не напрямую манипулировать `__dict__` модуля.

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

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

Новое в версии 3.3.

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

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

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

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

Новое в версии 3.2.

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

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

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

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

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

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

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

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

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

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

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

Новое в версии 3.3.

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

Удаляет объект модуля, созданный из *def*, из состояния интерпретатора.

Новое в версии 3.3.

## Инициализация C-модулей

Эти функции обычно используются в функции инициализации модуля.

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

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

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

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

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

**`PyModuleDef`**

Эта структура содержит всю информацию, необходимую для создания объекта модуля. Обычно для каждого модуля существует только одна статическая переменная этого типа, которая статически инициализируется и затем передаётся в [`PyModule_Create()`](https://python-all.ru/3.4/c-api/module.html#c.PyModule_Create) в функции инициализации модуля.

**PyModuleDef\_Base `m_base`**

Этот член следует всегда инициализировать значением `PyModuleDef_HEAD_INIT`.

**char\* `m_name`**

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

**char\* `m_doc`**

Докстринг модуля; обычно используется переменная докстринга, созданная с помощью `PyDoc_STRVAR()`.

**Py\_ssize\_t `m_size`**

Некоторые модули допускают повторную инициализацию (вызов их функции `PyInit_*` более одного раза). Такие модули должны хранить своё состояние в области памяти, выделенной на модуль, которую можно получить с помощью [`PyModule_GetState()`](https://python-all.ru/3.4/c-api/module.html#c.PyModule_GetState).

Эту память следует использовать для хранения состояния модуля вместо статических глобальных переменных, так как в таком случае она безопасна для использования в нескольких под-интерпретаторах. Она освобождается при удалении объекта модуля после вызова функции `m_free`, если она присутствует.

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

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

**[PyMethodDef](https://python-all.ru/3.4/c-api/structures.html#c.PyMethodDef)\* `m_methods`**

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

**[inquiry](https://python-all.ru/3.4/c-api/gcsupport.html#c.inquiry) `m_reload`**

В настоящее время не используется, должно быть *NULL*.

**[traverseproc](https://python-all.ru/3.4/c-api/gcsupport.html#c.traverseproc) `m_traverse`**

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

**[inquiry](https://python-all.ru/3.4/c-api/gcsupport.html#c.inquiry) `m_clear`**

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

**freefunc `m_free`**

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

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

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

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

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

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

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

#### `int PyModule_AddIntMacro(PyObject *module, macro)`

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

#### `int PyModule_AddStringMacro(PyObject *module, macro)`

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