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__ модуль (например, zipfile, содержащий файл верхнего уровня __main__.py).

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