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.

Изменено в версии 3.12: Установка __cached__, __loader__, и __package__ устарела. См. ModuleSpec для альтернатив.

runpy.run_path(path_name, 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] обновляется значением path_name, а 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__ устарела.