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)¶

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

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

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

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

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

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

__file__, __cached__, __loader__ и __package__ являются set as normal на основе спецификации модуля.

Если аргумент 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(path_name, init_globals=None, run_name=None)¶

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

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

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

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

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

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

Если указанный путь является ссылкой на действительный элемент sys.path, то __spec__ будет установлен соответствующим образом для импортированного модуля __main__ (то есть __spec__.name всегда будет __main__). __file__, __cached__, __loader__ и __package__ будут set as normal в зависимости от спецификации модуля.

В модуль 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, а не выполняется напрямую.