`import.md`

265 строк · 18.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/c-api/import.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Импорт модулей89**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_ImportModule`(const char *\*name*)**1011*Возвращаемое значение: новая ссылка.*1213Это упрощённый интерфейс к [`PyImport_ImportModuleEx()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ImportModuleEx) (см. ниже), при этом аргументы *globals* и *locals* принимают значение *NULL*, а *level* – 0. Когда аргумент *name* содержит точку (то есть указывает на подмодуль пакета), аргумент *fromlist* устанавливается в список `['*']`, чтобы возвращаемым значением был указанный модуль, а не содержащий его пакет верхнего уровня, как было бы в противном случае. (К сожалению, у этого есть дополнительный побочный эффект, когда *name* на самом деле указывает на подпакет, а не на подмодуль: загружаются подмодули, указанные в переменной `__all__` пакета.) Возвращает новую ссылку на импортированный модуль или *NULL* с установленным исключением в случае ошибки. Неудачный импорт модуля не оставляет модуль в [`sys.modules`](https://python-all.ru/3.1/library/sys.html#sys.modules).1415Эта функция всегда использует абсолютные импорты.1617**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_ImportModuleNoBlock`(const char *\*name*)**1819Эта версия2021[`PyImport_ImportModule()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ImportModule)2223не блокирует. Она предназначена dля использования в функциях C, которые импортируют другие модули для выполнения функции. Импорт может блокироваться, если другой поток удерживает блокировку импорта. Функция2425[`PyImport_ImportModuleNoBlock()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ImportModuleNoBlock)2627никогда не блокируется. Она сначала пытается получить модуль из sys.modules, а в случае неудачи обращается к2829[`PyImport_ImportModule()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ImportModule)3031если только блокировка не удерживается. В последнем случае функция возбуждает исключение3233[`ImportError`](https://python-all.ru/3.1/library/exceptions.html#ImportError)3435.3637**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_ImportModuleEx`(char *\*name*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*locals*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*fromlist*)**3839*Возвращаемое значение: новая ссылка.*4041Импортирует модуль. Лучше всего это описывается встроенной функцией Python [`__import__()`](https://python-all.ru/3.1/library/functions.html#__import__), поскольку стандартная функция [`__import__()`](https://python-all.ru/3.1/library/functions.html#__import__) напрямую вызывает эту функцию.4243Возвращаемое значение – новая ссылка на импортированный модуль или пакет верхнего уровня, или *NULL* с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.1/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist*.4445Неудачные импорты удаляют неполные объекты модулей, как и в [`PyImport_ImportModule()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ImportModule).4647**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_ImportModuleLevel`(char *\*name*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*globals*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*locals*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*fromlist*, int *level*)**4849Импортирует модуль. Лучше всего это описывается встроенной функцией Python [`__import__()`](https://python-all.ru/3.1/library/functions.html#__import__), поскольку стандартная функция [`__import__()`](https://python-all.ru/3.1/library/functions.html#__import__) напрямую вызывает эту функцию.5051Возвращаемое значение – новая ссылка на импортированный модуль или пакет верхнего уровня, или *NULL* с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.1/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist*.5253**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_Import`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*name*)**5455*Возвращаемое значение: новая ссылка.*5657Это интерфейс более высокого уровня, который вызывает текущую «функцию перехвата импорта» (с явным *level*, равным 0, что означает абсолютный импорт). Он вызывает функцию [`__import__()`](https://python-all.ru/3.1/library/functions.html#__import__) из `__builtins__` текущих globals. Это означает, что импорт выполняется с использованием тех перехватчиков импорта, которые установлены в текущем окружении.5859Эта функция всегда использует абсолютные импорты.6061**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_ReloadModule`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*m*)**6263*Возвращаемое значение: новая ссылка.*6465Перезагружает модуль. Возвращает новую ссылку на перезагруженный модуль или *NULL* с установленным исключением в случае неудачи (в этом случае модуль всё ещё существует).6667**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_AddModule`(const char *\*name*)**6869*Возвращаемое значение: заимствованная ссылка.*7071Возвращает объект модуля, соответствующий имени модуля. Аргумент *name* может иметь вид `package.module`. Сначала проверяется словарь модулей, есть ли там такой модуль; если нет, создаётся новый и вставляется в словарь модулей. Возвращает *NULL* с установленным исключением в случае ошибки.7273> **Примечание**74>75> Эта функция не загружает и не импортирует модуль; если модуль ещё не был загружен, будет получен пустой объект модуля. Используйте [`PyImport_ImportModule()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ImportModule) или один из его вариантов для импорта модуля. Структуры пакетов, подразумеваемые составным именем для *name*, не создаются, если их ещё нет.7677**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_ExecCodeModule`(char *\*name*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*co*)**7879*Возвращаемое значение: новая ссылка.*8081Получая имя модуля (возможно, вида `package.module`) и объект кода, прочитанный из файла байт-кода Python или полученный от встроенной функции [`compile()`](https://python-all.ru/3.1/library/functions.html#compile), загружает модуль. Возвращает новую ссылку на объект модуля или *NULL* с установленным исключением, если произошла ошибка. *name* удаляется из [`sys.modules`](https://python-all.ru/3.1/library/sys.html#sys.modules) в случае ошибки, даже если *name* уже был в [`sys.modules`](https://python-all.ru/3.1/library/sys.html#sys.modules) на момент входа в [`PyImport_ExecCodeModule()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ExecCodeModule). Оставлять не полностью инициализированные модули в [`sys.modules`](https://python-all.ru/3.1/library/sys.html#sys.modules) опасно, так как импорты таких модулей не могут узнать, что объект модуля находится в неизвестном (и, вероятно, повреждённом относительно замысла автора модуля) состоянии.8283Эта функция перезагрузит модуль, если он уже был импортирован. См. [`PyImport_ReloadModule()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ReloadModule) – это предназначенный способ перезагрузки модуля.8485Если *name* указывает на составное имя вида `package.module`, любые структуры пакетов, которые ещё не были созданы, по-прежнему не будут созданы.8687**long `PyImport_GetMagicNumber`()**8889Возвращает магическое число для файлов байт-кода Python (также известных как файлы9091`.pyc`9293и9495`.pyo`9697). Магическое число должно находиться в первых четырёх байтах файла байт-кода в порядке little-endian.9899**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_GetModuleDict`()**100101*Возвращаемое значение: заимствованная ссылка.*102103Возвращает словарь, используемый для управления модулями (также известный как `sys.modules`). Обратите внимание, что это переменная на интерпретатор.104105**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `PyImport_GetImporter`([PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*path*)**106107Возвращает объект импортёра для элемента108109[`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path)110111/112113`pkg.__path__`114115*path*116117, возможно получая его из словаря118119[`sys.path_importer_cache`](https://python-all.ru/3.1/library/sys.html#sys.path_importer_cache)120121. Если он ещё не кэширован, проходит по122123[`sys.path_hooks`](https://python-all.ru/3.1/library/sys.html#sys.path_hooks)124125, пока не будет найден хук, способный обработать данный элемент пути. Возвращает126127`None`128129, если ни один хук не подошёл; это сообщает вызывающему коду, что следует вернуться к встроенному механизму импорта. Кэширует результат в130131[`sys.path_importer_cache`](https://python-all.ru/3.1/library/sys.html#sys.path_importer_cache)132133. Возвращает новую ссылку на объект импортёра.134135**void `_PyImport_Init`()**136137Инициализирует механизм импорта. Только для внутреннего использования.138139**void `PyImport_Cleanup`()**140141Очищает таблицу модулей. Только для внутреннего использования.142143**void `_PyImport_Fini`()**144145Завершает работу механизма импорта. Только для внутреннего использования.146147**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `_PyImport_FindExtension`(char *\**, char *\**)**148149Только для внутреннего использования.150151**[PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* `_PyImport_FixupExtension`(char *\**, char *\**)**152153Только для внутреннего использования.154155**int `PyImport_ImportFrozenModule`(char *\*name*)**156157Загружает замороженный модуль с именем158159*name*160161. Возвращает162163`1`164165в случае успеха,166167`0`168169если модуль не найден и170171`-1`172173с установленным исключением, если инициализация не удалась. Для доступа к импортированному модулю после успешной загрузки используйте174175[`PyImport_ImportModule()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ImportModule)176177. (Обратите внимание на неточность в названии – эта функция перезагрузила бы модуль, если бы он уже был импортирован.)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**struct [\_frozen](https://python-all.ru/3.1/c-api/import.html#_frozen)\* `PyImport_FrozenModules`**192193Этот указатель инициализируется так, чтобы указывать на массив записей194195`struct _frozen`196197, заканчивающийся записью, все члены которой равны198199*NULL*200201или нулю. Когда замороженный модуль импортируется, он ищется в этой таблице. Сторонний код может использовать это для предоставления динамически созданной коллекции замороженных модулей.202203**int `PyImport_AppendInittab`(const char *\*name*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject)\* *(\*initfunc)(void)*)**204205Добавляет один модуль в существующую таблицу встроенных модулей. Это удобная обёртка вокруг206207[`PyImport_ExtendInittab()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ExtendInittab)208209, возвращающая210211`-1`212213, если таблицу не удалось расширить. Новый модуль может быть импортирован под именем214215*name*216217и использует функцию218219*initfunc*220221в качестве функции инициализации, вызываемой при первой попытке импорта. Это должно быть вызвано до222223[`Py_Initialize()`](https://python-all.ru/3.1/c-api/init.html#Py_Initialize)224225.226227**struct `_inittab`**228229Структура, описывающая одну запись в списке встроенных модулей. Каждая из этих структур содержит имя и функцию инициализации для модуля, встроенного в интерпретатор. Программы, встраивающие Python, могут использовать массив таких структур совместно с [`PyImport_ExtendInittab()`](https://python-all.ru/3.1/c-api/import.html#PyImport_ExtendInittab) для предоставления дополнительных встроенных модулей. Структура определена в `Include/import.h` следующим образом:230231```c232struct _inittab {233    char *name;234    PyObject* (*initfunc)(void);235};236```237238**int `PyImport_ExtendInittab`(struct [\_inittab](https://python-all.ru/3.1/c-api/import.html#_inittab) *\*newtab*)**239240Добавляет набор модулей в таблицу встроенных модулей. Массив241242*newtab*243244должен заканчиваться сторожевой записью, содержащей245246*NULL*247248в поле249250`name`251252; отсутствие сторожевого значения может привести к ошибке памяти. Возвращает253254`0`255256в случае успеха или257258`-1`259260, если недостаточно памяти для расширения внутренней таблицы. В случае неудачи модули не добавляются во внутреннюю таблицу. Этот вызов должен быть выполнен до261262[`Py_Initialize()`](https://python-all.ru/3.1/c-api/init.html#Py_Initialize)263264.265