runpy
— Нахождение и выполнение модулей Python¶
Источник: Lib/runpy.py
Модуль runpy
используется для поиска и запуска модулей Python без их импорта. В основном он используется для реализации переключателя командной строки -m
, который позволяет находить скрипты в пространстве имен модулей Python, а не в файловой системе.
Обратите внимание, что это не модуль-песочница - весь код выполняется в текущем процессе, и любые побочные эффекты (например, кэшированный импорт других модулей) останутся на месте после возврата функций.
Кроме того, не гарантируется корректная работа любых функций и классов, определенных выполненным кодом, после возврата функции runpy
. Если это ограничение неприемлемо для конкретного случая использования, то importlib
, вероятно, будет более подходящим выбором, чем этот модуль.
Модуль runpy
выполняет две функции:
- runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)¶
Выполняет код указанного модуля и возвращает полученный словарь globals модуля. Код модуля сначала находится с помощью стандартного механизма импорта (подробности см. в PEP 302), а затем выполняется в свежем пространстве имен модуля.
Аргумент mod_name должен быть абсолютным именем модуля. Если имя модуля ссылается на пакет, а не на обычный модуль, то этот пакет импортируется, затем выполняется подмодуль
__main__
внутри этого пакета и возвращается результирующий словарь глобалов модуля.Необязательный аргумент словаря init_globals может быть использован для предварительного заполнения словаря globals модуля перед выполнением кода. Параметр init_globals не будет изменен. Если в init_globals определены какие-либо из специальных глобальных переменных, перечисленных ниже, то эти определения переопределяются значением
run_module()
.Специальные глобальные переменные
__name__
,__spec__
,__file__
,__cached__
,__loader__
и__package__
устанавливаются в словаре globals перед выполнением кода модуля. (Обратите внимание, что это минимальный набор переменных - другие переменные могут быть установлены неявно, как деталь реализации интерпретатора).__name__
устанавливается в run_name, если этот дополнительный аргумент не являетсяNone
, вmod_name + '.__main__'
, если именованный модуль является пакетом, и в mod_name в противном случае.__spec__
будет установлен соответствующим образом для фактически импортированного модуля (то есть__spec__.name
всегда будет mod_name илиmod_name + '.__main__'
, никогда run_name).__file__
,__cached__
,__loader__
и__package__
- set as normal в соответствии со спецификацией модуля.Если аргумент alter_sys имеет значение
True
, тоsys.argv[0]
обновляется значением__file__
, аsys.modules[__name__]
обновляется временным объектом модуля для выполняемого модуля. Перед возвратом функции оба значенияsys.argv[0]
иsys.modules[__name__]
восстанавливаются до исходных.Обратите внимание, что такая манипуляция с
sys
не является потокобезопасной. Другие потоки могут увидеть частично инициализированный модуль, а также измененный список аргументов. Рекомендуется не трогать модульsys
при вызове этой функции из потокового кода.См.также
Опция
-m
предлагает эквивалентную функциональность из командной строки.Изменено в версии 3.1: Добавлена возможность выполнения пакетов с помощью поиска субмодуля
__main__
.Изменено в версии 3.2: Добавлена глобальная переменная
__cached__
(см. PEP 3147).Изменено в версии 3.4: Обновлено для использования возможностей спецификации модулей, добавленных PEP 451. Это позволяет правильно устанавливать
__cached__
для модулей, запускаемых таким образом, а также гарантирует, что реальное имя модуля всегда будет доступно как__spec__.name
.Изменено в версии 3.12: Значения
__cached__
,__loader__
и__package__
устарели. Альтернативные варианты см. вModuleSpec
.
- runpy.run_path(path_name, init_globals=None, run_name=None)¶
Выполняет код в указанном месте файловой системы и возвращает словарь globals результирующего модуля. Как и в случае с именем скрипта в командной строке CPython, file_path может ссылаться на исходный файл Python, скомпилированный файл байткода или действительную запись
sys.path
, содержащую модуль__main__
(например, zip-файл, содержащий файл верхнего уровня__main__.py
).Для простого скрипта указанный код просто выполняется в свежем пространстве имен модуля. Для действительной записи
sys.path
(обычно это zip-файл или каталог) сначала добавляется запись в началоsys.path
. Затем функция ищет и выполняет модуль__main__
, используя обновленный путь. Обратите внимание, что нет никакой специальной защиты от вызова существующей записи__main__
, расположенной в другом местеsys.path
, если в указанном месте нет такого модуля.Необязательный аргумент словаря init_globals может быть использован для предварительного заполнения словаря globals модуля перед выполнением кода. Параметр init_globals не будет изменен. Если в init_globals определены какие-либо из специальных глобальных переменных, перечисленных ниже, то эти определения переопределяются значением
run_path()
.Специальные глобальные переменные
__name__
,__spec__
,__file__
,__cached__
,__loader__
и__package__
устанавливаются в словаре globals перед выполнением кода модуля. (Обратите внимание, что это минимальный набор переменных - другие переменные могут быть установлены неявно, как деталь реализации интерпретатора).__name__
устанавливается в run_name, если этот дополнительный аргумент неNone
, и в'<run_path>'
в противном случае.Если file_path напрямую ссылается на файл сценария (будь то исходный текст или прекомпилированный байт-код), то
__file__
будет установлен в file_path, а__spec__
,__cached__
,__loader__
и__package__
будут установлены вNone
.Если file_path является ссылкой на действительную запись
sys.path
, то__spec__
будет установлен соответствующим образом для импортированного модуля__main__
(то есть__spec__.name
всегда будет__main__
).__file__
,__cached__
,__loader__
и__package__
будут set as normal в зависимости от спецификации модуля.В модуль
sys
также вносится ряд изменений. Во-первых,sys.path
может быть изменен, как описано выше.sys.argv[0]
обновляется значением file_path, аsys.modules[__name__]
обновляется временным объектом модуля для выполняемого модуля. Все изменения элементов вsys
отменяются перед возвратом функции.Обратите внимание, что, в отличие от
run_module()
, изменения, вносимые вsys
, не являются необязательными в этой функции, поскольку эти изменения необходимы для выполнения записейsys.path
. Поскольку ограничения на потокобезопасность все еще действуют, использование этой функции в потоковом коде должно быть либо сериализовано с блокировкой импорта, либо делегировано отдельному процессу.См.также
Параметры интерфейса для эквивалентной функциональности в командной строке (
python path/to/script
).Added in version 3.2.
Изменено в версии 3.4: Обновлено для использования возможностей спецификации модулей, добавленных PEP 451. Это позволяет правильно установить
__cached__
в случае, когда__main__
импортируется из действительной записиsys.path
, а не выполняется напрямую.Изменено в версии 3.12: Значения
__cached__
,__loader__
и__package__
устарели.
См.также
- PEP 338 – Выполнение модулей как скриптов
PEP написан и реализован Ником Когланом.
- PEP 366 – Явный относительный импорт главного модуля
PEP написан и реализован Ником Когланом.
- PEP 451 – Тип ModuleSpec для системы импорта
PEP написан и реализован Эриком Сноу
Командная строка и окружение - Детали командной строки CPython
Функция importlib.import_module()