"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*는 코드가 실행되기 전에 모듈의
   전역 딕셔너리를 미리 채우기 위해 사용될 수 있습니다. 제공된 딕셔너
   리는 수정되지 않습니다. 아래의 특수 전역 변수가 제공된 딕셔너리에
   정의되어 있으면, 해당 정의가 "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__"가 이 방법으로 실행되는 모듈에 대해
   올바르게 설정되도록 합니다.

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

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

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

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

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

   "__name__"은 (이 선택적 인자가 "None"이 아니면) *run_name*으로, 그
   렇지 않으면 "'<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]"은 "file_path" 값
   으로 갱신되고 "sys.modules[__name__]"은 실행 중인 모듈에 대한 임시
   모듈 객체로 갱신됩니다. 함수가 반환되기 전에 "sys"의 항목에 대한 모
   든 수정 내용이 되돌려집니다.

   "run_module()"과 달리, "sys"에 대한 변경은 이 함수에서는 선택 사항
   이 아닌데, 이 조정이 sys.path 항목의 실행을 허용하는 데 필수적이기
   때문입니다. 스레드-안전 제약 사항이 계속 적용되므로, 스레드를 사용
   하는 코드에서 이 함수를 사용하려면 임포트 잠금을 사용하여 직렬화하
   거나 별도의 프로세스에 위임해야 합니다.

   더 보기: 명령 줄에서의 동등한 기능에 대한 인터페이스 옵션 ("python
         path/to/script").

   버전 3.2에 추가.

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

더 보기:

  **PEP 338** -- 모듈을 스크립트로 실행하기
     Nick Coghlan이 작성하고 구현한 PEP.

  **PEP 366** -- 메인 모듈 명시적 상대 임포트
     Nick Coghlan이 작성하고 구현한 PEP.

  **PEP 451** -- 임포트 시스템의 ModuleSpec 형
     Eric Snow가 작성하고 구현한 PEP

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

  "importlib.import_module()" 함수
