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