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__ (например, архив zipfile, содержащий файл __main__.py верхнего уровня).

Для простого скрипта указанный код просто выполняется в новом пространстве имён модуля. Для допустимого элемента sys.path (обычно zipfile или каталог) элемент сначала добавляется в начало 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, а не выполняется непосредственно.