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