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__ внутри этого пакета и возвращается результирующий словарь глобальных параметров модуля.

Необязательный аргумент dictionary 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__ являются set as normal на основе спецификации модуля.

Если указан аргумент alter_sys, значение которого равно True, то sys.argv[0] обновляется значением __file__, а sys.modules[__name__] обновляется временным объектом module для выполняемого модуля. Как 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)¶

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

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

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

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

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

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

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