trace — 파이썬 구문 실행 추적

trace 모듈은 프로그램 실행을 추적하고, 주석이 달린 구문 커버리지 목록(annotated statement coverage listings)을 생성하고, 호출자/피호출자(caller/callee) 관계를 출력하며, 프로그램 실행 중 호출된 함수를 나열할 수 있게 해 줘요. 다른 프로그램 안에서 쓰거나 커맨드라인에서 쓸 수 있어요.

참고: Coverage.py — HTML 출력과 브랜치 커버리지 같은 고급 기능을 제공하는 인기 있는 서드파티 커버리지 도구예요.

출처: Python 표준 라이브러리 — trace

본문

Command-Line Usage (커맨드라인 사용)

trace 모듈은 커맨드라인에서 호출할 수 있어요. 아주 단순하게는 이렇게 씁니다.

python -m trace --count -C . somefile.py ...

위 명령은 somefile.py를 실행하고, 실행 중 임포트된 모든 파이썬 모듈의 주석 목록을 현재 디렉토리에 생성해요.

--help — 사용법 표시 후 종료.
--version — 모듈 버전 표시 후 종료.
- 버전 3.8에서 추가: 실행 가능한 모듈을 실행할 수 있는 --module 옵션 추가.

Main options (주 옵션)

trace를 호출할 때 다음 옵션 중 적어도 하나는 지정해야 해요. --listfuncs 옵션은 --trace 및 --count 옵션과 상호 배타적이에요. --listfuncs가 주어지면 --count와 --trace 모두 받아들이지 않고, 그 반대도 마찬가지예요.

-c, --count — 프로그램 완료 시 각 구문이 몇 번 실행됐는지 보여주는 주석 목록 파일들을 생성. 아래의 --coverdir, --file, --no-report도 함께 보세요.
-t, --trace — 실행되는 대로 줄을 표시.
-l, --listfuncs — 프로그램 실행으로 호출된 함수를 표시.
-r, --report — --count와 --file 옵션을 사용한 이전 프로그램 실행의 주석 목록을 생성. 어떤 코드도 실행하지 않아요.
-T, --trackcalls — 프로그램 실행으로 드러난 호출 관계를 표시.

Modifiers (수정자)

-f, --file=<file> — 여러 추적 실행에 걸쳐 카운트를 누적할 파일 이름. --count 옵션과 함께 쓰여야 해요.
-C, --coverdir=<dir> — 보고서 파일이 놓일 디렉토리. package.module의 커버리지 보고서는 dir/package/module.cover 파일로 쓰여집니다.
-m, --missing — 주석 목록 생성 시 실행되지 않은 줄을 >>>>>>로 표시.
-s, --summary — --count나 --report를 쓸 때, 처리된 각 파일에 대한 간단한 요약을 stdout에 작성.
-R, --no-report — 주석 목록을 생성하지 않음. --count로 여러 실행을 하고 마지막에 주석 목록 한 벌을 만들려 할 때 유용해요.
-g, --timing — 각 줄 앞에 프로그램 시작 이후 경과 시간을 붙임. 추적 중에만 사용.

Filters (필터)

이 옵션들은 여러 번 반복할 수 있어요.

--ignore-module=<mod> — 주어진 각 모듈 이름과 (패키지라면) 그 서브모듈을 무시. 인자는 쉼표로 구분된 이름 목록일 수 있어요.
--ignore-dir=<dir> — 이름 붙은 디렉토리와 서브디렉토리의 모든 모듈·패키지를 무시. 인자는 os.pathsep으로 구분된 디렉토리 목록일 수 있어요.

Programmatic Interface (프로그래매틱 인터페이스)

class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

단일 구문이나 표현식의 실행을 추적하는 객체를 만들어요. 모든 파라미터는 선택적이에요. count는 줄 번호 카운팅을 활성화하고, trace는 줄 실행 추적을 활성화해요. countfuncs는 실행 중 호출된 함수의 목록을 활성화하고, countcallers는 호출 관계 추적을 활성화해요. ignoremods는 무시할 모듈·패키지 목록이고, ignoredirs는 모듈·패키지를 무시해야 할 디렉토리 목록이에요. infile은 저장된 카운트 정보를 읽을 파일 이름이며, outfile은 갱신된 카운트 정보를 쓸 파일 이름이에요. timing은 추적이 시작된 시점 기준 타임스탬프 표시를 활성화해요.

run(cmd) — 명령을 실행하고 현재 추적 파라미터로 실행 통계를 수집. cmd는 exec()에 넘기기 적합한 문자열 또는 코드 객체여야 해요.

runctx(cmd, globals=None, locals=None) — 정의된 전역·지역 환경에서 명령을 실행하고 현재 추적 파라미터로 통계를 수집. 정의되지 않으면 globals와 locals는 빈 딕셔너리로 기본 설정돼요.

runfunc(func, /, *args, **kwds) — 현재 추적 파라미터를 가진 Trace 객체의 제어 아래, 주어진 인자로 func를 호출.

results() — 주어진 Trace 인스턴스에 대한 이전 run, runctx, runfunc 호출의 누적 결과를 담는 CoverageResults 객체를 반환. 누적된 추적 결과를 리셋하지 않아요.

class trace.CoverageResults — Trace.results()로 만들어지는 커버리지 결과 컨테이너. 사용자가 직접 만들면 안 돼요.

update(other) — 다른 CoverageResults 객체의 데이터를 병합. write_results(show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False) — 커버리지 결과를 작성. show_missing을 설정하면 히트가 없던 줄을 표시하고, summary를 설정하면 모듈별 커버리지 요약을 출력에 포함해요. coverdir은 커버리지 결과 파일이 출력될 디렉토리를 지정하며, None이면 각 소스 파일의 결과가 그 파일이 있는 디렉토리에 놓입니다. ignore_missing_files가 True면 더 이상 존재하지 않는 파일의 커버리지 카운트는 조용히 무시되고, 그렇지 않으면 누락 파일이 FileNotFoundError를 발생시켜요.

버전 3.13에서 변경: ignore_missing_files 파라미터 추가.

프로그래매틱 인터페이스 사용을 보여주는 간단한 예시:

import sys
import trace

# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
    ignoredirs=[sys.prefix, sys.exec_prefix],
    trace=0,
    count=1)

# run the new command using the given tracer
tracer.run('main()')

# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")