# `runpy` — 파이썬 모듈 찾기와 실행

소스 코드: Lib/runpy.py

`runpy` 모듈은 파이썬 모듈을 먼저 임포트 하지 않고 찾아서 실행하는 데 사용합니다. 주요 용도는 파일 시스템이 아닌 파이썬 모듈 이름 공간을 사용하여 스크립트를 찾을 수 있는 `-m` 명령 줄 스위치를 구현하는 것입니다.

이것은 샌드박스 모듈이 아닙니다 - 모든 코드가 현재 프로세스에서 실행되고, 모든 부작용(가령 다른 모듈의 캐시된 임포트)은 함수가 반환된 후에도 그대로 유지됩니다.

또한, 실행된 코드에서 정의된 모든 함수와 클래스는 `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__`은 (이 선택적 인자가 `None`이 아니면) run_name으로, 명명된 모듈이 패키지면 `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이 추가한 모듈 스펙 기능을 활용하도록 갱신되었습니다. 이것은 실제 모듈 이름을 항상 `__spec__.name`으로 액세스할 수 있으면서, `__cached__`가 이 방법으로 실행되는 모듈에 대해 올바르게 설정되도록 합니다.

  버전 3.12에서 변경: `__cached__`, `__loader__` 및 `__package__`의 설정은 폐지되었습니다. 대안은 `ModuleSpec`을 참조하세요.

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

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

  간단한 스크립트의 경우, 지정된 코드는 단순히 새로운 모듈 이름 공간에서 실행됩니다. 유효한 `sys.path` 항목(보통 zip 파일이나 디렉터리)의 경우, 항목이 먼저 `sys.path`의 시작 부분에 추가됩니다. 그런 다음 함수는 갱신된 경로를 사용하여 `__main__` 모듈을 찾아 실행합니다. 지정된 위치에 해당 모듈이 없을 때 `sys.path`의 다른 위치에 있는 기존 `__main__` 항목을 호출하는 것을 막는 특별한 보호 장치가 없다는 점에 유의하십시오.

  선택적 딕셔너리 인자 init_globals는 코드가 실행되기 전에 모듈의 전역 딕셔너리를 미리 채우기 위해 사용될 수 있습니다. init_globals는 수정되지 않습니다. 아래의 특수 전역 변수가 init_globals에 정의되어 있으면, 해당 정의가 `run_path()`에 의해 대체됩니다.

  특수 전역 변수 `__name__`, `__spec__`, `__file__`, `__cached__`, `__loader__` 및 `__package__`는 모듈 코드가 실행되기 전에 전역 딕셔너리에 설정됩니다. (이 변수는 최소한의 변수 집합임에 유의하십시오 - 인터프리터 구현 세부 사항에 따라 다른 변수가 묵시적으로 설정될 수 있습니다.)

  `__name__`은 (이 선택적 인자가 `None`이 아니면) run_name으로, 그렇지 않으면 `'<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`).

  Added in version 3.2.

  버전 3.4에서 변경: PEP 451이 추가한 모듈 스펙 기능을 활용하도록 갱신되었습니다. 이것은 `__main__`이 직접 실행되는 대신 유효한 `sys.path` 항목에서 임포트 될 때 `__cached__`가 올바르게 설정되도록 합니다.

  버전 3.12에서 변경: `__cached__`, `__loader__` 및 `__package__`의 설정은 폐지되었습니다.

더 보기

PEP 338 – 모듈을 스크립트로 실행하기

  Nick Coghlan이 작성하고 구현한 PEP.

PEP 366 – 메인 모듈 명시적 상대 임포트

  Nick Coghlan이 작성하고 구현한 PEP.

PEP 451 – 임포트 시스템의 ModuleSpec 형

  Eric Snow가 작성하고 구현한 PEP

명령 줄과 환경 - CPython 명령 줄 세부 사항

`importlib.import_module()` 함수