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, то значение __file__ присваивается sys.argv[0], а 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.

Изменено в версии 3.12: Назначение __cached__, __loader__ и __package__ объявлено устаревшим. Альтернативные варианты см. в ModuleSpec.

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 может быть изменён, как описано выше. Значение path_name присваивается sys.argv[0], а sys.modules[__name__] присваивается временный объект модуля для выполняемого модуля. Все изменения элементов в sys отменяются до возврата функции.

Обратите внимание: в отличие от run_module(), изменения sys в этой функции необязательными не являются, поскольку эти настройки необходимы для выполнения элементов sys.path. Поскольку ограничения потокобезопасности сохраняются, при использовании этой функции в многопоточном коде её следует либо сериализовать с помощью блокировки импорта, либо выполнять в отдельном процессе.

См. также

Параметры интерфейса — аналогичные возможности в командной строке (python path/to/script).

Добавлено в версии 3.2.

Изменено в версии 3.4: Обновлено с учётом поддержки спецификации модулей, добавленной в PEP 451. Благодаря этому __cached__ правильно устанавливается, когда __main__ импортируется из действительного элемента sys.path, а не выполняется напрямую.

Изменено в версии 3.12: Назначение __cached__, __loader__ и __package__ объявлено устаревшим.