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 можно использовать для предварительного заполнения словаря глобальных переменных модуля перед выполнением кода. init_globals не будет изменён. Если в 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.

Изменено в версии 3.12: Установка __cached__, __loader__ и __package__ объявлена устаревшей. Альтернативы см. в разделе ModuleSpec.

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

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

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

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

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

__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__ задаются обычным образом на основе спецификации модуля.

В модуль 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, а не выполняется напрямую.

Изменено в версии 3.12: Установка __cached__, __loader__ и __package__ объявлена устаревшей.