py_compile — Python 소스 파일 컴파일

소스 코드: Lib/py_compile.py

py_compile 모듈은 소스 파일에서 바이트-코드 파일을 생성하는 함수와, 모듈 소스 파일을 스크립트로 호출할 때 사용되는 또 다른 함수를 제공해요.

자주 필요하진 않지만, 특히 소스 코드가 포함된 디렉터리에 바이트-코드 캐시 파일을 쓸 권한이 없는 사용자가 있을 때, 공유 사용을 위해 모듈을 설치할 때 이 함수가 유용할 수 있어요.

출처: Python 표준 라이브러리

본문

exception py_compile.PyCompileError

파일을 컴파일하는 동안 오류가 발생하면 발생하는 예외예요.

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

소스 파일을 바이트-코드로 컴파일하고 바이트-코드 캐시 파일을 써요. 소스 코드는 file이라는 파일에서 로드되고, 바이트-코드는 기본적으로 PEP 3147/PEP 488 경로(.pyc로 끝남)를 따르는 cfile에 쓰여요.

예를 들어 file이 /foo/bar/baz.py라면 Python 3.2에서 cfile은 기본적으로 /foo/bar/__pycache__/baz.cpython-32.pyc가 돼요. dfile이 지정되면 예외 traceback에 표시할 소스 줄을 얻어오는 소스 파일의 이름으로 file 대신 사용돼요.

doraise가 참이면 file을 컴파일하는 동안 오류가 발생했을 때 PyCompileError가 발생해요. doraise가 거짓(기본)이면 오류 문자열이 sys.stderr에 쓰이지만 예외는 발생하지 않아요. 이 함수는 바이트-컴파일된 파일의 경로, 즉 사용된 cfile 값을 돌려줘요.

doraise와 quiet 인자는 file을 컴파일하는 동안 오류를 어떻게 처리할지 결정해요. quiet가 0 또는 1이고 doraise가 거짓이면 기본 동작이 활성화돼요. 오류 문자열이 sys.stderr에 쓰이고, 함수는 경로 대신 None을 돌려줘요. doraise가 참이면 대신 PyCompileError가 발생해요. 그러나 quiet가 2면 메시지가 쓰이지 않고 doraise는 효과가 없어요.

cfile이 되는 경로(명시적으로 지정되든 계산되든)가 심볼릭 링크이거나 보통 파일이 아니면 FileExistsError가 발생해요. 이는 import가 그 경로에 바이트-컴파일 파일을 쓸 수 있다면 그 경로를 보통 파일로 바꿔 버릴 거라는 경고로 작용해요. 이것은 동시 파일 쓰기 문제를 막기 위해 import가 파일 이름 바꾸기(renaming)를 사용해 최종 바이트-컴파일 파일을 배치하는 부작용이에요.

optimize는 최적화 수준을 제어하며 내장 compile() 함수로 전달돼요. 기본값 -1은 현재 인터프리터의 최적화 수준을 선택해요.

invalidation_mode는 PycInvalidationMode 열거형의 멤버여야 하며, 생성된 바이트코드 캐시를 런타임에 어떻게 무효화할지 제어해요. SOURCE_DATE_EPOCH 환경 변수가 설정되어 있으면 기본값은 PycInvalidationMode.CHECKED_HASH이고, 그렇지 않으면 기본값은 PycInvalidationMode.TIMESTAMP예요.

버전 3.2에서 변경: cfile의 기본값을 PEP 3147 호환으로 변경. 이전 기본값은 file + 'c'(최적화를 켜면 'o')였음. optimize 매개변수도 추가.

버전 3.4에서 변경: 바이트-코드 캐시 파일 쓰기에 importlib을 사용하도록 코드 변경. 즉 파일 생성·쓰기 의미가 이제 importlib이 하는 것과 일치함(권한, 쓰기 후 이동(write-and-move) 의미 등). cfile이 심볼릭 링크이거나 보통 파일이 아니면 FileExistsError가 발생한다는 주의 사항도 추가.

버전 3.7에서 변경: invalidation_mode 매개변수를 PEP 552에 명시된 대로 추가. SOURCE_DATE_EPOCH가 설정되면 invalidation_mode는 PycInvalidationMode.CHECKED_HASH로 강제됨.

버전 3.7.2에서 변경: SOURCE_DATE_EPOCH 환경 변수가 더 이상 invalidation_mode 인자의 값을 덮어쓰지 않고, 그 기본값을 결정함.

버전 3.8에서 변경: quiet 매개변수 추가.

class py_compile.PycInvalidationMode

인터프리터가 바이트코드 파일이 소스 파일과 최신 상태인지 판단하는 데 사용할 수 있는 가능한 방법들의 열거형이에요. .pyc 파일은 헤더에 원하는 무효화 모드를 표시해요. Python이 런타임에 .pyc 파일을 어떻게 무효화하는지에 대한 자세한 내용은 캐시된 바이트코드 무효화를 참고하세요.

버전 3.7에 추가.

TIMESTAMP — .pyc 파일에 소스 파일의 타임스탬프와 크기가 포함돼요. Python은 런타임에 이것을 소스 파일의 메타데이터와 비교해 .pyc 파일을 다시 생성해야 하는지 판단해요.
CHECKED_HASH — .pyc 파일에 소스 파일 내용의 해시가 포함돼요. Python은 런타임에 그것을 소스와 비교해 .pyc 파일을 다시 생성해야 하는지 판단해요.
UNCHECKED_HASH — CHECKED_HASH처럼 .pyc 파일에 소스 파일 내용의 해시가 포함돼요. 그러나 Python은 런타임에 .pyc 파일이 최신 상태라고 가정하고 소스 파일과 전혀 대조하지 않아요. 빌드 시스템처럼 Python 외부의 어떤 시스템이 .pyc 파일을 최신 상태로 유지할 때 유용한 옵션이에요.

명령줄 인터페이스 (Command-Line Interface)

이 모듈은 여러 소스 파일을 컴파일하는 스크립트로 호출할 수 있어요. filenames에 이름이 지정된 파일들이 컴파일되고, 결과 바이트코드가 정상적인 방식으로 캐시돼요. 이 프로그램은 소스 파일을 찾기 위해 디렉터리 구조를 검색하지 않아요. 명시적으로 이름이 지정된 파일만 컴파일해요. 파일 중 하나라도 컴파일할 수 없으면 종료 상태가 0이 아니에요.

<file>...<fileN> — 위치 인자는 컴파일할 파일들이에요. -가 유일한 매개변수면 파일 목록은 표준 입력에서 가져와요.
-q, --quiet — 오류 출력을 억제해요.

버전 3.2에서 변경: - 지원 추가.

버전 3.10에서 변경: -q 지원 추가.

더 알아보기

compileall 모듈 — 디렉터리 트리에 있는 모든 Python 소스 파일을 바이트-컴파일하는 유틸리티.