compileall — 파이썬 라이브러리 바이트 컴파일

compileall — 파이썬 라이브러리 바이트 컴파일

(소스: Lib/compileall.py)

이 모듈은 파이썬 라이브러리 설치를 지원하는 몇 가지 유틸리티 함수를 제공해요. 이 함수들은 디렉터리 트리 안의 파이썬 소스 파일을 컴파일해요. 이 모듈은 라이브러리 설치 시점에 캐시된 바이트 코드 파일을 만들어, 라이브러리 디렉터리에 쓰기 권한이 없는 사용자도 사용할 수 있게 해 줘요.

가용성: WASI에서는 동작하지 않아요. WebAssembly에서 이 모듈은 동작하지 않거나 사용할 수 없어요.

출처: Python documentation

본문

커맨드라인 사용

이 모듈은 스크립트로(python -m compileall) 파이썬 소스를 컴파일할 수 있어요.

  • directory ... / file ...: 위치 인자는 컴파일할 파일 또는 소스 파일을 담은 (재귀적으로 탐색되는) 디렉터리. 인자가 없으면 -l <sys.path의 디렉터리들>인 것처럼 동작.
  • -l: 서브디렉터리로 재귀하지 않고 명명되거나 암시된 디렉터리에 직접 포함된 소스 코드 파일만 컴파일.
  • -f: 타임스탬프가 최신이어도 강제 재빌드.
  • -q: 컴파일된 파일 목록을 출력하지 않음. 한 번 넘기면 오류 메시지는 여전히 출력. 두 번(-qq) 넘기면 모든 출력 억제.
  • -d destdir: 컴파일되는 각 파일 경로에 앞에 붙는 디렉터리. 컴파일 시간 traceback에 나타나고 바이트 코드 파일에도 컴파일되어, 바이트 코드 실행 시점에 소스 파일이 없을 때 traceback과 다른 메시지에 사용돼요.
  • -s strip_prefix: .pyc 파일에 기록된 경로에서 주어진 접두사를 제거. 접두사에 상대적으로 경로가 만들어져요. -p와 쓸 수 있지만 -d와는 못 써요.
  • -p prepend_prefix: .pyc 파일에 기록된 경로 앞에 주어진 접두사를 추가. -p /로 경로를 절대화할 수 있어요. -s와 쓸 수 있지만 -d와는 못 써요.
  • -x regex: regex로 컴파일을 고려하는 각 파일의 전체 경로를 검색하고, 매치되면 건너뛰어요.
  • -i list: 파일 목록을 읽어 각 줄을 컴파일할 파일·디렉터리 목록에 추가. list가 -면 stdin에서 줄 읽기.
  • -b: 바이트 코드 파일을 레거시 위치·이름에 써요. 다른 버전의 파이썬이 만든 바이트 코드 파일을 덮어쓸 수 있어요. 기본은 PEP 3147 위치·이름에 써서 여러 파이썬 버전의 바이트 코드가 공존할 수 있게 해요.
  • -r: 서브디렉터리의 최대 재귀 수준 제어. 주어지면 -l 옵션은 고려되지 않아요. python -m compileall <directory> -r 0은 ... -l과 동등.
  • -j N: N개의 워커로 주어진 디렉터리 안의 파일을 컴파일. 0이면 os.process_cpu_count() 결과 사용.
  • --invalidation-mode [timestamp|checked-hash|unchecked-hash]: 생성된 바이트 코드 파일이 런타임에 어떻게 무효화되는지 제어. timestamp는 소스 타임스탬프와 크기가 내장된 .pyc 파일 생성, checked-hash/unchecked-hash는 hash 기반 pyc 생성(타임스탬프 대신 소스 내용의 해시 내장). 기본은 SOURCE_DATE_EPOCH 환경 변수가 설정되지 않았으면 timestamp, 설정됐으면 checked-hash.
  • -o level: 주어진 최적화 수준으로 컴파일. 여러 수준으로 컴파일하려면 여러 번 사용 가능(예: compileall -o 1 -o 2).
  • -e dir: 주어진 디렉터리 밖을 가리키는 심볼릭 링크 무시.
  • --hardlink-dupes: 다른 최적화 수준의 두 .pyc 파일 내용이 같으면 하드 링크로 중복 파일 통합.

compile() 함수가 쓰는 최적화 수준을 제어하는 커맨드라인 옵션은 없어요. 파이썬 인터프리터 자체가 옵션을 제공하기 때문이에요: python -O -m compileall. 마찬가지로 compile() 함수는 sys.pycache_prefix 설정을 존중해요. 생성된 바이트 코드 캐시는 런타임에 쓰일 것과 같은 sys.pycache_prefix(있다면)로 compile()이 실행될 때만 유용해요.

공개 함수

  • compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False): dir이 이름 붙은 디렉터리 트리를 재귀적으로 내려가며 .py 파일을 모두 컴파일. 모든 파일이 성공적으로 컴파일되면 true, 아니면 false 반환. maxlevels는 재귀 깊이 제한(기본 sys.getrecursionlimit()). ddir은 컴파일 시간 traceback용 경로 앞에 추가. force가 true면 타임스탬프가 최신이어도 재컴파일. rx가 주어지면 그 검색 메서드를 컴파일 고려 각 파일의 전체 경로에 호출하고 true 반환 시 건너뜀(re.Pattern 객체). quiet이 False/0(기본)이면 파일 이름과 정보를 표준 출력에 출력, 1이면 오류만, 2면 전부 억제. legacy가 true면 레거시 위치·이름에 작성. optimize는 컴파일러 최적화 수준(내장 compile()에 전달). 시퀀스도 받아 한 번의 호출에서 하나의 .py 파일을 여러 번 컴파일. workers는 병렬 컴파일 워커 수(기본 다중 워커 안 씀; 플랫폼이 못 쓰면 순차 컴파일로 폴백; 0이면 시스템 코어 수; 0보다 작으면 ValueError). invalidation_mode는 py_compile.PycInvalidationMode enum 멤버. stripdir, prependdir, limit_sl_dest는 -s/-p/-e 옵션에 해당하고 str 또는 os.PathLike로 지정. hardlink_dupes가 true면 다른 최적화 수준의 .pyc 내용이 같을 때 하드 링크 사용. (기본 maxlevels가 10에서 sys.getrecursionlimit()로 변경됨)

  • compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False): fullname 경로의 파일 컴파일. 성공 시 true 반환. compile_dir과 비슷한 인자들. (3.2 추가)

    compile_dir에서 rx는 "true 반환 시 파일 건너뜀", compile_file의 rx는 "true 반환 시 파일 컴파일 안 하고 True 반환" — 둘 다 제외 의미예요.

  • compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None): sys.path를 따라 발견된 모든 .py 파일을 바이트 컴파일. 모든 파일이 성공하면 true 반환. skip_curdir이 true(기본)면 검색에 현재 디렉터리 제외. 다른 인자는 compile_dir에 전달. 다른 compile 함수와 달리 maxlevels 기본이 0이에요.

예제:

import compileall
compileall.compile_dir('Lib/', force=True)
# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)
# pathlib.Path objects can also be used.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)

참고: py_compile 모듈(단일 소스 파일 바이트 컴파일)도 함께 보세요.

더 알아보기 (Learn more)