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 можно использовать для предварительного заполнения словаря глобальных переменных модуля перед выполнением кода. init_globals не будет изменён. Если какие-либо из специальных глобальных переменных, перечисленных ниже, определены в init_globals, эти определения переопределяются с помощью run_module().

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

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

__spec__ будет установлен соответствующим образом для фактически импортированного модуля (то есть __spec__.name всегда будет mod_name или mod_name + '.__main__', но никогда run_name).

__file__, __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.

Изменено в версии 3.12: Установка __cached__, __loader__ и __package__ устарела. Альтернативы см. в ModuleSpec.

Изменено в версии 3.15: __cached__ больше не устанавливается.

runpy.run_path(path_name, init_globals=None, run_name=None)¶

Выполняет код по указанному пути в файловой системе и возвращает словарь globals результирующего модуля. Как и имя скрипта, переданное в командной строке CPython, path_name может ссылаться на исходный файл Python, скомпилированный байт-код или допустимую запись sys.path, содержащую модуль __main__ (например, zip-файл, содержащий файл __main__.py верхнего уровня).

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

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

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

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

Если path_name напрямую ссылается на файл скрипта (как исходный код или предварительно скомпилированный байт-код), то __file__ будет установлено в path_name, а __spec__, __loader__ и __package__ будут установлены в None.

Если path_name является ссылкой на допустимую запись sys.path, то __spec__ будет установлено соответствующим образом для импортированного модуля __main__ (то есть __spec__.name всегда будет __main__). __file__, __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, а не выполняется напрямую.

Изменено в версии 3.12: Установка __cached__, __loader__ и __package__ устарела.

Изменено в версии 3.15: __cached__ больше не устанавливается.