`import.md`

261 строк · 18.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/c-api/import.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Импорт модулей89**\[PyImport\_ImportModule\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_ImportModule`(const char *\*name*)**1011*Возвращаемое значение: новая ссылка.*1213Это упрощённый интерфейс к [`PyImport_ImportModuleEx`](https://python-all.ru/3.0/c-api/import.html#PyImport_ImportModuleEx) (см. ниже); аргументы *globals* и *locals* устанавливаются в *NULL*, а *level* – в 0. Когда аргумент *name* содержит точку (то есть указывает на подмодуль пакета), аргумент *fromlist* устанавливается в список `['*']`, так что возвращается именованный модуль, а не содержащий его пакет верхнего уровня, как было бы в противном случае. (К сожалению, это даёт дополнительный побочный эффект, когда *name* на самом деле указывает на подпакет, а не на подмодуль: подмодули, указанные в переменной `__all__` пакета, загружаются.) Возвращает новую ссылку на импортированный модуль или *NULL* с установленным исключением при неудаче. Неудачный импорт модуля не оставляет модуль в [`sys.modules`](https://python-all.ru/3.0/library/sys.html#sys.modules).1415**\[PyImport\_ImportModuleNoBlock\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_ImportModuleNoBlock`(const char *\*name*)**1617Эта версия1819[`PyImport_ImportModule`](https://python-all.ru/3.0/c-api/import.html#PyImport_ImportModule)2021не блокируется. Она предназначена для использования в C-функциях, которые импортируют другие модули для выполнения функции. Импорт может блокироваться, если другой поток удерживает блокировку импорта. Функция2223[`PyImport_ImportModuleNoBlock`](https://python-all.ru/3.0/c-api/import.html#PyImport_ImportModuleNoBlock)2425никогда не блокируется. Сначала она пытается получить модуль из sys.modules, а при неудаче прибегает к2627[`PyImport_ImportModule`](https://python-all.ru/3.0/c-api/import.html#PyImport_ImportModule)2829, если только блокировка не удерживается; в этом случае функция возбуждает исключение3031[`ImportError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ImportError)3233.3435**\[PyImport\_ImportModuleEx\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_ImportModuleEx`(char *\*name*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*fromlist*)**3637*Возвращаемое значение: новая ссылка.*3839Импортирует модуль. Лучше всего это описывается встроенной функцией Python [`__import__()`](https://python-all.ru/3.0/library/functions.html#__import__), поскольку стандартная функция [`__import__()`](https://python-all.ru/3.0/library/functions.html#__import__) напрямую вызывает эту функцию.4041Возвращаемое значение – новая ссылка на импортированный модуль или пакет верхнего уровня, или *NULL* с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.0/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist*.4243Неудачные импорты удаляют неполные объекты модулей, как и [`PyImport_ImportModule`](https://python-all.ru/3.0/c-api/import.html#PyImport_ImportModule).4445**\[PyImport\_ImportModuleLevel\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_ImportModuleLevel`(char *\*name*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*locals*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*fromlist*, int *level*)**4647Импортирует модуль. Лучше всего это описывается встроенной функцией Python [`__import__()`](https://python-all.ru/3.0/library/functions.html#__import__), поскольку стандартная функция [`__import__()`](https://python-all.ru/3.0/library/functions.html#__import__) напрямую вызывает эту функцию.4849Возвращаемое значение – новая ссылка на импортированный модуль или пакет верхнего уровня, или *NULL* с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.0/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist*.5051**\[PyImport\_Import\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_Import`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*name*)**5253*Возвращаемое значение: новая ссылка.*5455Это интерфейс более высокого уровня, который вызывает текущую «функцию перехвата импорта» (с явным *level*, равным 0, что означает абсолютный импорт). Он вызывает функцию [`__import__()`](https://python-all.ru/3.0/library/functions.html#__import__) из `__builtins__` текущих globals. Это означает, что импорт выполняется с использованием тех перехватчиков импорта, которые установлены в текущем окружении.5657**\[PyImport\_ReloadModule\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_ReloadModule`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*m*)**5859*Возвращаемое значение: новая ссылка.*6061Перезагружает модуль. Возвращает новую ссылку на перезагруженный модуль или *NULL* с установленным исключением в случае неудачи (в этом случае модуль всё ещё существует).6263**\[PyImport\_AddModule\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_AddModule`(const char *\*name*)**6465*Возвращаемое значение: заимствованная ссылка.*6667Возвращает объект модуля, соответствующий имени модуля. Аргумент *name* может иметь вид `package.module`. Сначала проверяется словарь модулей, есть ли там такой модуль; если нет, создаётся новый и вставляется в словарь модулей. Возвращает *NULL* с установленным исключением в случае ошибки.6869> **Примечание**70>71> Эта функция не загружает и не импортирует модуль; если модуль ещё не был загружен, вы получите пустой объект модуля. Используйте [`PyImport_ImportModule`](https://python-all.ru/3.0/c-api/import.html#PyImport_ImportModule) или один из его вариантов для импорта модуля. Структуры пакетов, подразумеваемые составным именем для *name*, не создаются, если их ещё нет.7273**\[PyImport\_ExecCodeModule\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_ExecCodeModule`(char *\*name*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*co*)**7475*Возвращаемое значение: новая ссылка.*7677Получив имя модуля (возможно, в форме `package.module`) и объект кода, прочитанный из файла байт-кода Python или полученный от встроенной функции [`compile()`](https://python-all.ru/3.0/library/functions.html#compile), загрузите модуль. Возвращает новую ссылку на объект модуля или *NULL* с установленным исключением, если произошла ошибка. В случае ошибки *name* удаляется из [`sys.modules`](https://python-all.ru/3.0/library/sys.html#sys.modules), даже если *name* уже был в [`sys.modules`](https://python-all.ru/3.0/library/sys.html#sys.modules) на момент входа в [`PyImport_ExecCodeModule`](https://python-all.ru/3.0/c-api/import.html#PyImport_ExecCodeModule). Оставлять неполностью инициализированные модули в [`sys.modules`](https://python-all.ru/3.0/library/sys.html#sys.modules) опасно, так как импорты таких модулей не могут знать, что объект модуля находится в неизвестном (и, вероятно, повреждённом относительно намерений автора модуля) состоянии.7879Эта функция перезагрузит модуль, если он уже был импортирован. См. [`PyImport_ReloadModule`](https://python-all.ru/3.0/c-api/import.html#PyImport_ReloadModule) для правильного способа перезагрузки модуля.8081Если *name* указывает на составное имя вида `package.module`, любые структуры пакетов, которые ещё не были созданы, по-прежнему не будут созданы.8283**\[PyImport\_GetMagicNumber\]long `PyImport_GetMagicNumber`()**8485Возвращает магическое число для файлов байт-кода Python (также известных как файлы8687`.pyc`8889и9091`.pyo`9293). Магическое число должно находиться в первых четырёх байтах файла байт-кода в порядке little-endian.9495**\[PyImport\_GetModuleDict\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_GetModuleDict`()**9697*Возвращаемое значение: заимствованная ссылка.*9899Возвращает словарь, используемый для управления модулями (также известный как `sys.modules`). Обратите внимание, что это переменная на интерпретатор.100101**\[PyImport\_GetImporter\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `PyImport_GetImporter`([PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject) *\*path*)**102103Возвращает объект импортёра для элемента104105[`sys.path`](https://python-all.ru/3.0/library/sys.html#sys.path)106107/108109`pkg.__path__`110111*path*112113, возможно, получая его из словаря114115`sys.path_importer_cache`116117. Если он ещё не кеширован, просматривает118119`sys.path_hooks`120121, пока не будет найден хук, способный обработать элемент пути. Возвращает122123`None`124125, если ни один хук не подошёл; это говорит вызывающему коду, что следует прибегнуть к встроенному механизму импорта. Кеширует результат в126127`sys.path_importer_cache`128129. Возвращает новую ссылку на объект импортёра.130131**\[\_PyImport\_Init\]void `_PyImport_Init`()**132133Инициализирует механизм импорта. Только для внутреннего использования.134135**\[PyImport\_Cleanup\]void `PyImport_Cleanup`()**136137Очищает таблицу модулей. Только для внутреннего использования.138139**\[\_PyImport\_Fini\]void `_PyImport_Fini`()**140141Завершает работу механизма импорта. Только для внутреннего использования.142143**\[\_PyImport\_FindExtension\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `_PyImport_FindExtension`(char *\**, char *\**)**144145Только для внутреннего использования.146147**\[\_PyImport\_FixupExtension\][PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* `_PyImport_FixupExtension`(char *\**, char *\**)**148149Только для внутреннего использования.150151**\[PyImport\_ImportFrozenModule\]int `PyImport_ImportFrozenModule`(char *\*name*)**152153Загружает замороженный модуль с именем154155*name*156157. Возвращает158159`1`160161в случае успеха,162163`0`164165если модуль не найден, и166167`-1`168169с установленным исключением, если инициализация не удалась. Чтобы получить доступ к импортированному модулю при успешной загрузке, используйте170171[`PyImport_ImportModule`](https://python-all.ru/3.0/c-api/import.html#PyImport_ImportModule)172173. (Обратите внимание на неточность названия – эта функция перезагрузит модуль, если он уже был импортирован.)174175**\[\_frozen\]struct `_frozen`**176177Это определение типа структуры для дескрипторов замороженных модулей, создаваемое утилитой **freeze** (см. `Tools/freeze/` в дистрибутиве исходного кода Python). Её определение находится в `Include/import.h`:178179```c180struct _frozen {181    char *name;182    unsigned char *code;183    int size;184};185```186187**\[PyImport\_FrozenModules\]struct [\_frozen](https://python-all.ru/3.0/c-api/import.html#_frozen)\* `PyImport_FrozenModules`**188189Этот указатель инициализируется так, чтобы указывать на массив записей190191`struct _frozen`192193, заканчивающийся записью, все члены которой равны194195*NULL*196197или нулю. Когда замороженный модуль импортируется, он ищется в этой таблице. Сторонний код может использовать это для предоставления динамически созданной коллекции замороженных модулей.198199**\[PyImport\_AppendInittab\]int `PyImport_AppendInittab`(char *\*name*, [PyObject](https://python-all.ru/3.0/c-api/structures.html#PyObject)\* *(\*initfunc)(void)*)**200201Добавляет один модуль в существующую таблицу встроенных модулей. Это удобная обёртка вокруг202203[`PyImport_ExtendInittab`](https://python-all.ru/3.0/c-api/import.html#PyImport_ExtendInittab)204205, возвращающая206207`-1`208209, если таблицу не удалось расширить. Новый модуль можно импортировать по имени210211*name*212213, и он использует функцию214215*initfunc*216217в качестве функции инициализации, вызываемой при первой попытке импорта. Это должно быть вызвано до218219[`Py_Initialize`](https://python-all.ru/3.0/c-api/init.html#Py_Initialize)220221.222223**\[\_inittab\]struct `_inittab`**224225Структура, описывающая одну запись в списке встроенных модулей. Каждая из этих структур задаёт имя и функцию инициализации для модуля, встроенного в интерпретатор. Программы, встраивающие Python, могут использовать массив таких структур совместно с [`PyImport_ExtendInittab`](https://python-all.ru/3.0/c-api/import.html#PyImport_ExtendInittab) для предоставления дополнительных встроенных модулей. Структура определена в `Include/import.h` как:226227```c228struct _inittab {229    char *name;230    PyObject* (*initfunc)(void);231};232```233234**\[PyImport\_ExtendInittab\]int `PyImport_ExtendInittab`(struct [\_inittab](https://python-all.ru/3.0/c-api/import.html#_inittab) *\*newtab*)**235236Добавляет набор модулей в таблицу встроенных модулей. Массив237238*newtab*239240должен заканчиваться сторожевым элементом, содержащим241242*NULL*243244в поле245246`name`247248; отсутствие сторожевого значения может привести к ошибке памяти. Возвращает249250`0`251252в случае успеха или253254`-1`255256, если недостаточно памяти для расширения внутренней таблицы. В случае ошибки модули не добавляются во внутреннюю таблицу. Должна вызываться до257258[`Py_Initialize`](https://python-all.ru/3.0/c-api/init.html#Py_Initialize)259260.261