import.md

1> **Источник:** https://python-all.ru/2.7/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/2.7/c-api/import.html#c.PyImport_ImportModuleEx) ниже, оставляя аргументы *globals* и *locals* равными *NULL*, а *level* – нулю. Когда аргумент *name* содержит точку (то есть указывает на вложенный модуль пакета), аргумент *fromlist* устанавливается в список `['*']`, чтобы возвращаемым значением был именно указанный модуль, а не содержащий его пакет верхнего уровня, как было бы в противном случае. (К сожалению, это даёт дополнительный побочный эффект, когда *name* на самом деле задаёт подпакет, а не подмодуль: подмодули, перечисленные в переменной `__all__` пакета, загружаются.) Возвращает новую ссылку на импортированный модуль или *NULL* с установленным исключением в случае ошибки. До Python 2.4 модуль мог создаваться даже в случае ошибки – для проверки используйте `sys.modules`. Начиная с Python 2.4, неудачный импорт модуля больше не оставляет модуль в `sys.modules`.1415Изменено в версии 2.4: Неудачные импорты удаляют незавершённые объекты модуля.1617Изменено в версии 2.6: Всегда использует абсолютные импорты.1819#### `PyObject* PyImport_ImportModuleNoBlock(const char *name)`2021Эта версия [`PyImport_ImportModule()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ImportModule) не блокируется. Она предназначена dля использования в C-функциях, которые импортируют другие модули для выполнения функции. Импорт может блокироваться, если другой поток удерживает блокировку импорта. Функция [`PyImport_ImportModuleNoBlock()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ImportModuleNoBlock) никогда не блокируется. Сначала она пытается получить модуль из sys.modules, а при неудаче вызывает [`PyImport_ImportModule()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ImportModule), если только блокировка не удерживается; в этом случае функция возбуждает [`ImportError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ImportError).2223Новое в версии 2.6.2425#### `PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)`2627*Возвращаемое значение: новая ссылка.*2829Импорт модуля. Наилучшее описание даётся через встроенную функцию Python [`__import__()`](https://python-all.ru/2.7/library/functions.html#__import__), поскольку стандартная функция [`__import__()`](https://python-all.ru/2.7/library/functions.html#__import__) вызывает эту функцию напрямую.3031Возвращаемое значение – новая ссылка на импортированный модуль или пакет верхнего уровня, либо *NULL* с установленным исключением в случае ошибки (до Python 2.4 модуль мог быть создан и в этом случае). Как и для [`__import__()`](https://python-all.ru/2.7/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist*.3233Изменено в версии 2.4: Неудачные импорты удаляют незавершённые объекты модуля.3435Изменено в версии 2.6: Функция является псевдонимом для [`PyImport_ImportModuleLevel()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ImportModuleLevel) с `-1` в качестве level, что означает относительный импорт.3637#### `PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)`3839*Возвращаемое значение: новая ссылка.*4041Импорт модуля. Наилучшее описание даётся через встроенную функцию Python [`__import__()`](https://python-all.ru/2.7/library/functions.html#__import__), поскольку стандартная функция [`__import__()`](https://python-all.ru/2.7/library/functions.html#__import__) вызывает эту функцию напрямую.4243Возвращаемое значение – это новая ссылка на импортированный модуль или пакет верхнего уровня, или *NULL* с установленным исключением в случае неудачи. Как и для [`__import__()`](https://python-all.ru/2.7/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был указан непустой *fromlist*.4445Новое в версии 2.5.4647#### `PyObject* PyImport_Import(PyObject *name)`4849*Возвращаемое значение: новая ссылка.*5051Это интерфейс более высокого уровня, который вызывает текущую «функцию перехвата импорта». Он вызывает функцию [`__import__()`](https://python-all.ru/2.7/library/functions.html#__import__) из `__builtins__` текущих глобальных переменных. Это означает, что импорт выполняется с использованием любых перехватчиков импорта, установленных в текущем окружении, например, с помощью [`rexec`](https://python-all.ru/2.7/library/rexec.html#module-rexec) или `ihooks`.5253Изменено в версии 2.6: Всегда использует абсолютные импорты.5455#### `PyObject* PyImport_ReloadModule(PyObject *m)`5657*Возвращаемое значение: новая ссылка.*5859Перезагружает модуль. Лучше всего это описывается обращением к встроенной функции Python [`reload()`](https://python-all.ru/2.7/library/functions.html#reload), поскольку стандартная функция [`reload()`](https://python-all.ru/2.7/library/functions.html#reload) напрямую вызывает эту функцию. Возвращает новую ссылку на перезагруженный модуль или *NULL* с установленным исключением в случае ошибки (модуль в этом случае всё ещё существует).6061#### `PyObject* PyImport_AddModule(const char *name)`6263*Возвращаемое значение: заимствованная ссылка.*6465Возвращает объект модуля, соответствующий имени модуля. Аргумент *name* может иметь вид `package.module`. Сначала проверяется словарь модулей, есть ли он там; если нет, создаётся новый и вставляется в словарь модулей. Возвращает *NULL* с установленным исключением в случае неудачи.6667> **Примечание**68>69> Эта функция не загружает и не импортирует модуль; если модуль ещё не был загружен, возвращается пустой объект модуля. Для импорта модуля используйте [`PyImport_ImportModule()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ImportModule) или один из его вариантов. Структуры пакетов, подразумеваемые точечным именем для *name*, не создаются, если их ещё нет.7071#### `PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)`7273*Возвращаемое значение: новая ссылка.*7475Принимая имя модуля (возможно, вида `package.module`) и объект кода, прочитанный из файла байт-кода Python или полученный от встроенной функции [`compile()`](https://python-all.ru/2.7/library/functions.html#compile), загружает модуль. Возвращает новую ссылку на объект модуля или *NULL* с установленным исключением, если произошла ошибка. До Python 2.4 модуль мог быть создан даже в случае ошибки. Начиная с Python 2.4, *name* удаляется из [`sys.modules`](https://python-all.ru/2.7/library/sys.html#sys.modules) в случае ошибки, даже если *name* уже находился в [`sys.modules`](https://python-all.ru/2.7/library/sys.html#sys.modules) на момент вызова [`PyImport_ExecCodeModule()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ExecCodeModule). Оставление неполностью инициализированных модулей в [`sys.modules`](https://python-all.ru/2.7/library/sys.html#sys.modules) опасно, так как импорт таких модулей не может определить, что объект модуля находится в неизвестном (и, вероятно, повреждённом относительно намерений автора модуля) состоянии.7677Атрибут `__file__` модуля будет установлен в `co_filename` объекта кода.7879Эта функция перезагрузит модуль, если он уже был импортирован. См. [`PyImport_ReloadModule()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ReloadModule) для описания правильного способа перезагрузки модуля.8081Если *name* указывает на имя с точками вида `package.module`, любые структуры пакета, которые ещё не были созданы, по-прежнему не будут созданы.8283Изменено в версии 2.4: *name* удаляется из [`sys.modules`](https://python-all.ru/2.7/library/sys.html#sys.modules) в случае ошибки.8485#### `PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)`8687*Возвращаемое значение: новая ссылка.*8889Как и [`PyImport_ExecCodeModule()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ExecCodeModule), но атрибут `__file__` объекта модуля устанавливается в *pathname*, если он не равен `NULL`.9091#### `long PyImport_GetMagicNumber()`9293Возвращает магическое число для файлов байт-кода Python (также известных как файлы `.pyc` и `.pyo`). Магическое число должно находиться в первых четырёх байтах файла байт-кода, в порядке байтов little-endian.9495#### `PyObject* PyImport_GetModuleDict()`9697*Возвращаемое значение: заимствованная ссылка.*9899Возвращает словарь, используемый для администрирования модулей (также известный как `sys.modules`). Обратите внимание, что это переменная, отдельная для каждого интерпретатора.100101#### `PyObject* PyImport_GetImporter(PyObject *path)`102103Возвращает объект импортёра для элемента [`sys.path`](https://python-all.ru/2.7/library/sys.html#sys.path)/`pkg.__path__` *path*, возможно извлекая его из словаря [`sys.path_importer_cache`](https://python-all.ru/2.7/library/sys.html#sys.path_importer_cache). Если он ещё не кэширован, обходит [`sys.path_hooks`](https://python-all.ru/2.7/library/sys.html#sys.path_hooks), пока не будет найден перехватчик, способный обработать элемент пути. Возвращает `None`, если перехватчик не найден; это указывает вызывающей стороне, что следует вернуться к встроенному механизму импорта. Кэширует результат в [`sys.path_importer_cache`](https://python-all.ru/2.7/library/sys.html#sys.path_importer_cache). Возвращает новую ссылку на объект импортёра.104105Новое в версии 2.6.106107#### `void _PyImport_Init()`108109Инициализирует механизм импорта. Только для внутреннего использования.110111#### `void PyImport_Cleanup()`112113Очищает таблицу модулей. Только для внутреннего использования.114115#### `void _PyImport_Fini()`116117Завершает работу механизма импорта. Только для внутреннего использования.118119#### `PyObject* _PyImport_FindExtension(char *, char *)`120121Только для внутреннего использования.122123#### `PyObject* _PyImport_FixupExtension(char *, char *)`124125Только для внутреннего использования.126127#### `int PyImport_ImportFrozenModule(char *name)`128129Загружает замороженный модуль с именем *name*. Возвращает `1` при успехе, `0`, если модуль не найден, и `-1` с установленным исключением, если инициализация не удалась. Чтобы получить доступ к импортированному модулю после успешной загрузки, используйте [`PyImport_ImportModule()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ImportModule). (Обратите внимание на неточность названия – эта функция перезагрузила бы модуль, если он уже был импортирован.)130131**struct `_frozen`**132133Это определение типа структуры для дескрипторов замороженных модулей, как сгенерировано утилитой **freeze** (см. `Tools/freeze/` в дистрибутиве исходного кода Python). Её определение находится в `Include/import.h`:134135```c136struct _frozen {137    char *name;138    unsigned char *code;139    int size;140};141```142143**struct [\_frozen](https://python-all.ru/2.7/c-api/import.html#c._frozen)\* `PyImport_FrozenModules`**144145Этот указатель инициализируется так, чтобы указывать на массив записей `struct _frozen`, завершающийся записью, все члены которой равны *NULL* или нулю. При импорте замороженного модуля поиск выполняется в этой таблице. Сторонний код может использовать это для предоставления динамически создаваемого набора замороженных модулей.146147#### `int PyImport_AppendInittab(const char *name, void (*initfunc)(void))`148149Добавляет один модуль в существующую таблицу встроенных модулей. Это удобная обёртка вокруг [`PyImport_ExtendInittab()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ExtendInittab), возвращающая `-1`, если таблицу не удалось расширить. Новый модуль можно импортировать по имени *name*, и он использует функцию *initfunc* в качестве функции инициализации, вызываемой при первой попытке импорта. Это должно вызываться до [`Py_Initialize()`](https://python-all.ru/2.7/c-api/init.html#c.Py_Initialize).150151**struct `_inittab`**152153Структура, описывающая одну запись в списке встроенных модулей. Каждая из этих структур содержит имя и функцию инициализации для модуля, встроенного в интерпретатор. Программы, встраивающие Python, могут использовать массив таких структур в сочетании с [`PyImport_ExtendInittab()`](https://python-all.ru/2.7/c-api/import.html#c.PyImport_ExtendInittab) для предоставления дополнительных встроенных модулей. Структура определена в `Include/import.h` следующим образом:154155```c156struct _inittab {157    char *name;158    void (*initfunc)(void);159};160```161162#### `int PyImport_ExtendInittab(struct _inittab *newtab)`163164Добавляет набор модулей в таблицу встроенных модулей. Массив *newtab* должен заканчиваться сторожевой записью, содержащей *NULL* для поля `name`; отсутствие сторожевого значения может привести к ошибке памяти. Возвращает `0` при успехе или `-1`, если для расширения внутренней таблицы не удалось выделить достаточно памяти. В случае неудачи ни один модуль не добавляется во внутреннюю таблицу. Эта функция должна вызываться до [`Py_Initialize()`](https://python-all.ru/2.7/c-api/init.html#c.Py_Initialize).165