> **Источник:** https://python-all.ru/3.4/c-api/import.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Импорт модулей #### `PyObject* PyImport_ImportModule(const char *name)` *Возвращаемое значение: новая ссылка.* Это упрощённый интерфейс к [`PyImport_ImportModuleEx()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ImportModuleEx) (см. ниже), при этом аргументы *globals* и *locals* принимают значение *NULL*, а *level* – 0. Когда аргумент *name* содержит точку (то есть указывает на подмодуль пакета), аргумент *fromlist* устанавливается в список `['*']`, чтобы возвращаемым значением был указанный модуль, а не содержащий его пакет верхнего уровня, как было бы в противном случае. (К сожалению, у этого есть дополнительный побочный эффект, когда *name* на самом деле указывает на подпакет, а не на подмодуль: загружаются подмодули, указанные в переменной `__all__` пакета.) Возвращает новую ссылку на импортированный модуль или *NULL* с установленным исключением в случае ошибки. Неудачный импорт модуля не оставляет модуль в [`sys.modules`](https://python-all.ru/3.4/library/sys.html#sys.modules). Эта функция всегда использует абсолютные импорты. #### `PyObject* PyImport_ImportModuleNoBlock(const char *name)` Эта функция является устаревшим псевдонимом [`PyImport_ImportModule()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ImportModule). Изменено в версии 3.3: Ранее эта функция немедленно завершалась ошибкой, если блокировка импорта удерживалась другим потоком. Однако в Python 3.3 схема блокировки была изменена на блокировки на уровне модулей для большинства случаев, поэтому специальное поведение этой функции больше не требуется. #### `PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)` *Возвращаемое значение: новая ссылка.* Импортирует модуль. Лучше всего это описывается встроенной функцией Python [`__import__()`](https://python-all.ru/3.4/library/functions.html#__import__). Возвращаемое значение – новая ссылка на импортированный модуль или пакет верхнего уровня, или *NULL* с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.4/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist*. Неудачные импорты удаляют неполные объекты модулей, как и в [`PyImport_ImportModule()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ImportModule). #### `PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)` Импортирует модуль. Лучше всего это описывается встроенной функцией Python [`__import__()`](https://python-all.ru/3.4/library/functions.html#__import__), поскольку стандартная функция [`__import__()`](https://python-all.ru/3.4/library/functions.html#__import__) напрямую вызывает эту функцию. Возвращаемое значение – новая ссылка на импортированный модуль или пакет верхнего уровня, или *NULL* с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.4/library/functions.html#__import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist*. Новое в версии 3.3. #### `PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)` *Возвращаемое значение: новая ссылка.* Аналогична [`PyImport_ImportModuleLevelObject()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ImportModuleLevelObject), но name представляет собой строку в кодировке UTF-8 вместо объекта Unicode. Изменено в версии 3.3: Отрицательные значения для *level* больше не принимаются. #### `PyObject* PyImport_Import(PyObject *name)` *Возвращаемое значение: новая ссылка.* Это интерфейс более высокого уровня, который вызывает текущую «функцию перехвата импорта» (с явным *level*, равным 0, что означает абсолютный импорт). Он вызывает функцию [`__import__()`](https://python-all.ru/3.4/library/functions.html#__import__) из `__builtins__` текущих globals. Это означает, что импорт выполняется с использованием тех перехватчиков импорта, которые установлены в текущем окружении. Эта функция всегда использует абсолютные импорты. #### `PyObject* PyImport_ReloadModule(PyObject *m)` *Возвращаемое значение: новая ссылка.* Перезагружает модуль. Возвращает новую ссылку на перезагруженный модуль или *NULL* с установленным исключением в случае неудачи (в этом случае модуль всё ещё существует). #### `PyObject* PyImport_AddModuleObject(PyObject *name)` Возвращает объект модуля, соответствующий имени модуля. Аргумент *name* может иметь вид `package.module`. Сначала проверяется словарь модулей, есть ли там такой модуль; если нет, создаётся новый и вставляется в словарь модулей. Возвращает *NULL* с установленным исключением в случае ошибки. > **Примечание** > > Эта функция не загружает и не импортирует модуль; если модуль ещё не был загружен, будет получен пустой объект модуля. Используйте [`PyImport_ImportModule()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ImportModule) или один из его вариантов для импорта модуля. Структуры пакетов, подразумеваемые составным именем для *name*, не создаются, если их ещё нет. Новое в версии 3.3. #### `PyObject* PyImport_AddModule(const char *name)` *Возвращаемое значение: заимствованная ссылка.* Аналогична [`PyImport_AddModuleObject()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_AddModuleObject), но name представляет собой строку в кодировке UTF-8 вместо объекта Unicode. #### `PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)` *Возвращаемое значение: новая ссылка.* Получая имя модуля (возможно, вида `package.module`) и объект кода, прочитанный из файла байт-кода Python или полученный от встроенной функции [`compile()`](https://python-all.ru/3.4/library/functions.html#compile), загружает модуль. Возвращает новую ссылку на объект модуля или *NULL* с установленным исключением, если произошла ошибка. *name* удаляется из [`sys.modules`](https://python-all.ru/3.4/library/sys.html#sys.modules) в случае ошибки, даже если *name* уже был в [`sys.modules`](https://python-all.ru/3.4/library/sys.html#sys.modules) на момент входа в [`PyImport_ExecCodeModule()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ExecCodeModule). Оставлять не полностью инициализированные модули в [`sys.modules`](https://python-all.ru/3.4/library/sys.html#sys.modules) опасно, так как импорты таких модулей не могут узнать, что объект модуля находится в неизвестном (и, вероятно, повреждённом относительно замысла автора модуля) состоянии. Атрибуты модуля [`__spec__`](https://python-all.ru/3.4/reference/import.html#__spec__) и [`__loader__`](https://python-all.ru/3.4/reference/import.html#__loader__) будут установлены, если ещё не установлены, с соответствующими значениями. Загрузчик спецификации будет установлен в `__loader__` модуля (если он задан) или в экземпляр `SourceFileLoader` в противном случае. Атрибут [`__file__`](https://python-all.ru/3.4/reference/import.html#__file__) модуля будет установлен в `co_filename` объекта кода. Если применимо, [`__cached__`](https://python-all.ru/3.4/reference/import.html#__cached__) также будет установлен. Эта функция перезагрузит модуль, если он уже был импортирован. См. [`PyImport_ReloadModule()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ReloadModule) – это предназначенный способ перезагрузки модуля. Если *name* указывает на составное имя вида `package.module`, любые структуры пакетов, которые ещё не были созданы, по-прежнему не будут созданы. См. также [`PyImport_ExecCodeModuleEx()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ExecCodeModuleEx) и [`PyImport_ExecCodeModuleWithPathnames()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ExecCodeModuleWithPathnames). #### `PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)` *Возвращаемое значение: новая ссылка.* Как и [`PyImport_ExecCodeModule()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ExecCodeModule), но атрибут [`__file__`](https://python-all.ru/3.4/reference/import.html#__file__) объекта модуля устанавливается в *pathname*, если он не равен `NULL`. См. также [`PyImport_ExecCodeModuleWithPathnames()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ExecCodeModuleWithPathnames). #### `PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)` Подобно [`PyImport_ExecCodeModuleEx()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ExecCodeModuleEx), но атрибут [`__cached__`](https://python-all.ru/3.4/reference/import.html#__cached__) объекта модуля устанавливается в *cpathname*, если он не равен `NULL`. Из трёх функций эта предпочтительнее. Новое в версии 3.3. #### `PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)` Подобно [`PyImport_ExecCodeModuleObject()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ExecCodeModuleObject), но *name*, *pathname* и *cpathname* являются строками в кодировке UTF-8. Также предпринимаются попытки определить значение *pathname* из *cpathname*, если первая установлена в `NULL`. Новое в версии 3.2. Изменено в версии 3.3: Использует [`imp.source_from_cache()`](https://python-all.ru/3.4/library/imp.html#imp.source_from_cache) при вычислении пути к исходному файлу, если указан только путь к байт-коду. #### `long PyImport_GetMagicNumber()` Возвращает магическое число для файлов байт-кода Python (также известных как файлы `.pyc` и `.pyo`). Магическое число должно находиться в первых четырёх байтах файла байт-кода в порядке little-endian. Возвращает -1 при ошибке. Изменено в версии 3.3: Возвращаемое значение -1 в случае ошибки. #### `const char * PyImport_GetMagicTag()` Возвращает строку магического тега для имён файлов байт-кода Python в формате [**PEP 3147**](https://python-all.ru/3.4/c-api/import.html). Имейте в виду, что значение `sys.implementation.cache_tag` является авторитетным и должно использоваться вместо этой функции. Новое в версии 3.2. #### `PyObject* PyImport_GetModuleDict()` *Возвращаемое значение: заимствованная ссылка.* Возвращает словарь, используемый для управления модулями (также известный как `sys.modules`). Обратите внимание, что это переменная на интерпретатор. #### `PyObject* PyImport_GetImporter(PyObject *path)` Возвращает объект импортёра для элемента [`sys.path`](https://python-all.ru/3.4/library/sys.html#sys.path)/`pkg.__path__` *path*, возможно получая его из словаря [`sys.path_importer_cache`](https://python-all.ru/3.4/library/sys.html#sys.path_importer_cache). Если он ещё не кэширован, проходит по [`sys.path_hooks`](https://python-all.ru/3.4/library/sys.html#sys.path_hooks), пока не будет найден хук, способный обработать данный элемент пути. Возвращает `None`, если ни один хук не подошёл; это сообщает вызывающему коду, что следует вернуться к встроенному механизму импорта. Кэширует результат в [`sys.path_importer_cache`](https://python-all.ru/3.4/library/sys.html#sys.path_importer_cache). Возвращает новую ссылку на объект импортёра. #### `void _PyImport_Init()` Инициализирует механизм импорта. Только для внутреннего использования. #### `void PyImport_Cleanup()` Очищает таблицу модулей. Только для внутреннего использования. #### `void _PyImport_Fini()` Завершает работу механизма импорта. Только для внутреннего использования. #### `PyObject* _PyImport_FindExtension(char *, char *)` Только для внутреннего использования. #### `PyObject* _PyImport_FixupExtension(char *, char *)` Только для внутреннего использования. #### `int PyImport_ImportFrozenModuleObject(PyObject *name)` Загружает замороженный модуль с именем *name*. Возвращает `1` в случае успеха, `0` если модуль не найден и `-1` с установленным исключением, если инициализация не удалась. Для доступа к импортированному модулю после успешной загрузки используйте [`PyImport_ImportModule()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ImportModule). (Обратите внимание на неточность в названии – эта функция перезагрузила бы модуль, если бы он уже был импортирован.) Новое в версии 3.3. Изменено в версии 3.4: Атрибут `__file__` больше не устанавливается в модуле. #### `int PyImport_ImportFrozenModule(const char *name)` Аналогична [`PyImport_ImportFrozenModuleObject()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ImportFrozenModuleObject), но имя является строкой в кодировке UTF-8 вместо объекта Unicode. **struct `_frozen`** Это определение типа структуры для дескрипторов замороженных модулей, создаваемое утилитой **freeze** (см. `Tools/freeze/` в дистрибутиве исходного кода Python). Её определение находится в `Include/import.h`: ```c struct _frozen { char *name; unsigned char *code; int size; }; ``` **struct [\_frozen](https://python-all.ru/3.4/c-api/import.html#c._frozen)\* `PyImport_FrozenModules`** Этот указатель инициализируется так, чтобы указывать на массив записей `struct _frozen`, заканчивающийся записью, все члены которой равны *NULL* или нулю. Когда замороженный модуль импортируется, он ищется в этой таблице. Сторонний код может использовать это для предоставления динамически созданной коллекции замороженных модулей. #### `int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))` Добавляет один модуль в существующую таблицу встроенных модулей. Это удобная обёртка вокруг [`PyImport_ExtendInittab()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ExtendInittab), возвращающая `-1`, если таблицу не удалось расширить. Новый модуль может быть импортирован под именем *name* и использует функцию *initfunc* в качестве функции инициализации, вызываемой при первой попытке импорта. Это должно быть вызвано до [`Py_Initialize()`](https://python-all.ru/3.4/c-api/init.html#c.Py_Initialize). **struct `_inittab`** Структура, описывающая одну запись в списке встроенных модулей. Каждая из этих структур задаёт имя и функцию инициализации для модуля, встроенного в интерпретатор. Имя является строкой в кодировке ASCII. Программы, встраивающие Python, могут использовать массив таких структур совместно с [`PyImport_ExtendInittab()`](https://python-all.ru/3.4/c-api/import.html#c.PyImport_ExtendInittab) для предоставления дополнительных встроенных модулей. Структура определена в `Include/import.h` как: ```c struct _inittab { char *name; /* Строка в кодировке ASCII */ PyObject* (*initfunc)(void); }; ``` #### `int PyImport_ExtendInittab(struct _inittab *newtab)` Добавляет набор модулей в таблицу встроенных модулей. Массив *newtab* должен заканчиваться сторожевой записью, содержащей *NULL* в поле `name`; отсутствие сторожевого значения может привести к ошибке памяти. Возвращает `0` в случае успеха или `-1`, если недостаточно памяти для расширения внутренней таблицы. В случае неудачи модули не добавляются во внутреннюю таблицу. Этот вызов должен быть выполнен до [`Py_Initialize()`](https://python-all.ru/3.4/c-api/init.html#c.Py_Initialize).