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

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

Изменено в версии 3.12: Присваивание значений __cached__, __loader__ и __package__ объявлено устаревшим. Альтернативы см. в ModuleSpec.

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

Выполняет код по указанному пути в файловой системе и возвращает словарь глобальных переменных получившегося модуля. Как и имя скрипта, переданное в командной строке CPython, file_path может указывать на исходный файл 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__, __cached__, __loader__ и __package__. (Обратите внимание, что это минимальный набор переменных — другие переменные могут устанавливаться неявно в рамках деталей реализации интерпретатора.)

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

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

Если file_path указывает на допустимый элемент 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, а не выполняется напрямую.

Изменено в версии 3.12: Присваивание значений __cached__, __loader__ и __package__ объявлено устаревшим.