`module.md`

168 строк · 13.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.3/c-api/module.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты модулей89Есть лишь несколько функций, специфичных для объектов модуля.1011**[PyTypeObject](https://python-all.ru/3.3/c-api/type.html#PyTypeObject) `PyModule_Type`**1213Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.3/c-api/type.html#PyTypeObject) представляет тип модуля Python. Он доступен программам на Python как `types.ModuleType`.1415#### `int PyModule_Check(PyObject *p)`1617Возвращает истину, если *p* является объектом модуля или подтипом объекта модуля.1819#### `int PyModule_CheckExact(PyObject *p)`2021Возвращает true, если *p* является объектом модуля, но не подтипом [`PyModule_Type`](https://python-all.ru/3.3/c-api/module.html#PyModule_Type).2223#### `PyObject* PyModule_NewObject(PyObject *name)`2425Возвращает новый объект модуля с атрибутом `__name__`, установленным в *name*. Заполнены только атрибуты модуля `__doc__` и `__name__`; вызывающий отвечает за предоставление атрибута `__file__`.2627Новое в версии 3.3.2829#### `PyObject* PyModule_New(const char *name)`3031*Возвращаемое значение: новая ссылка.*3233Аналогично `PyImport_NewObject()`, но имя – это строка в кодировке UTF-8, а не объект Unicode.3435#### `PyObject* PyModule_GetDict(PyObject *module)`3637*Возвращаемое значение: заимствованная ссылка.*3839Возвращает объект словаря, который реализует пространство имён *module*; этот объект совпадает с атрибутом `__dict__` объекта модуля. Эта функция никогда не завершается ошибкой. Расширениям рекомендуется использовать другие `PyModule_*()` и `PyObject_*()` функции, а не напрямую манипулировать `__dict__` модуля.4041#### `PyObject* PyModule_GetNameObject(PyObject *module)`4243Возвращает значение `__name__` для объекта *module*. Если модуль не предоставляет его или если это не строка, возбуждается [`SystemError`](https://python-all.ru/3.3/library/exceptions.html#SystemError) и возвращается *NULL*.4445Новое в версии 3.3.4647#### `char* PyModule_GetName(PyObject *module)`4849Аналогично [`PyModule_GetNameObject()`](https://python-all.ru/3.3/c-api/module.html#PyModule_GetNameObject), но возвращает имя, закодированное в `'utf-8'`.5051#### `PyObject* PyModule_GetFilenameObject(PyObject *module)`5253Возвращает имя файла, из которого был загружен *module*, используя атрибут `__file__` объекта *module*. Если этот атрибут не определён или не является строкой Unicode, возбуждается [`SystemError`](https://python-all.ru/3.3/library/exceptions.html#SystemError) и возвращается *NULL*; в противном случае возвращается ссылка на объект Unicode.5455Новое в версии 3.2.5657#### `char* PyModule_GetFilename(PyObject *module)`5859Аналогично [`PyModule_GetFilenameObject()`](https://python-all.ru/3.3/c-api/module.html#PyModule_GetFilenameObject), но возвращает имя файла, закодированное в 'utf-8'.6061Устарело с версии 3.2: [`PyModule_GetFilename()`](https://python-all.ru/3.3/c-api/module.html#PyModule_GetFilename) возбуждает `UnicodeEncodeError` для некодируемых имён файлов, используйте вместо неё [`PyModule_GetFilenameObject()`](https://python-all.ru/3.3/c-api/module.html#PyModule_GetFilenameObject).6263#### `void* PyModule_GetState(PyObject *module)`6465Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или *NULL*. См. [`PyModuleDef.m_size`](https://python-all.ru/3.3/c-api/module.html#PyModuleDef.m_size).6667#### `PyModuleDef* PyModule_GetDef(PyObject *module)`6869Возвращает указатель на структуру [`PyModuleDef`](https://python-all.ru/3.3/c-api/module.html#PyModuleDef), из которой был создан модуль, или *NULL*, если модуль не был создан с помощью [`PyModule_Create()`](https://python-all.ru/3.3/c-api/module.html#PyModule_Create).7071#### `PyObject* PyState_FindModule(PyModuleDef *def)`7273Возвращает объект модуля, созданный из *def* для текущего интерпретатора. Этот метод требует, чтобы объект модуля был предварительно присоединён к состоянию интерпретатора с помощью [`PyState_AddModule()`](https://python-all.ru/3.3/c-api/module.html#PyState_AddModule). Если соответствующий объект модуля не найден или ещё не был присоединён к состоянию интерпретатора, возвращается NULL.7475#### `int PyState_AddModule(PyObject *module, PyModuleDef *def)`7677Присоединяет переданный функции объект модуля к состоянию интерпретатора. Это позволяет получить доступ к объекту модуля через [`PyState_FindModule()`](https://python-all.ru/3.3/c-api/module.html#PyState_FindModule).7879Новое в версии 3.3.8081#### `int PyState_RemoveModule(PyModuleDef *def)`8283Удаляет объект модуля, созданный из *def*, из состояния интерпретатора.8485Новое в версии 3.3.8687## Инициализация C-модулей8889Эти функции обычно используются в функции инициализации модуля.9091#### `PyObject* PyModule_Create(PyModuleDef *module)`9293Создаёт новый объект модуля по определению в *module*. Работает как [`PyModule_Create2()`](https://python-all.ru/3.3/c-api/module.html#PyModule_Create2), где *module\_api\_version* установлено в `PYTHON_API_VERSION`.9495#### `PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)`9697Создаёт новый объект модуля по определению в *module*, принимая версию API *module\_api\_version*. Если эта версия не совпадает с версией работающего интерпретатора, выдаётся [`RuntimeWarning`](https://python-all.ru/3.3/library/exceptions.html#RuntimeWarning).9899> **Примечание**100>101> В большинстве случаев следует использовать [`PyModule_Create()`](https://python-all.ru/3.3/c-api/module.html#PyModule_Create); используйте эту функцию, только если уверены, что она нужна.102103**`PyModuleDef`**104105Эта структура содержит всю информацию, необходимую для создания объекта модуля. Обычно для каждого модуля существует только одна статическая переменная этого типа, которая статически инициализируется и затем передаётся в [`PyModule_Create()`](https://python-all.ru/3.3/c-api/module.html#PyModule_Create) в функции инициализации модуля.106107**PyModuleDef\_Base `m_base`**108109Этот член следует всегда инициализировать значением `PyModuleDef_HEAD_INIT`.110111**char\* `m_name`**112113Имя нового модуля.114115**char\* `m_doc`**116117Докстринг модуля; обычно используется переменная докстринга, созданная с помощью `PyDoc_STRVAR()`.118119**Py\_ssize\_t `m_size`**120121Некоторые модули допускают повторную инициализацию (вызов их функции `PyInit_*` более одного раза). Такие модули должны хранить своё состояние в области памяти, выделенной на модуль, которую можно получить с помощью [`PyModule_GetState()`](https://python-all.ru/3.3/c-api/module.html#PyModule_GetState).122123Эту память следует использовать для хранения состояния модуля вместо статических глобальных переменных, так как в таком случае она безопасна для использования в нескольких под-интерпретаторах. Она освобождается при удалении объекта модуля после вызова функции `m_free`, если она присутствует.124125Установка `m_size` в `-1` означает, что модуль не может быть повторно инициализирован, поскольку у него есть глобальное состояние. Установка неотрицательного значения означает, что модуль может быть повторно инициализирован, и указывает дополнительный объём памяти, необходимый для его состояния.126127Подробнее см. [**PEP 3121**](https://python-all.ru/3.3/c-api/module.html).128129**[PyMethodDef](https://python-all.ru/3.3/c-api/structures.html#PyMethodDef)\* `m_methods`**130131Указатель на таблицу функций уровня модуля, описываемую значениями [`PyMethodDef`](https://python-all.ru/3.3/c-api/structures.html#PyMethodDef). Может быть *NULL*, если функции отсутствуют.132133**[inquiry](https://python-all.ru/3.3/c-api/gcsupport.html#inquiry) `m_reload`**134135В настоящее время не используется, должно быть *NULL*.136137**[traverseproc](https://python-all.ru/3.3/c-api/gcsupport.html#traverseproc) `m_traverse`**138139Функция обхода, вызываемая во время GC-обхода объекта модуля, или *NULL*, если не требуется.140141**[inquiry](https://python-all.ru/3.3/c-api/gcsupport.html#inquiry) `m_clear`**142143Функция очистки, вызываемая во время GC-очистки объекта модуля, или *NULL*, если не требуется.144145**freefunc `m_free`**146147Функция, вызываемая при освобождении объекта модуля, или *NULL*, если не требуется.148149#### `int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)`150151Добавляет объект в *module* под именем *name*. Это удобная функция, которую можно использовать в функции инициализации модуля. Она похищает ссылку на *value*. Возвращает `-1` при ошибке, `0` при успехе.152153#### `int PyModule_AddIntConstant(PyObject *module, const char *name, long value)`154155Добавляет целочисленную константу в модуль *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Возвращает `-1` в случае ошибки, `0` при успешном выполнении.156157#### `int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)`158159Добавляет строковую константу в *module* под именем *name*. Эту вспомогательную функцию можно использовать в функции инициализации модуля. Строка *value* должна завершаться нулевым символом. Возвращает `-1` при ошибке, `0` при успехе.160161#### `int PyModule_AddIntMacro(PyObject *module, macro)`162163Добавляет целочисленную константу в *module*. Имя и значение берутся из *macro*. Например, `PyModule_AddIntMacro(module, AF_INET)` добавляет целочисленную константу *AF\_INET* со значением *AF\_INET* в *module*. Возвращает `-1` при ошибке, `0` при успехе.164165#### `int PyModule_AddStringMacro(PyObject *module, macro)`166167Добавляет строковую константу в *module*.168