import.md

1> **Источник:** https://python-all.ru/3.6/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Это упрощённый интерфейс к [`PyImport_ImportModuleEx()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ImportModuleEx) ниже, оставляющий аргументы *globals* и *locals* установленными в *NULL*, а *level* – в 0. Когда аргумент *name* содержит точку (то есть задаёт подмодуль пакета), аргумент *fromlist* устанавливается равным списку `['*']`, так что возвращаемое значение – это именованный модуль, а не содержащий его пакет верхнего уровня, как было бы в противном случае. (К сожалению, это даёт дополнительный побочный эффект, когда *name* на самом деле задаёт подпакет, а не подмодуль: подмодули, указанные в переменной `__all__` пакета, загружаются.) Возвращает новую ссылку на импортированный модуль или *NULL* с установленным исключением в случае неудачи. Неудачный импорт модуля не оставляет модуль в [`sys.modules`](https://python-all.ru/3.6/library/sys.html#sys.modules).1415Эта функция всегда использует абсолютные импорты.1617#### `PyObject* PyImport_ImportModuleNoBlock(const char *name)`1819Эта функция – устаревший псевдоним [`PyImport_ImportModule()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ImportModule).2021Изменено в версии 3.3: Ранее эта функция немедленно завершалась ошибкой, если блокировка импорта удерживалась другим потоком. Однако в Python 3.3 схема блокировки была изменена на блокировки на уровне модулей для большинства случаев, поэтому специальное поведение этой функции больше не требуется.2223#### `PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)`2425*Возвращаемое значение: новая ссылка.*2627Импорт модуля. Лучше всего это описывается через встроенную функцию Python [`__import__()`](https://python-all.ru/3.6/library/functions.html#__import__).2829Возвращаемое значение – это новая ссылка на импортированный модуль или пакет верхнего уровня, или *NULL* с установленным исключением в случае неудачи. Как и для [`__import__()`](https://python-all.ru/3.6/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был указан непустой *fromlist*.3031Неудачные импорты удаляют неполные объекты модулей, как и [`PyImport_ImportModule()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ImportModule).3233#### `PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)`3435*Возвращаемое значение: новая ссылка.*3637Импорт модуля. Наилучшее описание даётся через встроенную функцию Python [`__import__()`](https://python-all.ru/3.6/library/functions.html#__import__), поскольку стандартная функция [`__import__()`](https://python-all.ru/3.6/library/functions.html#__import__) вызывает эту функцию напрямую.3839Возвращаемое значение – это новая ссылка на импортированный модуль или пакет верхнего уровня, или *NULL* с установленным исключением в случае неудачи. Как и для [`__import__()`](https://python-all.ru/3.6/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был указан непустой *fromlist*.4041Новое в версии 3.3.4243#### `PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)`4445*Возвращаемое значение: новая ссылка.*4647Аналогично [`PyImport_ImportModuleLevelObject()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ImportModuleLevelObject), но имя представляет собой строку в кодировке UTF-8 вместо объекта Unicode.4849Изменено в версии 3.3: Отрицательные значения для *level* больше не принимаются.5051#### `PyObject* PyImport_Import(PyObject *name)`5253*Возвращаемое значение: новая ссылка.*5455Это интерфейс более высокого уровня, который вызывает текущую «функцию перехвата импорта» (с явным *level* равным 0, что означает абсолютный импорт). Он вызывает функцию [`__import__()`](https://python-all.ru/3.6/library/functions.html#__import__) из `__builtins__` текущих глобальных переменных. Это означает, что импорт выполняется с использованием тех перехватчиков импорта, которые установлены в текущем окружении.5657Эта функция всегда использует абсолютные импорты.5859#### `PyObject* PyImport_ReloadModule(PyObject *m)`6061*Возвращаемое значение: новая ссылка.*6263Перезагружает модуль. Возвращает новую ссылку на перезагруженный модуль или *NULL* с установленным исключением в случае неудачи (в этом случае модуль всё ещё существует).6465#### `PyObject* PyImport_AddModuleObject(PyObject *name)`6667*Возвращаемое значение: заимствованная ссылка.*6869Возвращает объект модуля, соответствующий имени модуля. Аргумент *name* может иметь вид `package.module`. Сначала проверяется словарь модулей, есть ли он там; если нет, создаётся новый и вставляется в словарь модулей. Возвращает *NULL* с установленным исключением в случае неудачи.7071> **Примечание**72>73> Эта функция не загружает и не импортирует модуль; если модуль ещё не был загружен, возвращается пустой объект модуля. Для импорта модуля используйте [`PyImport_ImportModule()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ImportModule) или один из его вариантов. Структуры пакетов, подразумеваемые точечным именем для *name*, не создаются, если их ещё нет.7475Новое в версии 3.3.7677#### `PyObject* PyImport_AddModule(const char *name)`7879*Возвращаемое значение: заимствованная ссылка.*8081Аналогично [`PyImport_AddModuleObject()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_AddModuleObject), но имя передаётся в виде строки в кодировке UTF-8, а не как объект Unicode.8283#### `PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)`8485*Возвращаемое значение: новая ссылка.*8687По заданному имени модуля (возможно, вида `package.module`) и объекту кода, прочитанному из файла байт-кода Python или полученному от встроенной функции [`compile()`](https://python-all.ru/3.6/library/functions.html#compile), загружает модуль. Возвращает новую ссылку на объект модуля или *NULL* с установленным исключением при ошибке. В случае ошибки *name* удаляется из [`sys.modules`](https://python-all.ru/3.6/library/sys.html#sys.modules), даже если *name* уже находился в [`sys.modules`](https://python-all.ru/3.6/library/sys.html#sys.modules) на момент входа в [`PyImport_ExecCodeModule()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ExecCodeModule). Оставлять не полностью инициализированные модули в [`sys.modules`](https://python-all.ru/3.6/library/sys.html#sys.modules) опасно, так как импорт таких модулей не может узнать, что объект модуля находится в неизвестном (и, вероятно, повреждённом относительно замысла автора модуля) состоянии.8889Атрибуты [`__spec__`](https://python-all.ru/3.6/reference/import.html#__spec__) и [`__loader__`](https://python-all.ru/3.6/reference/import.html#__loader__) модуля будут установлены, если ещё не установлены, в соответствующие значения. Загрузчик спецификации будет установлен в `__loader__` модуля (если он задан), в противном случае – в экземпляр `SourceFileLoader`.9091Атрибут [`__file__`](https://python-all.ru/3.6/reference/import.html#__file__) модуля будет установлен в значение `co_filename` объекта кода. Если применимо, будет также установлен атрибут [`__cached__`](https://python-all.ru/3.6/reference/import.html#__cached__).9293Эта функция перезагрузит модуль, если он уже был импортирован. См. [`PyImport_ReloadModule()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ReloadModule) для описания правильного способа перезагрузки модуля.9495Если *name* указывает на имя с точками вида `package.module`, любые структуры пакета, которые ещё не были созданы, по-прежнему не будут созданы.9697См. также [`PyImport_ExecCodeModuleEx()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ExecCodeModuleEx) и [`PyImport_ExecCodeModuleWithPathnames()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ExecCodeModuleWithPathnames).9899#### `PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)`100101*Возвращаемое значение: новая ссылка.*102103Как и [`PyImport_ExecCodeModule()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ExecCodeModule), но атрибут [`__file__`](https://python-all.ru/3.6/reference/import.html#__file__) объекта модуля устанавливается в *pathname*, если он не равен `NULL`.104105См. также [`PyImport_ExecCodeModuleWithPathnames()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ExecCodeModuleWithPathnames).106107#### `PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)`108109*Возвращаемое значение: новая ссылка.*110111Как и [`PyImport_ExecCodeModuleEx()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ExecCodeModuleEx), но атрибут [`__cached__`](https://python-all.ru/3.6/reference/import.html#__cached__) объекта модуля устанавливается в *cpathname*, если он не равен `NULL`. Из трёх функций эта является предпочтительной.112113Новое в версии 3.3.114115#### `PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)`116117*Возвращаемое значение: новая ссылка.*118119Как [`PyImport_ExecCodeModuleObject()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ExecCodeModuleObject), но *name*, *pathname* и *cpathname* являются строками в кодировке UTF-8. Также предпринимаются попытки выяснить, каким должно быть значение *pathname* из *cpathname*, если первое установлено в `NULL`.120121Новое в версии 3.2.122123Изменено в версии 3.3: Использует [`imp.source_from_cache()`](https://python-all.ru/3.6/library/imp.html#imp.source_from_cache) при вычислении пути к исходному коду, если указан только путь к байткоду.124125#### `long PyImport_GetMagicNumber()`126127Возвращает магическое число для файлов байткода Python (также известных как файлы `.pyc`). Магическое число должно присутствовать в первых четырёх байтах файла байткода в порядке little-endian. В случае ошибки возвращает `-1`.128129Изменено в версии 3.3: Возвращает `-1` в случае неудачи.130131#### `const char * PyImport_GetMagicTag()`132133Возвращает строку магического тега для имён файлов байткода Python в формате [**PEP 3147**](https://python-all.ru/3.6/c-api/import.html). Имейте в виду, что значение в `sys.implementation.cache_tag` является авторитетным и должно использоваться вместо этой функции.134135Новое в версии 3.2.136137#### `PyObject* PyImport_GetModuleDict()`138139*Возвращаемое значение: заимствованная ссылка.*140141Возвращает словарь, используемый для администрирования модулей (также известный как `sys.modules`). Обратите внимание, что это переменная, отдельная для каждого интерпретатора.142143#### `PyObject* PyImport_GetImporter(PyObject *path)`144145*Возвращаемое значение: новая ссылка.*146147Возвращает объект поиска для элемента [`sys.path`](https://python-all.ru/3.6/library/sys.html#sys.path)/`pkg.__path__` *path*, возможно, извлекая его из словаря [`sys.path_importer_cache`](https://python-all.ru/3.6/library/sys.html#sys.path_importer_cache). Если он ещё не кэширован, обходит [`sys.path_hooks`](https://python-all.ru/3.6/library/sys.html#sys.path_hooks), пока не будет найден хук, способный обработать элемент пути. Возвращает `None`, если ни один хук не подошёл; это сообщает вызывающей стороне, что [поисковик на основе пути](https://python-all.ru/3.6/glossary.html#term-path-based-finder) не смог найти поисковик для этого элемента пути. Кэширует результат в [`sys.path_importer_cache`](https://python-all.ru/3.6/library/sys.html#sys.path_importer_cache). Возвращает новую ссылку на объект поисковика.148149#### `void _PyImport_Init()`150151Инициализирует механизм импорта. Только для внутреннего использования.152153#### `void PyImport_Cleanup()`154155Очищает таблицу модулей. Только для внутреннего использования.156157#### `void _PyImport_Fini()`158159Завершает работу механизма импорта. Только для внутреннего использования.160161#### `PyObject* _PyImport_FindExtension(char *, char *)`162163Только для внутреннего использования.164165#### `int PyImport_ImportFrozenModuleObject(PyObject *name)`166167*Возвращаемое значение: новая ссылка.*168169Загружает замороженный модуль с именем *name*. Возвращает `1` при успехе, `0`, если модуль не найден, и `-1` с установленным исключением, если инициализация не удалась. Чтобы получить доступ к импортированному модулю после успешной загрузки, используйте [`PyImport_ImportModule()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ImportModule). (Обратите внимание на неточность названия – эта функция перезагрузила бы модуль, если он уже был импортирован.)170171Новое в версии 3.3.172173Изменено в версии 3.4: Атрибут `__file__` больше не устанавливается в модуле.174175#### `int PyImport_ImportFrozenModule(const char *name)`176177Аналогично [`PyImport_ImportFrozenModuleObject()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ImportFrozenModuleObject), но имя представляет собой строку в кодировке UTF-8 вместо объекта Unicode.178179**struct `_frozen`**180181Это определение типа структуры для дескрипторов замороженных модулей, как сгенерировано утилитой **freeze** (см. `Tools/freeze/` в дистрибутиве исходного кода Python). Её определение находится в `Include/import.h`:182183```c184struct _frozen {185    char *name;186    unsigned char *code;187    int size;188};189```190191**const struct [\_frozen](https://python-all.ru/3.6/c-api/import.html#c._frozen)\* `PyImport_FrozenModules`**192193Этот указатель инициализируется так, чтобы указывать на массив записей `struct _frozen`, завершающийся записью, все члены которой равны *NULL* или нулю. При импорте замороженного модуля поиск выполняется в этой таблице. Сторонний код может использовать это для предоставления динамически создаваемого набора замороженных модулей.194195#### `int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))`196197Добавляет один модуль в существующую таблицу встроенных модулей. Это удобная обёртка вокруг [`PyImport_ExtendInittab()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ExtendInittab), возвращающая `-1`, если таблицу не удалось расширить. Новый модуль можно импортировать по имени *name*, и он использует функцию *initfunc* в качестве функции инициализации, вызываемой при первой попытке импорта. Это должно вызываться до [`Py_Initialize()`](https://python-all.ru/3.6/c-api/init.html#c.Py_Initialize).198199**struct `_inittab`**200201Структура, описывающая одну запись в списке встроенных модулей. Каждая из этих структур содержит имя и функцию инициализации для модуля, встроенного в интерпретатор. Имя – это строка в кодировке ASCII. Программы, встраивающие Python, могут использовать массив таких структур совместно с [`PyImport_ExtendInittab()`](https://python-all.ru/3.6/c-api/import.html#c.PyImport_ExtendInittab) для добавления дополнительных встроенных модулей. Структура определена в `Include/import.h` следующим образом:202203```c204struct _inittab {205    char *name;                 /* Строка в кодировке ASCII */206    PyObject* (*initfunc)(void);207};208```209210#### `int PyImport_ExtendInittab(struct _inittab *newtab)`211212Добавляет набор модулей в таблицу встроенных модулей. Массив *newtab* должен заканчиваться сторожевой записью, содержащей *NULL* для поля `name`; отсутствие сторожевого значения может привести к ошибке памяти. Возвращает `0` при успехе или `-1`, если для расширения внутренней таблицы не удалось выделить достаточно памяти. В случае неудачи ни один модуль не добавляется во внутреннюю таблицу. Эта функция должна вызываться до [`Py_Initialize()`](https://python-all.ru/3.6/c-api/init.html#c.Py_Initialize).213