runpy — Python 모듈 찾기 및 실행

runpy — Python 모듈 찾기 및 실행

runpy 모듈은 Python 모듈을 먼저 가져오지 않고 찾아서 실행하는 데 사용됩니다. 주요 용도는 -m 명령줄 스위치를 구현하는 것입니다. 이 스위치는 스크립트를 파일 시스템이 아니라 Python 모듈 네임스페이스를 사용하여 찾을 수 있게 합니다.

출처: Python documentation

본문

이것은 샌드박스 모듈이 아닙니다 — 모든 코드는 현재 프로세스에서 실행되며, 함수가 반환된 후에도 (다른 모듈의 캐시된 import와 같은) 부작용은 그대로 남아 있습니다.

또한 실행된 코드가 정의한 함수와 클래스는 runpy 함수가 반환된 후 올바르게 작동한다는 보장이 없습니다. 주어진 사용 사례에 대해 그 제한이 허용되지 않으면 이 모듈보다 importlib이 더 적합한 선택일 수 있습니다.

runpy 모듈은 두 가지 함수를 제공합니다.

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)

지정된 모듈의 코드를 실행하고 결과 모듈의 globals 사전을 반환합니다. 모듈의 코드는 먼저 표준 import 메커니즘을 사용하여 찾은 다음(PEP 302 참고) 새 모듈 네임스페이스에서 실행됩니다.

mod_name 인자는 절대 모듈 이름이어야 합니다. 모듈 이름이 일반 모듈이 아니라 패키지를 가리키면 해당 패키지가 import되고 그 패키지 안의 __main__ 하위 모듈이 실행되며 결과 모듈 globals 사전이 반환됩니다.

선택적 init_globals 사전 인자는 코드가 실행되기 전에 모듈의 globals 사전을 미리 채우는 데 사용할 수 있습니다. init_globals는 수정되지 않습니다. 아래의 특수 전역 변수 중 하나라도 init_globals에 정의되어 있으면 그 정의는 run_module()에 의해 재정의됩니다.

특수 전역 변수 __name__, __spec__, __file__, __cached__, __loader__, __package__는 모듈 코드가 실행되기 전에 globals 사전에 설정됩니다.

  • __name__은 이 선택적 인자가 None이 아니면 run_name으로, 명명된 모듈이 패키지이면 mod_name+'.__main__'으로, 그렇지 않으면 mod_name 인자로 설정됩니다.
  • __spec__은 실제로 import된 모듈에 적절하게 설정됩니다(즉, __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 모듈을 건드리지 않는 것이 좋습니다.

See also

명령줄에서 동등한 기능을 제공하는 -m 옵션.

versionchanged: 3.1에서 __main__ 하위 모듈을 찾아 패키지를 실행하는 기능이 추가되었습니다.

versionchanged: 3.2에서 __cached__ 전역 변수가 추가되었습니다(PEP 3147 참고).

versionchanged: 3.4에서 PEP 451이 추가한 모듈 스펙 기능을 활용하도록 업데이트되었습니다. 이렇게 하면 이 방식으로 실행되는 모듈에 대해 __cached__가 올바르게 설정되고 실제 모듈 이름이 항상 __spec__.name으로 접근 가능합니다.

versionchanged: 3.12에서 __cached__, __loader__, __package__ 설정이 폐기되었습니다. 대안은 ModuleSpec을 참고하세요.

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

명명된 파일 시스템 위치에서 코드를 실행하고 결과 모듈의 globals 사전을 반환합니다. CPython 명령줄에 제공된 스크립트 이름과 마찬가지로 file_path는 Python 소스 파일, 컴파일된 바이트코드 파일, 또는 __main__ 모듈을 포함하는 유효한 sys.path 항목(예: 최상위 __main__.py 파일을 포함하는 zipfile)을 가리킬 수 있습니다.

단순 스크립트의 경우 지정된 코드가 새 모듈 네임스페이스에서 실행됩니다. 유효한 sys.path 항목(일반적으로 zipfile 또는 디렉터리)의 경우 항목이 먼저 sys.path의 시작 부분에 추가됩니다. 그런 다음 함수는 업데이트된 경로를 사용하여 __main__ 모듈을 찾아 실행합니다. 지정된 위치에 그런 모듈이 없으면 sys.path의 다른 곳에 위치한 기존 __main__ 항목을 호출하는 것에 대한 특별한 보호가 없다는 점에 유의하세요.

선택적 init_globals 사전 인자는 코드 실행 전에 모듈의 globals 사전을 미리 채우는 데 사용할 수 있습니다. init_globals는 수정되지 않습니다. 특수 전역 변수 중 하나라도 init_globals에 정의되어 있으면 그 정의는 run_path()에 의해 재정의됩니다.

특수 전역 변수 __name__, __spec__, __file__, __cached__, __loader__, __package__는 모듈 코드가 실행되기 전에 globals 사전에 설정됩니다.

  • __name__은 이 선택적 인자가 None이 아니면 run_name으로, 그렇지 않으면 '<run_path>'로 설정됩니다.
  • file_path가 스크립트 파일(소스든 사전 컴파일된 바이트코드든)을 직접 참조하면 __file__은 file_path로 설정되고, __spec__, __cached__, __loader__, __package__는 모두 None으로 설정됩니다.
  • file_path가 유효한 sys.path 항목에 대한 참조이면 __spec__은 import된 __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 항목의 실행을 허용하는 데 필수적이기 때문입니다. 스레드 안전성 제한이 여전히 적용되므로 스레드 코드에서 이 함수를 사용하는 것은 import 잠금으로 직렬화하거나 별도의 프로세스에 위임해야 합니다.

See also

명령줄에서 동등한 기능을 제공하는 인터페이스 옵션(python path/to/script).

versionadded: 3.2.

versionchanged: 3.4에서 PEP 451이 추가한 모듈 스펙 기능을 활용하도록 업데이트되었습니다. 이를 통해 __main__이 유효한 sys.path 항목에서 직접 실행되는 것이 아니라 import되는 경우에 __cached__가 올바르게 설정됩니다.

versionchanged: 3.12에서 __cached__, __loader__, __package__ 설정이 폐기되었습니다.

See also

  • PEP 338 – Executing modules as scripts — Nick Coghlan이 작성하고 구현한 PEP.
  • PEP 366 – Main module explicit relative imports — Nick Coghlan이 작성하고 구현한 PEP.
  • PEP 451 – A ModuleSpec Type for the Import System — Eric Snow가 작성하고 구현한 PEP.
  • 명령줄 및 환경 - CPython 명령줄 세부 사항.
  • importlib.import_module() 함수.

더 알아보기 (Learn more)