`module.md`

170 строк · 14.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.4/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.4/c-api/type.html#c.PyTypeObject) `PyModule_Type`**1213Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.4/c-api/type.html#c.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.4/c-api/module.html#c.PyModule_Type).2223#### `PyObject* PyModule_NewObject(PyObject *name)`2425Возвращает новый объект модуля, у которого атрибут [`__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__).2627Новое в версии 3.3.2829Изменено в версии 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`.3031#### `PyObject* PyModule_New(const char *name)`3233*Возвращаемое значение: новая ссылка.*3435Аналогично `PyImport_NewObject()`, но имя – это строка в кодировке UTF-8, а не объект Unicode.3637#### `PyObject* PyModule_GetDict(PyObject *module)`3839*Возвращаемое значение: заимствованная ссылка.*4041Возвращает объект словаря, который реализует пространство имён *module*; этот объект совпадает с атрибутом `__dict__` объекта модуля. Эта функция никогда не завершается ошибкой. Расширениям рекомендуется использовать другие `PyModule_*()` и `PyObject_*()` функции, а не напрямую манипулировать `__dict__` модуля.4243#### `PyObject* PyModule_GetNameObject(PyObject *module)`4445Возвращает значение [`__name__`](https://python-all.ru/3.4/reference/import.html#__name__) модуля *module*. Если модуль не предоставляет его, или если это не строка, возбуждается [`SystemError`](https://python-all.ru/3.4/library/exceptions.html#SystemError) и возвращается *NULL*.4647Новое в версии 3.3.4849#### `char* PyModule_GetName(PyObject *module)`5051Аналогично [`PyModule_GetNameObject()`](https://python-all.ru/3.4/c-api/module.html#c.PyModule_GetNameObject), но возвращает имя, закодированное в `'utf-8'`.5253#### `PyObject* PyModule_GetFilenameObject(PyObject *module)`5455Возвращает имя файла, из которого был загружен *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.5657Новое в версии 3.2.5859#### `char* PyModule_GetFilename(PyObject *module)`6061Аналогично [`PyModule_GetFilenameObject()`](https://python-all.ru/3.4/c-api/module.html#c.PyModule_GetFilenameObject), но возвращает имя файла, закодированное в 'utf-8'.6263Устарело с версии 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).6465#### `void* PyModule_GetState(PyObject *module)`6667Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или *NULL*. См. [`PyModuleDef.m_size`](https://python-all.ru/3.4/c-api/module.html#c.PyModuleDef.m_size).6869#### `PyModuleDef* PyModule_GetDef(PyObject *module)`7071Возвращает указатель на структуру [`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).7273#### `PyObject* PyState_FindModule(PyModuleDef *def)`7475Возвращает объект модуля, созданный из *def* для текущего интерпретатора. Этот метод требует, чтобы объект модуля был предварительно присоединён к состоянию интерпретатора с помощью [`PyState_AddModule()`](https://python-all.ru/3.4/c-api/module.html#c.PyState_AddModule). Если соответствующий объект модуля не найден или ещё не был присоединён к состоянию интерпретатора, возвращается NULL.7677#### `int PyState_AddModule(PyObject *module, PyModuleDef *def)`7879Присоединяет переданный функции объект модуля к состоянию интерпретатора. Это позволяет получить доступ к объекту модуля через [`PyState_FindModule()`](https://python-all.ru/3.4/c-api/module.html#c.PyState_FindModule).8081Новое в версии 3.3.8283#### `int PyState_RemoveModule(PyModuleDef *def)`8485Удаляет объект модуля, созданный из *def*, из состояния интерпретатора.8687Новое в версии 3.3.8889## Инициализация C-модулей9091Эти функции обычно используются в функции инициализации модуля.9293#### `PyObject* PyModule_Create(PyModuleDef *module)`9495Создаёт новый объект модуля по определению в *module*. Работает как [`PyModule_Create2()`](https://python-all.ru/3.4/c-api/module.html#c.PyModule_Create2), где *module\_api\_version* установлено в `PYTHON_API_VERSION`.9697#### `PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)`9899Создаёт новый объект модуля по определению в *module*, принимая версию API *module\_api\_version*. Если эта версия не совпадает с версией работающего интерпретатора, выдаётся [`RuntimeWarning`](https://python-all.ru/3.4/library/exceptions.html#RuntimeWarning).100101> **Примечание**102>103> В большинстве случаев следует использовать [`PyModule_Create()`](https://python-all.ru/3.4/c-api/module.html#c.PyModule_Create); используйте эту функцию, только если уверены, что она нужна.104105**`PyModuleDef`**106107Эта структура содержит всю информацию, необходимую для создания объекта модуля. Обычно для каждого модуля существует только одна статическая переменная этого типа, которая статически инициализируется и затем передаётся в [`PyModule_Create()`](https://python-all.ru/3.4/c-api/module.html#c.PyModule_Create) в функции инициализации модуля.108109**PyModuleDef\_Base `m_base`**110111Этот член следует всегда инициализировать значением `PyModuleDef_HEAD_INIT`.112113**char\* `m_name`**114115Имя нового модуля.116117**char\* `m_doc`**118119Докстринг модуля; обычно используется переменная докстринга, созданная с помощью `PyDoc_STRVAR()`.120121**Py\_ssize\_t `m_size`**122123Некоторые модули допускают повторную инициализацию (вызов их функции `PyInit_*` более одного раза). Такие модули должны хранить своё состояние в области памяти, выделенной на модуль, которую можно получить с помощью [`PyModule_GetState()`](https://python-all.ru/3.4/c-api/module.html#c.PyModule_GetState).124125Эту память следует использовать для хранения состояния модуля вместо статических глобальных переменных, так как в таком случае она безопасна для использования в нескольких под-интерпретаторах. Она освобождается при удалении объекта модуля после вызова функции `m_free`, если она присутствует.126127Установка `m_size` в `-1` означает, что модуль не может быть повторно инициализирован, поскольку у него есть глобальное состояние. Установка неотрицательного значения означает, что модуль может быть повторно инициализирован, и указывает дополнительный объём памяти, необходимый для его состояния.128129Подробнее см. [**PEP 3121**](https://python-all.ru/3.4/c-api/module.html).130131**[PyMethodDef](https://python-all.ru/3.4/c-api/structures.html#c.PyMethodDef)\* `m_methods`**132133Указатель на таблицу функций уровня модуля, описываемую значениями [`PyMethodDef`](https://python-all.ru/3.4/c-api/structures.html#c.PyMethodDef). Может быть *NULL*, если функции отсутствуют.134135**[inquiry](https://python-all.ru/3.4/c-api/gcsupport.html#c.inquiry) `m_reload`**136137В настоящее время не используется, должно быть *NULL*.138139**[traverseproc](https://python-all.ru/3.4/c-api/gcsupport.html#c.traverseproc) `m_traverse`**140141Функция обхода, вызываемая во время GC-обхода объекта модуля, или *NULL*, если не требуется.142143**[inquiry](https://python-all.ru/3.4/c-api/gcsupport.html#c.inquiry) `m_clear`**144145Функция очистки, вызываемая во время GC-очистки объекта модуля, или *NULL*, если не требуется.146147**freefunc `m_free`**148149Функция, вызываемая при освобождении объекта модуля, или *NULL*, если не требуется.150151#### `int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)`152153Добавляет объект в *module* под именем *name*. Это удобная функция, которую можно использовать в функции инициализации модуля. Она похищает ссылку на *value*. Возвращает `-1` при ошибке, `0` при успехе.154155#### `int PyModule_AddIntConstant(PyObject *module, const char *name, long value)`156157Добавляет целочисленную константу в модуль *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Возвращает `-1` в случае ошибки, `0` при успешном выполнении.158159#### `int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)`160161Добавляет строковую константу в *module* под именем *name*. Эту вспомогательную функцию можно использовать в функции инициализации модуля. Строка *value* должна завершаться нулевым символом. Возвращает `-1` при ошибке, `0` при успехе.162163#### `int PyModule_AddIntMacro(PyObject *module, macro)`164165Добавляет целочисленную константу в *module*. Имя и значение берутся из *macro*. Например, `PyModule_AddIntMacro(module, AF_INET)` добавляет целочисленную константу *AF\_INET* со значением *AF\_INET* в *module*. Возвращает `-1` при ошибке, `0` при успехе.166167#### `int PyModule_AddStringMacro(PyObject *module, macro)`168169Добавляет строковую константу в *module*.170