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