runpy – Поиск и выполнение модулей Python¶runpy – Locating and executing Python modules

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