`import.md`

345 строк · 30.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/c-api/import.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Импорт модулей89#### `PyObject *PyImport_ImportModule(const char *name)`1011*Возвращаемое значение: новая ссылка.*1213*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*1415Это обёртка вокруг [`PyImport_Import()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_Import), которая принимает const char\* в качестве аргумента вместо [PyObject](https://python-all.ru/3.15/c-api/structures.html#c.PyObject)\*.1617#### `PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)`1819*Возвращаемое значение: новая ссылка.*2021Импорт модуля. Лучше всего это описывается через встроенную функцию Python [`__import__()`](https://python-all.ru/3.15/library/functions.html#import__).2223Возвращаемое значение – это новая ссылка на импортированный модуль или пакет верхнего уровня, либо `NULL` с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.15/library/functions.html#import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist* .2425Неудачные импорты удаляют неполные объекты модулей, как и [`PyImport_ImportModule()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ImportModule).2627#### `PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)`2829*Возвращаемое значение: новая ссылка.*3031*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable) начиная с версии 3.7.*3233Импорт модуля. Наилучшее описание даётся через встроенную функцию Python [`__import__()`](https://python-all.ru/3.15/library/functions.html#import__), поскольку стандартная функция `__import__()` вызывает эту функцию напрямую.3435Возвращаемое значение – это новая ссылка на импортированный модуль или пакет верхнего уровня, либо `NULL` с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.15/library/functions.html#import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist*.3637Добавлено в версии 3.3.3839#### `PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)`4041*Возвращаемое значение: новая ссылка.*4243*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*4445Аналогично [`PyImport_ImportModuleLevelObject()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ImportModuleLevelObject), но имя представляет собой строку в кодировке UTF-8 вместо объекта Unicode.4647Изменено в версии 3.3: Отрицательные значения для *level* больше не принимаются.4849#### `PyObject *PyImport_Import(PyObject *name)`5051*Возвращаемое значение: новая ссылка.*5253*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*5455Это интерфейс более высокого уровня, который вызывает текущую «функцию перехвата импорта» (с явным *level* равным 0, что означает абсолютный импорт). Он вызывает функцию [`__import__()`](https://python-all.ru/3.15/library/functions.html#import__) из `__builtins__` текущих глобальных переменных. Это означает, что импорт выполняется с использованием тех перехватчиков импорта, которые установлены в текущем окружении.5657Эта функция всегда использует абсолютные импорты.5859#### `PyObject *PyImport_ReloadModule(PyObject *m)`6061*Возвращаемое значение: новая ссылка.*6263*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*6465Перезагружает модуль. Возвращает новую ссылку на перезагруженный модуль или `NULL` с установленным исключением в случае ошибки (в этом случае модуль всё ещё существует).6667#### `PyObject *PyImport_AddModuleRef(const char *name)`6869*Возвращаемое значение: новая ссылка.*7071*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable) начиная с версии 3.13.*7273Возвращает объект модуля, соответствующий имени модуля.7475Аргумент *name* может быть в форме `package.module`. Сначала проверяется словарь модулей на наличие такого модуля, и если его нет, создаётся новый и вставляется в словарь модулей.7677Возвращает [сильную ссылку](https://python-all.ru/3.15/glossary.html#term-strong-reference) на модуль в случае успеха. Возвращает `NULL` с установленным исключением в случае ошибки.7879Имя модуля *name* декодируется из UTF-8.8081Эта функция не загружает и не импортирует модуль; если модуль ещё не был загружен, будет получен пустой объект модуля. Используйте [`PyImport_ImportModule()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ImportModule) или один из его вариантов для импорта модуля. Структуры пакетов, подразумеваемые именем с точками для *name*, не создаются, если они ещё не существуют.8283Добавлено в версии 3.13.8485#### `PyObject *PyImport_AddModuleObject(PyObject *name)`8687*Возвращаемое значение: заимствованная ссылка.*8889*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable) начиная с версии 3.7.*9091Аналог [`PyImport_AddModuleRef()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_AddModuleRef), но возвращает [заимствованную ссылку](https://python-all.ru/3.15/glossary.html#term-borrowed-reference), а *name* является объектом Python [`str`](https://python-all.ru/3.15/library/stdtypes.html#str).9293Добавлено в версии 3.3.9495#### `PyObject *PyImport_AddModule(const char *name)`9697*Возвращаемое значение: заимствованная ссылка.*9899*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*100101Подобно [`PyImport_AddModuleRef()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_AddModuleRef), но возвращает [заимствованную ссылку](https://python-all.ru/3.15/glossary.html#term-borrowed-reference).102103#### `PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)`104105*Возвращаемое значение: новая ссылка.*106107*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*108109Принимая имя модуля (возможно, вида `package.module`) и объект кода, прочитанный из файла байткода Python или полученный из встроенной функции [`compile()`](https://python-all.ru/3.15/library/functions.html#compile), загружает модуль. Возвращает новую ссылку на объект модуля или `NULL` с установленным исключением, если произошла ошибка. В случае ошибки *name* удаляется из [`sys.modules`](https://python-all.ru/3.15/library/sys.html#sys.modules), даже если *name* уже был в `sys.modules` на момент входа в [`PyImport_ExecCodeModule()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExecCodeModule). Оставлять не полностью инициализированные модули в `sys.modules` опасно, так как импорт таких модулей не может узнать, что объект модуля находится в неизвестном (и, вероятно, повреждённом с точки зрения намерений автора модуля) состоянии.110111[`__spec__`](https://python-all.ru/3.15/reference/datamodel.html#module.__spec__) и [`__loader__`](https://python-all.ru/3.15/reference/datamodel.html#module.__loader__) модуля будут установлены, если ещё не установлены, с соответствующими значениями. Загрузчик спецификации будет установлен на `__loader__` модуля (если установлен) или на экземпляр [`SourceFileLoader`](https://python-all.ru/3.15/library/importlib.html#importlib.machinery.SourceFileLoader) в противном случае.112113Атрибут [`__file__`](https://python-all.ru/3.15/reference/datamodel.html#module.__file__) модуля будет установлен в [`co_filename`](https://python-all.ru/3.15/reference/datamodel.html#codeobject.co_filename) объекта кода.114115Эта функция перезагрузит модуль, если он уже был импортирован. См. [`PyImport_ReloadModule()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ReloadModule) для описания правильного способа перезагрузки модуля.116117Если *name* указывает на имя с точками вида `package.module`, любые структуры пакета, которые ещё не были созданы, по-прежнему не будут созданы.118119См. также [`PyImport_ExecCodeModuleEx()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExecCodeModuleEx) и [`PyImport_ExecCodeModuleWithPathnames()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExecCodeModuleWithPathnames).120121Изменено в версии 3.12: Установка `__cached__` и [`__loader__`](https://python-all.ru/3.15/reference/datamodel.html#module.__loader__) является устаревшей. См. [`ModuleSpec`](https://python-all.ru/3.15/library/importlib.html#importlib.machinery.ModuleSpec) для альтернатив.122123Изменено в версии 3.15: `__cached__` больше не устанавливается.124125#### `PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)`126127*Возвращаемое значение: новая ссылка.*128129*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*130131Как [`PyImport_ExecCodeModule()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExecCodeModule), но атрибут [`__file__`](https://python-all.ru/3.15/reference/datamodel.html#module.__file__) объекта модуля устанавливается в *pathname*, если он не равен `NULL`.132133См. также [`PyImport_ExecCodeModuleWithPathnames()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExecCodeModuleWithPathnames).134135#### `PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)`136137*Возвращаемое значение: новая ссылка.*138139*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable) начиная с версии 3.7.*140141Как [`PyImport_ExecCodeModuleEx()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExecCodeModuleEx), но путь к любому скомпилированному файлу через *cpathname* используется соответствующим образом, когда не равен `NULL`. Из трёх функций эта является предпочтительной.142143Добавлено в версии 3.3.144145Изменено в версии 3.12: Установка `__cached__` является устаревшей. См. [`ModuleSpec`](https://python-all.ru/3.15/library/importlib.html#importlib.machinery.ModuleSpec) для альтернатив.146147Изменено в версии 3.15: `__cached__` больше не устанавливается.148149#### `PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)`150151*Возвращаемое значение: новая ссылка.*152153*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*154155Как [`PyImport_ExecCodeModuleObject()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExecCodeModuleObject), но *name*, *pathname* и *cpathname* являются строками в кодировке UTF-8. Также предпринимаются попытки выяснить, каким должно быть значение *pathname* из *cpathname*, если первое установлено в `NULL`.156157Добавлено в версии 3.2.158159Изменено в версии 3.3: Использует `imp.source_from_cache()` при вычислении пути к исходному коду, если указан только путь к байткоду.160161Изменено в версии 3.12: Больше не использует удалённый модуль `imp`.162163#### `long PyImport_GetMagicNumber()`164165*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*166167Возвращает магическое число для файлов байткода Python (также известных как файлы `.pyc`). Магическое число должно присутствовать в первых четырёх байтах файла байткода в порядке little-endian. В случае ошибки возвращает `-1`.168169Изменено в версии 3.3: Возвращает `-1` в случае неудачи.170171#### `const char *PyImport_GetMagicTag()`172173*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*174175Возвращает строку магического тега для имён файлов байткода Python в формате [**PEP 3147**](https://python-all.ru/3.15/c-api/import.html). Имейте в виду, что значение в `sys.implementation.cache_tag` является авторитетным и должно использоваться вместо этой функции.176177Добавлено в версии 3.2.178179#### `PyObject *PyImport_GetModuleDict()`180181*Возвращаемое значение: заимствованная ссылка.*182183*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*184185Возвращает словарь, используемый для администрирования модулей (также известный как `sys.modules`). Обратите внимание, что это переменная, отдельная для каждого интерпретатора.186187#### `PyObject *PyImport_GetModule(PyObject *name)`188189*Возвращаемое значение: новая ссылка.*190191*Часть [стабильного ABI](https://python-all.ru/3.15/c-api/stable.html#stable) начиная с версии 3.8.*192193Возвращает уже импортированный модуль с заданным именем. Если модуль ещё не был импортирован, возвращает `NULL`, но не устанавливает ошибку. Возвращает `NULL` и устанавливает ошибку, если поиск не удался.194195Добавлено в версии 3.7.196197#### `PyObject *PyImport_GetImporter(PyObject *path)`198199*Возвращаемое значение: новая ссылка.*200201*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*202203Возвращает объект поиска для элемента [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path)/`pkg.__path__` *path*, возможно, извлекая его из словаря [`sys.path_importer_cache`](https://python-all.ru/3.15/library/sys.html#sys.path_importer_cache). Если он ещё не кэширован, обходит [`sys.path_hooks`](https://python-all.ru/3.15/library/sys.html#sys.path_hooks), пока не будет найден хук, способный обработать элемент пути. Возвращает `None`, если ни один хук не подошёл; это сообщает вызывающей стороне, что [поисковик на основе пути](https://python-all.ru/3.15/glossary.html#term-path-based-finder) не смог найти поисковик для этого элемента пути. Кэширует результат в `sys.path_importer_cache`. Возвращает новую ссылку на объект поисковика.204205#### `int PyImport_ImportFrozenModuleObject(PyObject *name)`206207*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable) начиная с версии 3.7.*208209Загружает замороженный модуль с именем *name*. Возвращает `1` при успехе, `0`, если модуль не найден, и `-1` с установленным исключением, если инициализация не удалась. Чтобы получить доступ к импортированному модулю после успешной загрузки, используйте [`PyImport_ImportModule()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ImportModule). (Обратите внимание на неточность названия – эта функция перезагрузила бы модуль, если он уже был импортирован.)210211Добавлено в версии 3.3.212213Изменено в версии 3.4: Атрибут `__file__` больше не устанавливается в модуле.214215#### `int PyImport_ImportFrozenModule(const char *name)`216217*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*218219Аналогично [`PyImport_ImportFrozenModuleObject()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ImportFrozenModuleObject), но имя представляет собой строку в кодировке UTF-8 вместо объекта Unicode.220221#### `struct _frozen`222223Это определение типа структуры для дескрипторов замороженных модулей, как сгенерировано утилитой **freeze** (см. `Tools/freeze/` в дистрибутиве исходного кода Python). Её определение находится в `Include/import.h`:224225```c226struct _frozen {227    const char *name;228    const unsigned char *code;229    int size;230    bool is_package;231};232```233234Изменено в версии 3.11: Новое поле `is_package` указывает, является ли модуль пакетом или нет. Это заменяет установку поля `size` в отрицательное значение.235236#### `const struct _frozen *PyImport_FrozenModules`237238Этот указатель инициализируется так, чтобы указывать на массив записей [`_frozen`](https://python-all.ru/3.15/c-api/import.html#c._frozen), завершающийся записью, все члены которой равны `NULL` или нулю. Когда замороженный модуль импортируется, он ищется в этой таблице. Сторонний код может этим воспользоваться, чтобы предоставить динамически создаваемую коллекцию замороженных модулей.239240#### `int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))`241242*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*243244Добавляет один модуль в существующую таблицу встроенных модулей. Это удобная обёртка вокруг [`PyImport_ExtendInittab()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExtendInittab), возвращающая `-1`, если таблицу не удалось расширить. Новый модуль можно импортировать по имени *name*, и он использует функцию *initfunc* в качестве функции инициализации, вызываемой при первой попытке импорта. Это должно вызываться до [`Py_Initialize()`](https://python-all.ru/3.15/c-api/interp-lifecycle.html#c.Py_Initialize).245246#### `struct _inittab`247248Структура, описывающая одну запись в списке встроенных модулей. Программы, встраивающие Python, могут использовать массив таких структур в сочетании с [`PyImport_ExtendInittab()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExtendInittab) для предоставления дополнительных встроенных модулей. Структура состоит из двух членов:249250#### `const char *name`251252Имя модуля в виде строки в кодировке ASCII.253254#### `PyObject *(*initfunc)(void)`255256Функция инициализации для модуля, встроенного в интерпретатор.257258Обратите внимание, что inittab использует «`PyInit`» [функции инициализации](https://python-all.ru/3.15/c-api/extension-modules.html#extension-pyinit); в настоящее время нет способа включить «`PyModExport_`» [экспортные хуки](https://python-all.ru/3.15/c-api/extension-modules.html#extension-export-hook).259260#### `int PyImport_ExtendInittab(struct _inittab *newtab)`261262Добавляет набор модулей в таблицу встроенных модулей. Массив *newtab* должен заканчиваться сторожевой записью, которая содержит `NULL` для поля [`name`](https://python-all.ru/3.15/c-api/import.html#c._inittab.name); отсутствие сторожевого значения может привести к ошибке памяти. Возвращает `0` при успехе или `-1`, если недостаточно памяти для расширения внутренней таблицы. В случае неудачи ни один модуль не добавляется во внутреннюю таблицу. Это должно вызываться до [`Py_Initialize()`](https://python-all.ru/3.15/c-api/interp-lifecycle.html#c.Py_Initialize).263264Если Python инициализируется несколько раз, [`PyImport_AppendInittab()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_AppendInittab) или [`PyImport_ExtendInittab()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExtendInittab) должны вызываться перед каждой инициализацией Python.265266#### `struct _inittab *PyImport_Inittab`267268Таблица встроенных модулей, используемая при инициализации Python. Не используйте это напрямую; вместо этого используйте [`PyImport_AppendInittab()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_AppendInittab) и [`PyImport_ExtendInittab()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ExtendInittab).269270#### `PyObject *PyImport_ImportModuleAttr(PyObject *mod_name, PyObject *attr_name)`271272*Возвращаемое значение: новая ссылка.*273274Импортирует модуль *mod\_name* и получает его атрибут *attr\_name*.275276Имена должны быть объектами Python [`str`](https://python-all.ru/3.15/library/stdtypes.html#str).277278Вспомогательная функция, объединяющая [`PyImport_Import()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_Import) и [`PyObject_GetAttr()`](https://python-all.ru/3.15/c-api/object.html#c.PyObject_GetAttr). Например, она может возбуждать [`ImportError`](https://python-all.ru/3.15/library/exceptions.html#ImportError), если модуль не найден, и [`AttributeError`](https://python-all.ru/3.15/library/exceptions.html#AttributeError), если атрибут не существует.279280Добавлено в версии 3.14.281282#### `PyObject *PyImport_ImportModuleAttrString(const char *mod_name, const char *attr_name)`283284*Возвращаемое значение: новая ссылка.*285286Аналогично [`PyImport_ImportModuleAttr()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ImportModuleAttr), но имена передаются в виде строк в кодировке UTF-8 вместо объектов [`str`](https://python-all.ru/3.15/library/stdtypes.html#str).287288Добавлено в версии 3.14.289290#### `PyImport_LazyImportsMode PyImport_GetLazyImportsMode()`291292Возвращает текущий режим отложенного импорта.293294Добавлено в версии 3.15.295296#### `PyObject *PyImport_GetLazyImportsFilter()`297298Возвращает [сильную ссылку](https://python-all.ru/3.15/glossary.html#term-strong-reference) на текущий фильтр отложенного импорта. Если фильтр не задан, возвращает `NULL`. Эта функция всегда завершается успешно.299300Добавлено в версии 3.15.301302#### `int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)`303304Аналогично [`PyImport_ImportModuleAttr()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_ImportModuleAttr), но имена передаются в виде строк в кодировке UTF-8 вместо объектов [`str`](https://python-all.ru/3.15/library/stdtypes.html#str).305306Эта функция всегда возвращает `0`.307308Добавлено в версии 3.15.309310#### `int PyImport_SetLazyImportsFilter(PyObject *filter)`311312Устанавливает текущий фильтр отложенного импорта. Параметр *filter* должен быть вызываемым объектом, который получит `(importing_module_name, imported_module_name, [fromlist])`, когда импорт может быть отложенным. Значение `imported_module_name` – это разрешённое имя модуля, поэтому `lazy from .spam import eggs` передаёт `package.spam`. Вызываемый объект должен вернуть `True`, если импорт должен быть отложенным, и `False` в противном случае.313314Возвращает `0` при успешном выполнении и `-1` с установленным исключением в противном случае.315316Добавлено в версии 3.15.317318#### `type PyImport_LazyImportsMode`319320Перечисление возможных режимов отложенного импорта.321322#### `enumerator PyImport_LAZY_NORMAL`323324Уважает ключевое слово `lazy` в исходном коде. Это режим по умолчанию.325326#### `enumerator PyImport_LAZY_ALL`327328Делает все импорты отложенными по умолчанию.329330Добавлено в версии 3.15.331332#### `PyObject *PyImport_CreateModuleFromInitfunc(PyObject *spec, PyObject *(*initfunc)(void))`333334Эта функция является строительным блоком, который позволяет встраивающим разработчикам реализовать этап [`create_module()`](https://python-all.ru/3.15/library/importlib.html#importlib.abc.Loader.create_module) пользовательских импортёров статических расширений (например, для статически скомпонованных расширений).335336Параметр *spec* должен быть объектом [`ModuleSpec`](https://python-all.ru/3.15/library/importlib.html#importlib.machinery.ModuleSpec).337338Параметр *initfunc* должен быть [функцией инициализации](https://python-all.ru/3.15/c-api/extension-modules.html#extension-export-hook), такой же, как для [`PyImport_AppendInittab()`](https://python-all.ru/3.15/c-api/import.html#c.PyImport_AppendInittab).339340При успехе создаёт и возвращает объект модуля. Этот модуль не будет инициализирован; для инициализации вызовите [`PyModule_Exec()`](https://python-all.ru/3.15/c-api/module.html#c.PyModule_Exec). (Пользовательские импортёры должны делать это в своём методе [`exec_module()`](https://python-all.ru/3.15/library/importlib.html#importlib.abc.Loader.exec_module).)341342При ошибке возвращает NULL с установленным исключением.343344Добавлено в версии 3.15.345