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

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

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

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

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

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

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

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

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