runpy.md

1> **Источник:** https://python-all.ru/3.15/library/runpy.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `runpy` – Поиск и выполнение модулей Python89**Исходный код:** [Lib/runpy.py](https://python-all.ru/src/3.15/Lib/runpy.py)1011---1213Модуль `runpy` используется для поиска и запуска модулей Python без их предварительного импорта. Основное его применение – реализация ключа командной строки [`-m`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-m), который позволяет находить скрипты через пространство имён модулей Python, а не через файловую систему.1415Обратите внимание: это *не* изолированный модуль – весь код выполняется в текущем процессе, и все побочные эффекты (например, кешированные импорты других модулей) сохраняются после возврата из функций.1617Кроме того, любые функции и классы, определённые выполняемым кодом, не гарантируют корректной работы после возврата из функции `runpy`. Если такое ограничение неприемлемо для конкретного случая, [`importlib`](https://python-all.ru/3.15/library/importlib.html#module-importlib), скорее всего, будет более подходящим выбором, чем этот модуль.1819Модуль `runpy` предоставляет две функции:2021#### `runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)`2223Выполняет код указанного модуля и возвращает словарь глобальных переменных этого модуля. Код модуля сначала находится с помощью стандартного механизма импорта (подробнее см. [**PEP 302**](https://python-all.ru/3.15/library/runpy.html)), а затем выполняется в новом пространстве имён модуля.2425Аргумент *mod\_name* должен быть абсолютным именем модуля. Если имя модуля указывает на пакет, а не на обычный модуль, то этот пакет импортируется, а затем выполняется подмодуль [`__main__`](https://python-all.ru/3.15/library/__main__.html#module-__main__) внутри этого пакета, и возвращается словарь глобальных переменных полученного модуля.2627Необязательный аргумент-словарь *init\_globals* можно использовать для предварительного заполнения словаря глобальных переменных модуля перед выполнением кода. *init\_globals* не будет изменён. Если какие-либо из специальных глобальных переменных, перечисленных ниже, определены в *init\_globals*, эти определения переопределяются с помощью `run_module()`.2829Специальные глобальные переменные `__name__`, `__spec__`, `__file__`, `__loader__` и `__package__` устанавливаются в словаре globals до выполнения кода модуля. (Обратите внимание, что это минимальный набор переменных - другие переменные могут быть установлены неявно как деталь реализации интерпретатора.)3031`__name__` устанавливается в *run\_name*, если этот необязательный аргумент не равен [`None`](https://python-all.ru/3.15/library/constants.html#None), в `mod_name + '.__main__'`, если указанный модуль является пакетом, и в аргумент *mod\_name* в противном случае.3233`__spec__` будет установлен соответствующим образом для *фактически* импортированного модуля (то есть `__spec__.name` всегда будет *mod\_name* или `mod_name + '.__main__'`, но никогда *run\_name*).3435`__file__`, `__loader__` и `__package__` [устанавливаются как обычно](https://python-all.ru/3.15/reference/datamodel.html#import-mod-attrs) на основе спецификации модуля.3637Если аргумент *alter\_sys* передан и его значение равно [`True`](https://python-all.ru/3.15/library/constants.html#True), то `sys.argv[0]` обновляется значением `__file__`, а `sys.modules[__name__]` обновляется временным объектом модуля для выполняемого модуля. Оба `sys.argv[0]` и `sys.modules[__name__]` восстанавливаются до исходных значений перед возвратом из функции.3839Обратите внимание: такие манипуляции с [`sys`](https://python-all.ru/3.15/library/sys.html#module-sys) не являются потокобезопасными. Другие потоки могут увидеть частично инициализированный модуль, а также изменённый список аргументов. Рекомендуется оставить модуль `sys` в покое при вызове этой функции из многопоточного кода.4041> **См. также**42>43> Параметр [`-m`](https://python-all.ru/3.15/using/cmdline.html#cmdoption-m) предоставляет эквивалентную функциональность из командной строки.4445Изменено в версии 3.1: Добавлена возможность выполнять пакеты путём поиска подмодуля [`__main__`](https://python-all.ru/3.15/library/__main__.html#module-__main__).4647Изменено в версии 3.2: Добавлена глобальная переменная `__cached__` (см. [**PEP 3147**](https://python-all.ru/3.15/library/runpy.html)).4849Изменено в версии 3.4: Обновлено для использования возможностей спецификации модуля, добавленных [**PEP 451**](https://python-all.ru/3.15/library/runpy.html). Это позволяет правильно устанавливать `__cached__` для модулей, запускаемых таким образом, а также гарантирует, что настоящее имя модуля всегда доступно как `__spec__.name`.5051Изменено в версии 3.12: Установка `__cached__`, `__loader__` и `__package__` устарела. Альтернативы см. в [`ModuleSpec`](https://python-all.ru/3.15/library/importlib.html#importlib.machinery.ModuleSpec).5253Изменено в версии 3.15: `__cached__` больше не устанавливается.5455#### `runpy.run_path(path_name, init_globals=None, run_name=None)`5657Выполняет код по указанному пути в файловой системе и возвращает словарь глобальных переменных полученного модуля. Как и имя скрипта, переданное командной строке CPython, *file\_path* может ссылаться на исходный файл Python, скомпилированный байт-код или корректную запись [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path), содержащую модуль [`__main__`](https://python-all.ru/3.15/library/__main__.html#module-__main__) (например, zip-файл с файлом `__main__.py` верхнего уровня).5859Для простого скрипта указанный код просто выполняется в новом пространстве имён модуля. Для корректной записи [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path) (обычно zip-файла или каталога) запись сначала добавляется в начало `sys.path`. Затем функция ищет и выполняет модуль [`__main__`](https://python-all.ru/3.15/library/__main__.html#module-__main__), используя обновлённый путь. Обратите внимание: нет специальной защиты от вызова существующей записи `__main__`, расположенной в другом месте `sys.path`, если в указанном месте такого модуля нет.6061Необязательный аргумент-словарь *init\_globals* можно использовать для предварительного заполнения словаря глобальных переменных модуля перед выполнением кода. *init\_globals* не будет изменён. Если какие-либо из специальных глобальных переменных, перечисленных ниже, определены в *init\_globals*, эти определения переопределяются с помощью `run_path()`.6263Специальные глобальные переменные `__name__`, `__spec__`, `__file__`, `__loader__` и `__package__` устанавливаются в словаре globals до выполнения кода модуля. (Обратите внимание, что это минимальный набор переменных - другие переменные могут быть установлены неявно как деталь реализации интерпретатора.)6465`__name__` устанавливается в *run\_name*, если этот необязательный аргумент не равен [`None`](https://python-all.ru/3.15/library/constants.html#None), и в `'<run_path>'` в противном случае.6667Если *file\_path* напрямую ссылается на файл сценария (будь то в виде исходного кода или предварительно скомпилированного байт-кода), то `__file__` будет установлено в *file\_path*, а `__spec__`, `__loader__` и `__package__` будут установлены в [`None`](https://python-all.ru/3.15/library/constants.html#None).6869Если *file\_path* является ссылкой на допустимую запись [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path), то `__spec__` будет соответствующим образом установлен для импортированного модуля [`__main__`](https://python-all.ru/3.15/library/__main__.html#module-__main__) (то есть `__spec__.name` всегда будет `__main__`). `__file__`, `__loader__` и `__package__` будут [установлены обычным образом](https://python-all.ru/3.15/reference/datamodel.html#import-mod-attrs) на основе спецификации модуля.7071Также в модуль [`sys`](https://python-all.ru/3.15/library/sys.html#module-sys) вносится ряд изменений. Во-первых, [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path) может быть изменён, как описано выше. `sys.argv[0]` обновляется значением *file\_path*, а `sys.modules[__name__]` обновляется временным объектом модуля для выполняемого модуля. Все изменения элементов в `sys` отменяются перед возвратом функции.7273Обратите внимание: в отличие от [`run_module()`](https://python-all.ru/3.15/library/runpy.html#runpy.run_module), изменения в [`sys`](https://python-all.ru/3.15/library/sys.html#module-sys) в этой функции не являются необязательными, поскольку они необходимы для обеспечения выполнения записей [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path). Поскольку ограничения потокобезопасности по-прежнему действуют, использование этой функции в многопоточном коде должно быть либо сериализовано с помощью блокировки импорта, либо делегировано отдельному процессу.7475> **См. также**76>77> [Параметры интерфейса](https://python-all.ru/3.15/using/cmdline.html#using-on-interface-options) для эквивалентной функциональности в командной строке (`python path/to/script`).7879Добавлено в версии 3.2.8081Изменено в версии 3.4: Обновлено для использования возможностей спецификации модулей, добавленных в [**PEP 451**](https://python-all.ru/3.15/library/runpy.html). Это позволяет корректно установить `__cached__` в случае, когда `__main__` импортируется из допустимой записи [`sys.path`](https://python-all.ru/3.15/library/sys.html#sys.path), а не выполняется напрямую.8283Изменено в версии 3.12: Установка `__cached__`, `__loader__` и `__package__` устарела.8485Изменено в версии 3.15: `__cached__` больше не устанавливается.8687> **См. также**88>89> **[**PEP 338**](https://python-all.ru/3.15/library/runpy.html) – Выполнение модулей как сценариев**90>91> PEP написан и реализован Ником Когланом.92>93> **[**PEP 366**](https://python-all.ru/3.15/library/runpy.html) – Явные относительные импорты главного модуля**94>95> PEP написан и реализован Ником Когланом.96>97> **[**PEP 451**](https://python-all.ru/3.15/library/runpy.html) – Тип ModuleSpec для системы импорта**98>99> PEP написан и реализован Эриком Сноу.100>101> [Командная строка и окружение](https://python-all.ru/3.15/using/cmdline.html#using-on-general) – подробности о командной строке CPython102>103> Функция [`importlib.import_module()`](https://python-all.ru/3.15/library/importlib.html#importlib.import_module)104