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