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

Исходный код: Lib/runpy.py

Модуль runpy используется для поиска и запуска модулей Python без их предварительного импорта. Основное его применение – реализация ключа командной строки -m, который позволяет находить скрипты через пространство имён модулей Python, а не через файловую систему.

Модуль runpy предоставляет две функции:

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)¶

Выполняет код указанного модуля и возвращает результирующий словарь глобальных переменных модуля. Сначала код модуля находится с помощью стандартного механизма импорта (подробнее см. PEP 302), а затем выполняется в новом пространстве имён модуля.

Если указанное имя модуля относится к пакету, а не к обычному модулю, то этот пакет импортируется, и в нём выполняется подмодуль __main__, после чего возвращается полученный словарь глобальных переменных модуля.

Необязательный аргумент-словарь init_globals можно использовать для предварительного заполнения словаря глобальных переменных модуля до выполнения кода. Переданный словарь не будет изменён. Если какие-либо из специальных глобальных переменных, перечисленных ниже, определены в переданном словаре, эти определения переопределяются вызовом run_module().

Специальные глобальные переменные __name__, __file__, __loader__ и __package__ устанавливаются в словаре глобальных переменных до выполнения кода модуля (обратите внимание, что это минимальный набор переменных – другие переменные могут устанавливаться неявно как деталь реализации интерпретатора).

__name__ устанавливается в run_name, если этот необязательный аргумент не равен None, в mod_name + '.__main__', если указанный модуль является пакетом, и в аргумент mod_name в противном случае.

__file__ устанавливается в имя, предоставленное загрузчиком модулей. Если загрузчик не предоставляет информацию об имени файла, эта переменная устанавливается в None.

__loader__ устанавливается в PEP 302 загрузчик модулей, используемый для получения кода модуля (этот загрузчик может быть обёрткой стандартного механизма импорта).

__package__ устанавливается в mod_name, если именованный модуль является пакетом, и в mod_name.rpartition('.')[0] в противном случае.

Если аргумент alter_sys передан и его значение равно True, то sys.argv[0] обновляется значением __file__, а sys.modules[__name__] обновляется временным объектом модуля для выполняемого модуля. Оба sys.argv[0] и sys.modules[__name__] восстанавливаются до исходных значений перед возвратом из функции.

Обратите внимание: такие манипуляции с sys не являются потокобезопасными. Другие потоки могут увидеть частично инициализированный модуль, а также изменённый список аргументов. Рекомендуется оставить модуль sys в покое при вызове этой функции из многопоточного кода.

См. также

Параметр -m предоставляет эквивалентную функциональность из командной строки.

Изменено в версии 2.7: Добавлена возможность выполнения пакетов через поиск подмодуля __main__.

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__, __file__, __loader__ и __package__ устанавливаются в словаре глобальных переменных до выполнения кода модуля (обратите внимание, что это минимальный набор переменных – другие переменные могут устанавливаться неявно как деталь реализации интерпретатора).

__name__ устанавливается в run_name, если этот необязательный аргумент не равен None, и в '<run_path>' в противном случае.

__file__ устанавливается в имя, предоставленное загрузчиком модулей. Если загрузчик не предоставляет информацию об имени файла, эта переменная устанавливается в None. Для простого скрипта она будет установлена в file_path.

__loader__ устанавливается в PEP 302 загрузчик модулей, используемый для получения кода модуля (этот загрузчик может быть обёрткой стандартного механизма импорта). Для простого скрипта она будет установлена в None.

__package__ устанавливается в __name__.rpartition('.')[0].

В модуль sys также вносится ряд изменений. Во-первых, sys.path может быть изменён, как описано выше. sys.argv[0] обновляется значением file_path, а sys.modules[__name__] обновляется временным объектом модуля для выполняемого модуля. Все изменения элементов в sys отменяются до возврата функции.

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

См. также

Параметры интерфейса для эквивалентной функциональности в командной строке (python path/to/script).

Новое в версии 2.7.