`import.md`

249 строк · 23.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.11/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*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*1415Это обёртка вокруг [`PyImport_Import()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_Import), которая принимает const char\* в качестве аргумента вместо [PyObject](https://python-all.ru/3.11/c-api/structures.html#c.PyObject)\*.1617#### `PyObject *PyImport_ImportModuleNoBlock(const char *name)`1819*Возвращаемое значение: новая ссылка.*2021*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*2223Эта функция – устаревший псевдоним [`PyImport_ImportModule()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ImportModule).2425Изменено в версии 3.3: Ранее эта функция немедленно завершалась ошибкой, если блокировка импорта удерживалась другим потоком. Однако в Python 3.3 схема блокировки была изменена на блокировки на уровне модулей для большинства случаев, поэтому специальное поведение этой функции больше не требуется.2627#### `PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)`2829*Возвращаемое значение: новая ссылка.*3031Импорт модуля. Лучше всего это описывается через встроенную функцию Python [`__import__()`](https://python-all.ru/3.11/library/functions.html#import__).3233Возвращаемое значение – это новая ссылка на импортированный модуль или пакет верхнего уровня, либо `NULL` с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.11/library/functions.html#import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist* .3435Неудачные импорты удаляют неполные объекты модулей, как и [`PyImport_ImportModule()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ImportModule).3637#### `PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)`3839*Возвращаемое значение: новая ссылка.*4041*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable) начиная с версии 3.7.*4243Импорт модуля. Наилучшее описание даётся через встроенную функцию Python [`__import__()`](https://python-all.ru/3.11/library/functions.html#import__), поскольку стандартная функция [`__import__()`](https://python-all.ru/3.11/library/functions.html#import__) вызывает эту функцию напрямую.4445Возвращаемое значение – это новая ссылка на импортированный модуль или пакет верхнего уровня, либо `NULL` с установленным исключением в случае ошибки. Как и для [`__import__()`](https://python-all.ru/3.11/library/functions.html#import__), возвращаемое значение при запросе подмодуля пакета обычно является пакетом верхнего уровня, если только не был передан непустой *fromlist*.4647Новое в версии 3.3.4849#### `PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)`5051*Возвращаемое значение: новая ссылка.*5253*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*5455Аналогично [`PyImport_ImportModuleLevelObject()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ImportModuleLevelObject), но имя представляет собой строку в кодировке UTF-8 вместо объекта Unicode.5657Изменено в версии 3.3: Отрицательные значения для *level* больше не принимаются.5859#### `PyObject *PyImport_Import(PyObject *name)`6061*Возвращаемое значение: новая ссылка.*6263*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*6465Это интерфейс более высокого уровня, который вызывает текущую «функцию перехвата импорта» (с явным *level* равным 0, что означает абсолютный импорт). Он вызывает функцию [`__import__()`](https://python-all.ru/3.11/library/functions.html#import__) из `__builtins__` текущих глобальных переменных. Это означает, что импорт выполняется с использованием тех перехватчиков импорта, которые установлены в текущем окружении.6667Эта функция всегда использует абсолютные импорты.6869#### `PyObject *PyImport_ReloadModule(PyObject *m)`7071*Возвращаемое значение: новая ссылка.*7273*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*7475Перезагружает модуль. Возвращает новую ссылку на перезагруженный модуль или `NULL` с установленным исключением в случае ошибки (в этом случае модуль всё ещё существует).7677#### `PyObject *PyImport_AddModuleObject(PyObject *name)`7879*Возвращаемое значение: заимствованная ссылка.*8081*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable) начиная с версии 3.7.*8283Возвращает объект модуля, соответствующий имени модуля. Аргумент *name* может иметь форму `package.module`. Сначала проверяется словарь modules – если модуль уже есть, он возвращается; если нет, создаётся новый и вставляется в словарь modules. В случае неудачи возвращается `NULL` и устанавливается исключение.8485> **Примечание**86>87> Эта функция не загружает и не импортирует модуль; если модуль ещё не был загружен, возвращается пустой объект модуля. Для импорта модуля используйте [`PyImport_ImportModule()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ImportModule) или один из его вариантов. Структуры пакетов, подразумеваемые точечным именем для *name*, не создаются, если их ещё нет.8889Новое в версии 3.3.9091#### `PyObject *PyImport_AddModule(const char *name)`9293*Возвращаемое значение: заимствованная ссылка.*9495*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*9697Аналогично [`PyImport_AddModuleObject()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_AddModuleObject), но имя передаётся в виде строки в кодировке UTF-8, а не как объект Unicode.9899#### `PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)`100101*Возвращаемое значение: новая ссылка.*102103*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*104105Принимая имя модуля (возможно, вида `package.module`) и объект кода, прочитанный из файла байткода Python или полученный из встроенной функции [`compile()`](https://python-all.ru/3.11/library/functions.html#compile), загружает модуль. Возвращает новую ссылку на объект модуля или `NULL` с установленным исключением, если произошла ошибка. В случае ошибки *name* удаляется из [`sys.modules`](https://python-all.ru/3.11/library/sys.html#sys.modules), даже если *name* уже был в [`sys.modules`](https://python-all.ru/3.11/library/sys.html#sys.modules) на момент входа в [`PyImport_ExecCodeModule()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExecCodeModule). Оставлять не полностью инициализированные модули в [`sys.modules`](https://python-all.ru/3.11/library/sys.html#sys.modules) опасно, так как импорт таких модулей не может узнать, что объект модуля находится в неизвестном (и, вероятно, повреждённом с точки зрения намерений автора модуля) состоянии.106107Атрибуты [`__spec__`](https://python-all.ru/3.11/reference/import.html#spec__) и [`__loader__`](https://python-all.ru/3.11/reference/import.html#loader__) модуля будут установлены, если ещё не установлены, в соответствующие значения. Загрузчик спецификации будет установлен в `__loader__` модуля (если он задан), в противном случае – в экземпляр [`SourceFileLoader`](https://python-all.ru/3.11/library/importlib.html#importlib.machinery.SourceFileLoader).108109Атрибут [`__file__`](https://python-all.ru/3.11/reference/import.html#file__) модуля будет установлен в значение [`co_filename`](https://python-all.ru/3.11/reference/datamodel.html#codeobject.co_filename) объекта кода. Если применимо, будет также установлен атрибут [`__cached__`](https://python-all.ru/3.11/reference/import.html#cached__).110111Эта функция перезагрузит модуль, если он уже был импортирован. См. [`PyImport_ReloadModule()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ReloadModule) для описания правильного способа перезагрузки модуля.112113Если *name* указывает на имя с точками вида `package.module`, любые структуры пакета, которые ещё не были созданы, по-прежнему не будут созданы.114115См. также [`PyImport_ExecCodeModuleEx()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExecCodeModuleEx) и [`PyImport_ExecCodeModuleWithPathnames()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExecCodeModuleWithPathnames).116117#### `PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)`118119*Возвращаемое значение: новая ссылка.*120121*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*122123Как и [`PyImport_ExecCodeModule()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExecCodeModule), но атрибут [`__file__`](https://python-all.ru/3.11/reference/import.html#file__) объекта модуля устанавливается в *pathname*, если он не равен `NULL`.124125См. также [`PyImport_ExecCodeModuleWithPathnames()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExecCodeModuleWithPathnames).126127#### `PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)`128129*Возвращаемое значение: новая ссылка.*130131*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable) начиная с версии 3.7.*132133Как и [`PyImport_ExecCodeModuleEx()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExecCodeModuleEx), но атрибут [`__cached__`](https://python-all.ru/3.11/reference/import.html#cached__) объекта модуля устанавливается в *cpathname*, если он не равен `NULL`. Из трёх функций эта является предпочтительной.134135Новое в версии 3.3.136137#### `PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)`138139*Возвращаемое значение: новая ссылка.*140141*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*142143Как [`PyImport_ExecCodeModuleObject()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExecCodeModuleObject), но *name*, *pathname* и *cpathname* являются строками в кодировке UTF-8. Также предпринимаются попытки выяснить, каким должно быть значение *pathname* из *cpathname*, если первое установлено в `NULL`.144145Новое в версии 3.2.146147Изменено в версии 3.3: Использует [`imp.source_from_cache()`](https://python-all.ru/3.11/library/imp.html#imp.source_from_cache) при вычислении пути к исходному коду, если указан только путь к байткоду.148149#### `long PyImport_GetMagicNumber()`150151*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*152153Возвращает магическое число для файлов байткода Python (также известных как файлы `.pyc`). Магическое число должно присутствовать в первых четырёх байтах файла байткода в порядке little-endian. В случае ошибки возвращает `-1`.154155Изменено в версии 3.3: Возвращает `-1` в случае неудачи.156157#### `const char *PyImport_GetMagicTag()`158159*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*160161Возвращает строку магического тега для имён файлов байткода Python в формате [**PEP 3147**](https://python-all.ru/3.11/c-api/import.html). Имейте в виду, что значение в `sys.implementation.cache_tag` является авторитетным и должно использоваться вместо этой функции.162163Новое в версии 3.2.164165#### `PyObject *PyImport_GetModuleDict()`166167*Возвращаемое значение: заимствованная ссылка.*168169*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*170171Возвращает словарь, используемый для администрирования модулей (также известный как `sys.modules`). Обратите внимание, что это переменная, отдельная для каждого интерпретатора.172173#### `PyObject *PyImport_GetModule(PyObject *name)`174175*Возвращаемое значение: новая ссылка.*176177*Часть [стабильного ABI](https://python-all.ru/3.11/c-api/stable.html#stable) начиная с версии 3.8.*178179Возвращает уже импортированный модуль с заданным именем. Если модуль ещё не был импортирован, возвращает `NULL`, но не устанавливает ошибку. Возвращает `NULL` и устанавливает ошибку, если поиск не удался.180181Добавлено в версии 3.7.182183#### `PyObject *PyImport_GetImporter(PyObject *path)`184185*Возвращаемое значение: новая ссылка.*186187*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*188189Возвращает объект поиска для элемента [`sys.path`](https://python-all.ru/3.11/library/sys.html#sys.path)/`pkg.__path__` *path*, возможно, извлекая его из словаря [`sys.path_importer_cache`](https://python-all.ru/3.11/library/sys.html#sys.path_importer_cache). Если он ещё не кэширован, обходит [`sys.path_hooks`](https://python-all.ru/3.11/library/sys.html#sys.path_hooks), пока не будет найден хук, способный обработать элемент пути. Возвращает `None`, если ни один хук не подошёл; это сообщает вызывающей стороне, что [поисковик на основе пути](https://python-all.ru/3.11/glossary.html#term-path-based-finder) не смог найти поисковик для этого элемента пути. Кэширует результат в [`sys.path_importer_cache`](https://python-all.ru/3.11/library/sys.html#sys.path_importer_cache). Возвращает новую ссылку на объект поисковика.190191#### `int PyImport_ImportFrozenModuleObject(PyObject *name)`192193*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable) начиная с версии 3.7.*194195Загружает замороженный модуль с именем *name*. Возвращает `1` при успехе, `0`, если модуль не найден, и `-1` с установленным исключением, если инициализация не удалась. Чтобы получить доступ к импортированному модулю после успешной загрузки, используйте [`PyImport_ImportModule()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ImportModule). (Обратите внимание на неточность названия – эта функция перезагрузила бы модуль, если он уже был импортирован.)196197Новое в версии 3.3.198199Изменено в версии 3.4: Атрибут `__file__` больше не устанавливается в модуле.200201#### `int PyImport_ImportFrozenModule(const char *name)`202203*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*204205Аналогично [`PyImport_ImportFrozenModuleObject()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ImportFrozenModuleObject), но имя представляет собой строку в кодировке UTF-8 вместо объекта Unicode.206207#### `struct _frozen`208209Это определение типа структуры для дескрипторов замороженных модулей, как сгенерировано утилитой **freeze** (см. `Tools/freeze/` в дистрибутиве исходного кода Python). Её определение находится в `Include/import.h`:210211```c212struct _frozen {213    const char *name;214    const unsigned char *code;215    int size;216    bool is_package;217};218```219220Изменено в версии 3.11: Новое поле `is_package` указывает, является ли модуль пакетом или нет. Это заменяет установку поля `size` в отрицательное значение.221222#### `const struct _frozen *PyImport_FrozenModules`223224Этот указатель инициализируется так, чтобы указывать на массив записей [`_frozen`](https://python-all.ru/3.11/c-api/import.html#c._frozen), завершающийся записью, все члены которой равны `NULL` или нулю. Когда замороженный модуль импортируется, он ищется в этой таблице. Сторонний код может этим воспользоваться, чтобы предоставить динамически создаваемую коллекцию замороженных модулей.225226#### `int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))`227228*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*229230Добавляет один модуль в существующую таблицу встроенных модулей. Это удобная обёртка вокруг [`PyImport_ExtendInittab()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExtendInittab), возвращающая `-1`, если таблицу не удалось расширить. Новый модуль можно импортировать по имени *name*, и он использует функцию *initfunc* в качестве функции инициализации, вызываемой при первой попытке импорта. Это должно вызываться до [`Py_Initialize()`](https://python-all.ru/3.11/c-api/init.html#c.Py_Initialize).231232#### `struct _inittab`233234Структура, описывающая одну запись в списке встроенных модулей. Программы, встраивающие Python, могут использовать массив таких структур в сочетании с [`PyImport_ExtendInittab()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExtendInittab) для предоставления дополнительных встроенных модулей. Структура состоит из двух членов:235236#### `const char *name`237238Имя модуля в виде строки в кодировке ASCII.239240#### `PyObject *(*initfunc)(void)`241242Функция инициализации для модуля, встроенного в интерпретатор.243244#### `int PyImport_ExtendInittab(struct _inittab *newtab)`245246Добавляет набор модулей в таблицу встроенных модулей. Массив *newtab* должен заканчиваться сторожевой записью, которая содержит `NULL` для поля [`name`](https://python-all.ru/3.11/c-api/import.html#c._inittab.name); отсутствие сторожевого значения может привести к ошибке памяти. Возвращает `0` при успехе или `-1`, если недостаточно памяти для расширения внутренней таблицы. В случае неудачи ни один модуль не добавляется во внутреннюю таблицу. Это должно вызываться до [`Py_Initialize()`](https://python-all.ru/3.11/c-api/init.html#c.Py_Initialize).247248Если Python инициализируется несколько раз, [`PyImport_AppendInittab()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_AppendInittab) или [`PyImport_ExtendInittab()`](https://python-all.ru/3.11/c-api/import.html#c.PyImport_ExtendInittab) должны вызываться перед каждой инициализацией Python.249