`module.md`

576 строк · 50.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/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.13/c-api/stable.html#stable).*1213Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.13/c-api/type.html#c.PyTypeObject) представляет тип Python-модуля. Он доступен программам Python как [`types.ModuleType`](https://python-all.ru/3.13/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.13/c-api/module.html#c.PyModule_Type). Эта функция всегда выполняется успешно.2223#### `PyObject *PyModule_NewObject(PyObject *name)`2425*Возвращаемое значение: новая ссылка.*2627*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*2829Возвращает новый объект модуля с [`module.__name__`](https://python-all.ru/3.13/reference/datamodel.html#module.__name__), установленным в *name*. Атрибуты модуля `__name__`, [`__doc__`](https://python-all.ru/3.13/reference/datamodel.html#module.__doc__), [`__package__`](https://python-all.ru/3.13/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3.13/reference/datamodel.html#module.__loader__) заполняются (все, кроме `__name__`, устанавливаются в `None`). Вызывающий отвечает за установку атрибута [`__file__`](https://python-all.ru/3.13/reference/datamodel.html#module.__file__).3031Возвращает `NULL` с установленным исключением в случае ошибки.3233Добавлено в версии 3.3.3435Изменено в версии 3.4: [`__package__`](https://python-all.ru/3.13/reference/datamodel.html#module.__package__) и [`__loader__`](https://python-all.ru/3.13/reference/datamodel.html#module.__loader__) теперь устанавливаются в `None`.3637#### `PyObject *PyModule_New(const char *name)`3839*Возвращаемое значение: новая ссылка.*4041*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*4243Аналогично [`PyModule_NewObject()`](https://python-all.ru/3.13/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.13/c-api/stable.html#stable).*5051Возвращает объект словаря, реализующий пространство имён *module*; этот объект совпадает с атрибутом [`__dict__`](https://python-all.ru/3.13/reference/datamodel.html#object.__dict__) объекта модуля. Если *module* не является объектом модуля (или подтипом объекта модуля), возбуждается [`SystemError`](https://python-all.ru/3.13/library/exceptions.html#SystemError) и возвращается `NULL`.5253Расширениям рекомендуется использовать другие функции `PyModule_*` и `PyObject_*` вместо прямого манипулирования [`__dict__`](https://python-all.ru/3.13/reference/datamodel.html#object.__dict__) модуля.5455Возвращаемая ссылка является заимствованной из модуля; она действительна до тех пор, пока модуль не будет уничтожен.5657#### `PyObject *PyModule_GetNameObject(PyObject *module)`5859*Возвращаемое значение: новая ссылка.*6061*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*6263Возвращает значение [`__name__`](https://python-all.ru/3.13/reference/datamodel.html#module.__name__) для *module*. Если модуль не предоставляет такого значения или оно не является строкой, возбуждается [`SystemError`](https://python-all.ru/3.13/library/exceptions.html#SystemError) и возвращается `NULL`.6465Добавлено в версии 3.3.6667#### `const char *PyModule_GetName(PyObject *module)`6869*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*7071Аналогично [`PyModule_GetNameObject()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_GetNameObject), но возвращает имя, закодированное в `'utf-8'`.7273Возвращаемый буфер действителен только до тех пор, пока модуль не переименован или не уничтожен. Обратите внимание, что код Python может переименовать модуль, установив его атрибут [`__name__`](https://python-all.ru/3.13/reference/datamodel.html#module.__name__).7475#### `void *PyModule_GetState(PyObject *module)`7677*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*7879Возвращает «состояние» модуля, то есть указатель на блок памяти, выделенный при создании модуля, или `NULL`. См. [`PyModuleDef.m_size`](https://python-all.ru/3.13/c-api/module.html#c.PyModuleDef.m_size).8081#### `PyModuleDef *PyModule_GetDef(PyObject *module)`8283*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*8485Возвращает указатель на структуру [`PyModuleDef`](https://python-all.ru/3.13/c-api/module.html#c.PyModuleDef), из которой был создан модуль, или `NULL`, если модуль не был создан из определения.8687В случае ошибки возвращает `NULL` с установленным исключением. Используйте [`PyErr_Occurred()`](https://python-all.ru/3.13/c-api/exceptions.html#c.PyErr_Occurred), чтобы отличить этот случай от отсутствия `PyModuleDef`.8889#### `PyObject *PyModule_GetFilenameObject(PyObject *module)`9091*Возвращаемое значение: новая ссылка.*9293*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*9495Возвращает имя файла, из которого был загружен *module*, используя атрибут [`__file__`](https://python-all.ru/3.13/reference/datamodel.html#module.__file__) модуля *module*. Если он не определён или не является строкой, возбуждает [`SystemError`](https://python-all.ru/3.13/library/exceptions.html#SystemError) и возвращает `NULL`; в противном случае возвращает ссылку на объект Unicode.9697Добавлено в версии 3.2.9899#### `const char *PyModule_GetFilename(PyObject *module)`100101*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*102103Аналогично [`PyModule_GetFilenameObject()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_GetFilenameObject), но возвращает имя файла, закодированное в 'utf-8'.104105Возвращаемый буфер действителен только до тех пор, пока атрибут [`__file__`](https://python-all.ru/3.13/reference/datamodel.html#module.__file__) модуля не будет переназначен или модуль не будет уничтожен.106107Устарело с версии 3.2: [`PyModule_GetFilename()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_GetFilename) возбуждает [`UnicodeEncodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeEncodeError) для некодируемых имён файлов; вместо него используйте [`PyModule_GetFilenameObject()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_GetFilenameObject).108109## Инициализация C-модулей110111Объекты модулей обычно создаются из модулей расширения (общих библиотек,\\nкоторые экспортируют функцию инициализации) или из встраиваемых модулей\\n(где функция инициализации добавляется с помощью [`PyImport_AppendInittab()`](https://python-all.ru/3.13/c-api/import.html#c.PyImport_AppendInittab)).\\nПодробнее см. [Building C and C++ Extensions](https://python-all.ru/3.13/extending/building.html#building) или [Extending Embedded Python](https://python-all.ru/3.13/extending/embedding.html#extending-with-embedding).112113Функция инициализации может либо передать экземпляр определения модуля\\nв [`PyModule_Create()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_Create) и вернуть результирующий объект модуля,\\nлибо запросить «многофазную инициализацию», вернув саму структуру определения.114115#### `type PyModuleDef`116117*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) (включая все члены).*118119Структура определения модуля, содержащая всю информацию, необходимую для создания\\nобъекта модуля. Обычно для каждого модуля существует только одна статически\\nинициализированная переменная этого типа.120121#### `PyModuleDef_Base m_base`122123Всегда инициализируйте этот элемент значением `PyModuleDef_HEAD_INIT`.124125#### `const char *m_name`126127Имя нового модуля.128129#### `const char *m_doc`130131Докстринг для модуля; обычно используется переменная докстринга, созданная с помощью [`PyDoc_STRVAR`](https://python-all.ru/3.13/c-api/intro.html#c.PyDoc_STRVAR).132133#### `Py_ssize_t m_size`134135Состояние модуля может храниться в выделенной под каждый модуль области памяти, доступ к которой можно получить через [`PyModule_GetState()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_GetState), а не в статических глобальных переменных. Это делает модули безопасными для использования в нескольких под-интерпретаторах.136137Эта область памяти выделяется на основе *m\_size* при создании модуля и освобождается при удалении объекта модуля, после вызова функции [`m_free`](https://python-all.ru/3.13/c-api/module.html#c.PyModuleDef.m_free) (если она присутствует).138139Установка `m_size` в `-1` означает, что модуль не поддерживает\\nпод-интерпретаторы, так как имеет глобальное состояние.140141Установка в неотрицательное значение означает, что модуль можно\\nпереинициализировать, и указывает дополнительный объём памяти, необходимый\\nдля его состояния. Неотрицательное значение `m_size` требуется для многофазной\\nинициализации.142143Подробнее см. [**PEP 3121**](https://python-all.ru/3.13/c-api/module.html).144145#### `PyMethodDef *m_methods`146147Указатель на таблицу функций уровня модуля, описываемых значениями [`PyMethodDef`](https://python-all.ru/3.13/c-api/structures.html#c.PyMethodDef). Может быть `NULL`, если функции отсутствуют.148149#### `PyModuleDef_Slot *m_slots`150151Массив определений слотов для многофазной инициализации, завершающийся\\nзаписью `{0, NULL}`.\\nПри использовании однофазной инициализации *m\_slots* должен быть `NULL`.152153Изменено в версии 3.5: До версии 3.5 этот элемент всегда устанавливался в `NULL`, и определялся как:154155> #### `inquiry m_reload`156157#### `traverseproc m_traverse`158159Функция обхода, вызываемая при GC-обходе объекта модуля, или `NULL`, если она не нужна.160161Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.13/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3.13/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_GetState)) равно `NULL`.162163Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.164165#### `inquiry m_clear`166167Функция очистки, вызываемая при GC-очистке объекта модуля, или `NULL`, если она не нужна.168169Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.13/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3.13/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_GetState)) равно `NULL`.170171Как и [`PyTypeObject.tp_clear`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_clear), эта функция вызывается не *всегда* перед освобождением модуля. Например, когда подсчёта ссылок достаточно, чтобы определить, что объект больше не используется, циклический сборщик мусора не задействуется, и [`m_free`](https://python-all.ru/3.13/c-api/module.html#c.PyModuleDef.m_free) вызывается напрямую.172173Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.174175#### `freefunc m_free`176177Функция, вызываемая при освобождении объекта модуля, или `NULL`, если она не нужна.178179Эта функция не вызывается, если состояние модуля было запрошено, но ещё не выделено. Такая ситуация возникает сразу после создания модуля и до его выполнения (функция [`Py_mod_exec`](https://python-all.ru/3.13/c-api/module.html#c.Py_mod_exec)). Если точнее, функция не вызывается, когда [`m_size`](https://python-all.ru/3.13/c-api/module.html#c.PyModuleDef.m_size) больше 0 и состояние модуля (возвращаемое [`PyModule_GetState()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_GetState)) равно `NULL`.180181Изменено в версии 3.9: Больше не вызывается до выделения состояния модуля.182183#### `PyTypeObject PyModuleDef_Type`184185*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.5.*186187Тип объектов `PyModuleDef`.188189### Однофазная инициализация190191Функция инициализации модуля может напрямую создать и вернуть объект модуля. Это называется «однофазной инициализацией» и использует одну из двух следующих функций создания модуля:192193#### `PyObject *PyModule_Create(PyModuleDef *def)`194195*Возвращаемое значение: новая ссылка.*196197Создаёт новый объект модуля на основе определения в *def*. Ведёт себя как [`PyModule_Create2()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_Create2), когда *module\_api\_version* установлен в `PYTHON_API_VERSION`.198199#### `PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)`200201*Возвращаемое значение: новая ссылка.*202203*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*204205Создаёт новый объект модуля на основе определения в *def*, предполагая версию API *module\_api\_version*. Если эта версия не совпадает с версией работающего интерпретатора, генерируется [`RuntimeWarning`](https://python-all.ru/3.13/library/exceptions.html#RuntimeWarning).206207Возвращает `NULL` с установленным исключением в случае ошибки.208209> **Примечание**210>211> В большинстве случаев вместо этой функции следует использовать [`PyModule_Create()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_Create); используйте её, только если точно уверены, что она нужна.212213Перед возвратом из функции инициализации полученный объект модуля обычно заполняется с помощью таких функций, как [`PyModule_AddObjectRef()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_AddObjectRef).214215### Многофазная инициализация216217Альтернативный способ определения расширений – запросить «многофазную инициализацию». Модули расширений, созданные таким образом, ведут себя больше как модули Python: инициализация разделена на *фазу создания*, когда создаётся объект модуля, и *фазу выполнения*, когда он заполняется. Различие похоже на методы [`__new__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__new__) и [`__init__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__init__) классов.218219В отличие от модулей, созданных с помощью однофазной инициализации, эти модули не являются синглтонами. Например, если запись [`sys.modules`](https://python-all.ru/3.13/library/sys.html#sys.modules) удалена и модуль импортируется заново, создаётся новый объект модуля, который обычно заполняется свежими объектами методов и типов. Старый модуль подлежит обычной сборке мусора. Это отражает поведение чистых модулей Python.220221Дополнительные экземпляры модуля могут быть созданы в [под-интерпретаторах](https://python-all.ru/3.13/c-api/init.html#sub-interpreter-support) или после повторной инициализации среды выполнения Python ([`Py_Finalize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Finalize) и [`Py_Initialize()`](https://python-all.ru/3.13/c-api/init.html#c.Py_Initialize)). В таких случаях совместное использование объектов Python между экземплярами модуля, скорее всего, приведёт к сбоям или неопределённому поведению.222223Чтобы избежать таких проблем, каждый экземпляр модуля расширения должен быть *изолирован*: изменения в одном экземпляре не должны неявно влиять на другие, и всё состояние, включая ссылки на объекты Python, должно быть специфичным для конкретного экземпляра модуля. См. [Изоляция модулей расширений](https://python-all.ru/3.13/howto/isolating-extensions.html#isolating-extensions-howto) для подробностей и практического руководства.224225A simpler way to avoid these issues is [raising an error on repeated initialization](https://python-all.ru/3.13/howto/isolating-extensions.html#isolating-extensions-optout).226227Все модули, созданные с помощью многофазной инициализации, должны поддерживать [под-интерпретаторы](https://python-all.ru/3.13/c-api/init.html#sub-interpreter-support) или иным образом явно сообщать об отсутствии поддержки. Обычно это достигается изоляцией или блокировкой повторной инициализации, как описано выше. Модуль также может быть ограничен главным интерпретатором с помощью слота [`Py_mod_multiple_interpreters`](https://python-all.ru/3.13/c-api/module.html#c.Py_mod_multiple_interpreters).228229Чтобы запросить многофазную инициализацию, функция инициализации (PyInit\_modulename) возвращает экземпляр [`PyModuleDef`](https://python-all.ru/3.13/c-api/module.html#c.PyModuleDef) с непустым [`m_slots`](https://python-all.ru/3.13/c-api/module.html#c.PyModuleDef.m_slots). Перед возвратом экземпляр `PyModuleDef` должен быть инициализирован следующей функцией:230231#### `PyObject *PyModuleDef_Init(PyModuleDef *def)`232233*Возвращаемое значение: Borrowed reference.*234235*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.5.*236237Гарантирует, что определение модуля является правильно инициализированным объектом Python, который корректно сообщает свой тип и счётчик ссылок.238239Возвращает *def*, приведённый к `PyObject*`, или `NULL`, если произошла ошибка.240241Добавлено в версии 3.5.242243Член *m\_slots* определения модуля должен указывать на массив структур `PyModuleDef_Slot`:244245#### `type PyModuleDef_Slot`246247*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) (включая все элементы) начиная с версии 3.5.*248249#### `int slot`250251Идентификатор слота, выбираемый из доступных значений, описанных ниже.252253#### `void *value`254255Значение слота, смысл которого зависит от идентификатора слота.256257Добавлено в версии 3.5.258259Массив *m\_slots* должен завершаться слотом с id 0.260261Доступны следующие типы слотов:262263#### `Py_mod_create`264265*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.5.*266267Задаёт функцию, которая вызывается для создания самого объекта модуля. Указатель *value* этого слота должен указывать на функцию со следующей сигнатурой:268269#### `PyObject *create_module(PyObject *spec, PyModuleDef *def)`270271Функция получает экземпляр [`ModuleSpec`](https://python-all.ru/3.13/library/importlib.html#importlib.machinery.ModuleSpec), как определено в [**PEP 451**](https://python-all.ru/3.13/c-api/module.html), и определение модуля. Она должна вернуть новый объект модуля или установить ошибку и вернуть `NULL`.272273Эта функция должна быть минимальной. В частности, она не должна вызывать произвольный код Python, так как повторная попытка импорта того же модуля может привести к бесконечному циклу.274275В одном определении модуля нельзя задавать несколько слотов `Py_mod_create`.276277Если `Py_mod_create` не указан, механизм импорта создаст обычный объект модуля с помощью [`PyModule_New()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_New). Имя берётся из *spec*, а не из определения, чтобы расширения могли динамически подстраиваться под своё место в иерархии модулей и импортироваться под другими именами через симлинки, оставаясь привязанными к одному определению модуля.278279Возвращаемый объект не обязан быть экземпляром [`PyModule_Type`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_Type). Можно использовать любой тип, если он поддерживает установку и получение атрибутов, связанных с импортом. Однако только экземпляры `PyModule_Type` могут быть возвращены, если `PyModuleDef` содержит ненулевые `NULL` `m_traverse`, `m_clear`, `m_free`; ненулевой `m_size`; или слоты, отличные от `Py_mod_create`.280281Добавлено в версии 3.5.282283#### `Py_mod_exec`284285*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.5.*286287Задаёт функцию, которая вызывается для *выполнения* модуля. Это эквивалентно выполнению кода модуля Python: обычно эта функция добавляет в модуль классы и константы. Сигнатура функции такова:288289#### `int exec_module(PyObject *module)`290291Если указано несколько слотов `Py_mod_exec`, они обрабатываются в том порядке, в котором расположены в массиве *m\_slots*.292293Добавлено в версии 3.5.294295#### `Py_mod_multiple_interpreters`296297*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.12.*298299Задаёт одно из следующих значений:300301#### `Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`302303Модуль не поддерживает импорт в подынтерпретаторах.304305#### `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`306307Модуль поддерживает импорт в подынтерпретаторах, но только если они используют общий GIL основного интерпретатора. (См. [Изоляция модулей расширения](https://python-all.ru/3.13/howto/isolating-extensions.html#isolating-extensions-howto).)308309#### `Py_MOD_PER_INTERPRETER_GIL_SUPPORTED`310311Модуль поддерживает импорт в подынтерпретаторах, даже если у них собственный GIL. (См. [Изоляция модулей расширения](https://python-all.ru/3.13/howto/isolating-extensions.html#isolating-extensions-howto).)312313Этот слот определяет, будет ли импорт этого модуля в подынтерпретаторе завершаться ошибкой.314315В одном определении модуля нельзя указывать несколько слотов `Py_mod_multiple_interpreters`.316317Если `Py_mod_multiple_interpreters` не указан, механизм импорта по умолчанию использует `Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED`.318319Добавлено в версии 3.12.320321#### `Py_mod_gil`322323*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable), начиная с версии 3.13.*324325Задаёт одно из следующих значений:326327#### `Py_MOD_GIL_USED`328329Модуль зависит от наличия глобальной блокировки интерпретатора (GIL), и может обращаться к глобальному состоянию без синхронизации.330331#### `Py_MOD_GIL_NOT_USED`332333Модуль можно безопасно использовать без активного GIL.334335Этот слот игнорируется сборками Python, не настроенными с [`--disable-gil`](https://python-all.ru/3.13/using/configure.html#cmdoption-disable-gil). В противном случае он определяет, приведёт ли импорт этого модуля к автоматическому включению GIL. Подробнее см. [Free-threaded CPython](https://python-all.ru/3.13/whatsnew/3.13.html#whatsnew313-free-threaded-cpython).336337В одном определении модуля нельзя указывать несколько слотов `Py_mod_gil`.338339Если `Py_mod_gil` не указан, механизм импорта по умолчанию использует `Py_MOD_GIL_USED`.340341Добавлено в версии 3.13.342343См. [**PEP 489**](https://python-all.ru/3.13/c-api/module.html) для более подробной информации о многофазной инициализации.344345### Низкоуровневые функции создания модулей346347Следующие функции вызываются «под капотом» при использовании многофазной инициализации. Их можно использовать напрямую, например, при динамическом создании объектов модуля. Обратите внимание, что для полной инициализации модуля необходимо вызвать как `PyModule_FromDefAndSpec`, так и `PyModule_ExecDef`.348349#### `PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)`350351*Возвращаемое значение: новая ссылка.*352353Создаёт новый объект модуля по определению *def* и *spec* (ModuleSpec). Работает так же, как [`PyModule_FromDefAndSpec2()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_FromDefAndSpec2), с *module\_api\_version*, установленным в `PYTHON_API_VERSION`.354355Добавлено в версии 3.5.356357#### `PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)`358359*Возвращаемое значение: новая ссылка.*360361*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*362363Создает новый объект модуля по определению из *def* и ModuleSpec *spec*, используя версию API *module\_api\_version*. Если эта версия не соответствует версии работающего интерпретатора, выдается [`RuntimeWarning`](https://python-all.ru/3.13/library/exceptions.html#RuntimeWarning).364365Возвращает `NULL` с установленным исключением в случае ошибки.366367> **Примечание**368>369> В большинстве случаев вместо этой функции следует использовать [`PyModule_FromDefAndSpec()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_FromDefAndSpec); используйте её, только если точно уверены, что она нужна.370371Добавлено в версии 3.5.372373#### `int PyModule_ExecDef(PyObject *module, PyModuleDef *def)`374375*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*376377Обрабатывает любые слоты выполнения ([`Py_mod_exec`](https://python-all.ru/3.13/c-api/module.html#c.Py_mod_exec)), заданные в *def*.378379Добавлено в версии 3.5.380381#### `int PyModule_SetDocString(PyObject *module, const char *docstring)`382383*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*384385Устанавливает docstring для *module* равным *docstring*. Эта функция вызывается автоматически при создании модуля из `PyModuleDef` с помощью `PyModule_Create` или `PyModule_FromDefAndSpec`.386387Возвращает `0` при успехе. Возвращает `-1` с установленным исключением при ошибке.388389Добавлено в версии 3.5.390391#### `int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)`392393*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.7.*394395Добавляет функции из массива *functions*, завершающегося `NULL`, в *module*. Подробнее об отдельных элементах см. документацию [`PyMethodDef`](https://python-all.ru/3.13/c-api/structures.html#c.PyMethodDef) (из-за отсутствия общего пространства имён модуля «функции» уровня модуля, реализованные на C, обычно получают сам модуль в качестве первого параметра, что делает их похожими на методы экземпляра классов Python). Эта функция вызывается автоматически при создании модуля из `PyModuleDef` с помощью `PyModule_Create` или `PyModule_FromDefAndSpec`.396397Массив *functions* должен быть статически выделен (или иным образом гарантированно переживать объект модуля).398399Добавлено в версии 3.5.400401### Вспомогательные функции402403Функция инициализации модуля (при однофазной инициализации) или функция, вызываемая из слота выполнения модуля (при многофазной инициализации), могут использовать следующие функции для инициализации состояния модуля:404405#### `int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)`406407*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.10.*408409Добавляет объект в *module* как *name*. Это удобная функция, которую можно использовать из функции инициализации модуля.410411При успехе возвращает `0`. При ошибке вызывает исключение и возвращает `-1`.412413Пример использования:414415```c416static int417add_spam(PyObject *module, int value)418{419    PyObject *obj = PyLong_FromLong(value);420    if (obj == NULL) {421        return -1;422    }423    int res = PyModule_AddObjectRef(module, "spam", obj);424    Py_DECREF(obj);425    return res;426 }427```428429Для удобства функция принимает `NULL` *value* с установленным исключением. В этом случае возвращает `-1` и просто оставляет вызванное исключение без изменений.430431Пример можно также написать без явной проверки, что *obj* равен `NULL`:432433```c434static int435add_spam(PyObject *module, int value)436{437    PyObject *obj = PyLong_FromLong(value);438    int res = PyModule_AddObjectRef(module, "spam", obj);439    Py_XDECREF(obj);440    return res;441 }442```443444Обратите внимание, что в этом случае следует использовать `Py_XDECREF()` вместо `Py_DECREF()`, поскольку *obj* может быть `NULL`.445446Количество различных строк *name*, передаваемых этой функции, должно быть небольшим – обычно используйте только статически выделенные строки в качестве *name*. Для имен, неизвестных во время компиляции, предпочтительнее вызывать [`PyUnicode_FromString()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_FromString) и [`PyObject_SetAttr()`](https://python-all.ru/3.13/c-api/object.html#c.PyObject_SetAttr) напрямую. Подробнее см. [`PyUnicode_InternFromString()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_InternFromString), который может использоваться внутри для создания объекта ключа.447448Добавлено в версии 3.10.449450#### `int PyModule_Add(PyObject *module, const char *name, PyObject *value)`451452*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable), начиная с версии 3.13.*453454Похожа на [`PyModule_AddObjectRef()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_AddObjectRef), но “[крадет](https://python-all.ru/3.13/glossary.html#term-steal)” ссылку на *value* (даже при ошибке). Её можно вызывать с результатом функции, возвращающей новую ссылку, не беспокоясь о проверке результата или даже сохранении его в переменную.455456Пример использования:457458```c459if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {460    goto error;461}462```463464Добавлено в версии 3.13.465466#### `int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)`467468*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*469470Похоже на [`PyModule_AddObjectRef()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_AddObjectRef), но при успехе [присваивает](https://python-all.ru/3.13/glossary.html#term-steal) ссылку на *value* (если возвращает `0`).471472Рекомендуются новые функции [`PyModule_Add()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_Add) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_AddObjectRef), поскольку неправильное использование [`PyModule_AddObject()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_AddObject) может легко привести к утечкам ссылок.473474> **Примечание**475>476> В отличие от других функций, крадущих ссылки, `PyModule_AddObject()` освобождает ссылку на *value* **только при успехе**.477>478> Это означает, что возвращаемое значение необходимо проверять, а код вызова должен вручную [`Py_XDECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XDECREF) *value* при ошибке.479480Пример использования:481482```c483PyObject *obj = PyBytes_FromString(value);484if (PyModule_AddObject(module, "spam", obj) < 0) {485    // Если 'obj' не NULL и PyModule_AddObject() завершился неудачей,486    // сильную ссылку 'obj' необходимо удалить с помощью Py_XDECREF().487    // Если 'obj' равен NULL, Py_XDECREF() ничего не делает.488    Py_XDECREF(obj);489    goto error;490}491// PyModule_AddObject() перехватил ссылку на obj:492// Py_XDECREF(obj) здесь не требуется.493```494495[Мягкое устаревание](https://python-all.ru/3.13/glossary.html#term-soft-deprecated) начиная с версии 3.13.496497#### `int PyModule_AddIntConstant(PyObject *module, const char *name, long value)`498499*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*500501Добавляет целочисленную константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.502503Это удобная функция, которая вызывает [`PyLong_FromLong()`](https://python-all.ru/3.13/c-api/long.html#c.PyLong_FromLong) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.504505#### `int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)`506507*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*508509Добавляет строковую константу в *module* под именем *name*. Эту удобную функцию можно использовать из функции инициализации модуля. Строка *value* должна быть завершена символами `NULL`. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.510511Это удобная функция, которая вызывает [`PyUnicode_InternFromString()`](https://python-all.ru/3.13/c-api/unicode.html#c.PyUnicode_InternFromString) и [`PyModule_AddObjectRef()`](https://python-all.ru/3.13/c-api/module.html#c.PyModule_AddObjectRef); подробнее см. их документацию.512513#### `PyModule_AddIntMacro(module, macro)`514515Добавляет целочисленную константу в *module*. Имя и значение берутся из *macro*. Например, `PyModule_AddIntMacro(module, AF_INET)` добавляет целочисленную константу *AF\_INET* со значением *AF\_INET* в *module*. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.516517#### `PyModule_AddStringMacro(module, macro)`518519Добавляет строковую константу в *module*.520521#### `int PyModule_AddType(PyObject *module, PyTypeObject *type)`522523*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.10.*524525Добавляет объект типа в *module*. Объект типа финализируется внутренним вызовом [`PyType_Ready()`](https://python-all.ru/3.13/c-api/type.html#c.PyType_Ready). Имя объекта типа берётся из последнего компонента [`tp_name`](https://python-all.ru/3.13/c-api/typeobj.html#c.PyTypeObject.tp_name) после точки. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.526527Добавлено в версии 3.9.528529#### `int PyUnstable_Module_SetGIL(PyObject *module, void *gil)`530531> *Это [нестабильное API](https://python-all.ru/3.13/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*532533Указывает, поддерживает ли *module* работу без глобальной блокировки интерпретатора (GIL), используя одно из значений из [`Py_mod_gil`](https://python-all.ru/3.13/c-api/module.html#c.Py_mod_gil). Должна быть вызвана во время функции инициализации *module*. Если эта функция не вызывается при инициализации модуля, механизм импорта считает, что модуль не поддерживает работу без GIL. Эта функция доступна только в сборках Python, сконфигурированных с [`--disable-gil`](https://python-all.ru/3.13/using/configure.html#cmdoption-disable-gil). Возвращает `-1` с установленным исключением в случае ошибки, `0` при успехе.534535Добавлено в версии 3.13.536537## Поиск модуля538539Однофазная инициализация создаёт модули-одиночки, которые можно найти в контексте текущего интерпретатора. Это позволяет впоследствии получить объект модуля, имея только ссылку на определение модуля.540541Эти функции не будут работать с модулями, созданными с помощью многофазной инициализации, поскольку из одного определения можно создать несколько таких модулей.542543#### `PyObject *PyState_FindModule(PyModuleDef *def)`544545*Возвращаемое значение: заимствованная ссылка.*546547*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*548549Возвращает объект модуля, созданный из *def* для текущего интерпретатора. Этот метод требует, чтобы объект модуля был предварительно прикреплён к состоянию интерпретатора с помощью [`PyState_AddModule()`](https://python-all.ru/3.13/c-api/module.html#c.PyState_AddModule). Если соответствующий объект модуля не найден или ещё не прикреплён к состоянию интерпретатора, он возвращает `NULL`.550551#### `int PyState_AddModule(PyObject *module, PyModuleDef *def)`552553*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.3.*554555Прикрепляет объект модуля, переданный функции, к состоянию интерпретатора. Это позволяет обращаться к объекту модуля через [`PyState_FindModule()`](https://python-all.ru/3.13/c-api/module.html#c.PyState_FindModule).556557Действует только на модули, созданные с помощью однофазной инициализации.558559Python автоматически вызывает `PyState_AddModule` после импорта модуля, поэтому её вызов из кода инициализации модуля излишен (но безвреден). Явный вызов требуется только в том случае, если собственный код инициализации модуля впоследствии вызывает `PyState_FindModule`. Функция в основном предназначена для реализации альтернативных механизмов импорта (путём прямого вызова или обращения к её реализации для получения информации о требуемых обновлениях состояния).560561Вызывающий код должен удерживать GIL.562563Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.564565Добавлено в версии 3.3.566567#### `int PyState_RemoveModule(PyModuleDef *def)`568569*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.3.*570571Удаляет объект модуля, созданный из *def*, из состояния интерпретатора. Возвращает `-1` с установленным исключением при ошибке, `0` при успехе.572573Вызывающий код должен удерживать GIL.574575Добавлено в версии 3.3.576