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)

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

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

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

Специальные глобальные переменные __name__, __spec__, __file__, __cached__, __loader__ и __package__ устанавливаются в словаре глобальных переменных перед выполнением кода модуля (Обратите внимание, что это минимальный набор переменных — другие переменные могут быть установлены неявно как деталь реализации интерпретатора).

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

__spec__ будет установлено соответствующим образом для фактически импортированного модуля (то есть, __spec__.name всегда будет mod_name или mod_name + '.__main__, а никогда run_name).

__file__, __cached__, __loader__ и __package__ устанавливаются как обычно, на основе спецификации модуля.

Если передан аргумент 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.

runpy.run_path(file_path, init_globals=None, run_name=None)

Выполняет код по указанному пути в файловой системе и возвращает словарь глобальных переменных получившегося модуля. Как и в случае с именем скрипта, переданным в командную строку CPython, указанный путь может ссылаться на файл исходного кода Python, скомпилированный файл байткода или на запись в sys.path, содержащую модуль __main__ (например, архив zip с файлом верхнего уровня __main__.py).

Для простого скрипта указанный код выполняется в новом пространстве имён модуля. Для записи в sys.path (обычно архив zip или каталог) запись сначала добавляется в начало sys.path. Затем функция ищет и выполняет модуль __main__ с обновлённым путем. Обратите внимание, что нет специальной защиты от вызова существующей записи __main__, расположенной в другом месте в sys.path, если такого модуля нет по указанному пути.

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

Специальные глобальные переменные __name__, __spec__, __file__, __cached__, __loader__ и __package__ устанавливаются в словаре глобальных переменных перед выполнением кода модуля (Обратите внимание, что это минимальный набор переменных — другие переменные могут быть установлены неявно как деталь реализации интерпретатора).

__name__ устанавливается в run_name, если этот необязательный аргумент не равен None, и в '<run_path>' в противном случае.

Если указанный путь непосредственно ссылается на файл скрипта (в виде исходного кода или предварительно скомпилированного байткода), то __file__ устанавливается в переданный путь, а __spec__, __cached__, __loader__ и __package__ устанавливаются в None.

Если указанный путь ссылается на запись в sys.path, то __spec__ устанавливается соответствующим образом для импортированного модуля __main__ (то есть __spec__.name всегда будет __main__). __file__, __cached__, __loader__ и __package__ устанавливаются как обычно, на основе спецификации модуля.

Также вносятся некоторые изменения в модуль sys. Во-первых, sys.path может быть изменён, как описано выше. sys.argv[0] обновляется значением file_path, а sys.modules[__name__] обновляется временным объектом модуля для выполняемого модуля. Все изменения элементов в модуле sys отменяются перед возвратом функции.

Обратите внимание, что в отличие от run_module(), изменения, внесённые в sys, в этой функции не являются необязательными, поскольку эти изменения необходимы для выполнения записей в sys.path. Так как ограничения по потоковой безопасности остаются, использование этой функции в многопоточном коде должно либо быть сериализовано с помощью блокировки импорта, либо быть делегировано отдельному процессу.

См. также

Параметры интерфейса для эквивалентной функциональности в командной строке (python path/to/script).

Добавлена в версии 3.2.

Изменено в версии 3.4: Обновлено для использования функции модульной спецификации, добавленной в PEP 451. Это позволяет установить __cached__ правильно в случае, когда __main__ импортируется из записи в sys.path, а не выполняется непосредственно.