29.5. runpy – Поиск и выполнение модулей Python¶runpy – Locating and executing Python modules

Модуль runpy используется для поиска и запуска модулей Python без их предварительного импорта. Основное его применение – реализация флага командной строки -m, который позволяет искать скрипты по пространству имён модулей Python, а не по файловой системе.

При запуске в качестве скрипта модуль работает следующим образом:

del sys.argv[0]  # Удалить модуль runpy из аргументов
run_module(sys.argv[0], run_name="__main__", alter_sys=True)

Модуль runpy предоставляет одну функцию:

runpy.run_module(mod_name[, init_globals][, run_name][, alter_sys])¶

Выполняет код указанного модуля и возвращает результирующий словарь глобальных переменных модуля. Код модуля сначала находится с помощью стандартного механизма импорта (подробности см. в PEP 302), а затем выполняется в новом пространстве имён модуля.

Если указанное имя модуля ссылается на пакет, а не на обычный модуль, то этот пакет импортируется, а затем выполняется подмодуль __main__ внутри этого пакета, и возвращается результирующий словарь глобальных переменных модуля.

Необязательный аргумент-словарь init_globals может использоваться для предварительного заполнения словаря глобальных переменных перед выполнением кода. Переданный словарь не будет изменён. Если в переданном словаре определены какие-либо из перечисленных ниже специальных глобальных переменных, эти определения переопределяются функцией run_module.

Специальные глобальные переменные __name__, __file__, __loader__, __builtins__ и __package__ устанавливаются в словаре глобальных переменных перед выполнением кода модуля.

__name__ устанавливается в run_name, если передан этот необязательный аргумент, в mod_name + '.__main__', если именованный модуль является пакетом, и в аргумент mod_name в противном случае.

__loader__ устанавливается в загрузчик модуля PEP 302, используемый для получения кода модуля (этот загрузчик может быть обёрткой вокруг стандартного механизма импорта).

__file__ устанавливается в имя, предоставленное загрузчиком модуля. Если загрузчик не предоставляет информацию об имени файла, эта переменная устанавливается в None.

__builtins__ автоматически инициализируется ссылкой на пространство имён верхнего уровня модуля builtins.

__package__ устанавливается в mod_name, если именованный модуль является пакетом, и в mod_name.rpartition('.')[0] в противном случае.

Если аргумент alter_sys передан и равен True, то sys.argv[0] обновляется значением __file__, а sys.modules[__name__] обновляется временным объектом модуля для выполняемого модуля. Оба значения sys.argv[0] и sys.modules[__name__] восстанавливаются до исходных перед возвратом из функции.

Обратите внимание, что такие манипуляции с sys не являются потокобезопасными. Другие потоки могут увидеть частично инициализированный модуль, а также изменённый список аргументов. Рекомендуется не трогать модуль sys при вызове этой функции из многопоточного кода.

Изменено в версии 3.1: Добавлена возможность выполнять пакеты путём поиска подмодуля __main__.