"trace" --- 파이썬 문장 실행 추적
*********************************

**소스 코드:** Lib/trace.py

======================================================================

"trace" 모듈을 사용하면 프로그램 실행을 추적하고, 주석 처리된 문장 커
버리지 리스트를 생성하고, 호출자/피호출자 관계를 인쇄하고, 프로그램 실
행 중 호출되는 함수를 나열할 수 있습니다. 다른 프로그램이나 명령 줄에
서 사용할 수 있습니다.

더 보기:

  Coverage.py
     브랜치 커버리지와 같은 고급 기능과 함께 HTML 출력을 제공하는 널리
     사용되는 제삼자 커버리지 도구.


명령 줄 사용법
==============

"trace" 모듈은 명령 줄에서 호출할 수 있습니다. 다음과 같이 간단할 수도
있습니다

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

이것은 "somefile.py"를 실행하고 실행 중에 임포트 한 모든 파이썬 모듈들
의 주석이 달린 리스트를 현재 디렉터리에 생성합니다.

--help

   사용법을 표시하고 종료합니다.

--version

   모듈의 버전을 표시하고 종료합니다.

Added in version 3.8: 실행 가능한 모듈을 실행할 수 있는 "--module" 옵
션이 추가되었습니다.


주요 옵션
---------

"trace"를 호출할 때 다음 옵션 중 적어도 하나를 지정해야 합니다. "--
listfuncs" 옵션은 "--trace" 나 "--count" 옵션과 함께 사용할 수 없습니
다. "--listfuncs"이 제공되면, "--count" 나 "--trace"는 허용되지 않으며
, 반대의 경우도 마찬가지입니다.

-c, --count

   프로그램 완료 시 각 문장이 실행된 횟수를 보여주는 주석이 달린 리스
   팅 파일 집합을 생성합니다. 아래의 "--coverdir", "--file" 및 "--no-
   report"도 참조하십시오.

-t, --trace

   줄이 실행될 때마다 표시합니다.

-l, --listfuncs

   프로그램을 실행하여 실행되는 함수들을 표시합니다.

-r, --report

   "--count" 와 "--file" 옵션을 사용한 이전 프로그램 실행에서 주석이
   달린 목록을 생성합니다. 이것은 어떤 코드도 실행하지 않습니다.

-T, --trackcalls

   프로그램을 실행하여 노출된 호출 관계를 표시합니다.


수정자
------

-f, --file=<file>

   여러 추적 실행에서 실행 횟수를 누적할 파일의 이름. "--count" 옵션과
   함께 사용해야 합니다.

-C, --coverdir=<dir>

   보고서 파일이 저장되는 디렉터리. "package.module"에 대한 커버리지
   보고서는 "*dir*/*package*/*module*.cover" 파일에 기록됩니다.

-m, --missing

   주석이 달린 리스팅을 작성할 때, ">>>>>>"로 실행되지 않은 줄을 표시
   합니다.

-s, --summary

   "--count" 나 "--report"를 사용할 때, 처리된 각 파일에 대한 요약을
   표준출력으로 기록합니다.

-R, --no-report

   주석이 달린 리스팅을 생성하지 않습니다. 이것은 "--count"를 사용하여
   여러 번 실행한 다음, 마지막에 주석이 달린 리스팅의 단일 집합을 생성
   하려고 할 때 유용합니다.

-g, --timing

   프로그램이 시작된 이후의 시간을 각 줄 앞에 붙입니다. 추적하는 동안
   에만 사용됩니다.


필터
----

이 옵션들은 여러 번 반복 될 수 있습니다.

--ignore-module=<mod>

   주어진 각 모듈 이름과 (패키지라면) 그 서브 모듈을 무시합니다. 인자
   는 쉼표로 구분된 이름 목록일 수 있습니다.

--ignore-dir=<dir>

   명명된 디렉터리와 하위 디렉터리의 모든 모듈과 패키지를 무시합니다.
   인자는 "os.pathsep"으로 구분된 디렉터리 목록일 수 있습니다.


프로그래밍 인터페이스
=====================

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"이면, 각 소스 파일의
      결과가 해당 디렉터리에 위치합니다.

      If *ignore_missing_files* is "True", coverage counts for files
      that no longer exist are silently ignored. Otherwise, a missing
      file will raise a "FileNotFoundError".

      버전 3.13에서 변경: Added *ignore_missing_files* parameter.

프로그래밍 인터페이스의 사용을 보여주는 간단한 예제:

   import sys
   import trace

   # Trace 객체를 만들고, 무시할 대상과, 추적할지, 줄을 셀지 또는 둘 다 수행할지를 지정합니다.
   tracer = trace.Trace(
       ignoredirs=[sys.prefix, sys.exec_prefix],
       trace=0,
       count=1)

   # 주어진 tracer를 사용해서 새 명령을 실행합니다
   tracer.run('main()')

   # 보고서를 만들어, 현재 디렉터리에 출력을 넣습니다
   r = tracer.results()
   r.write_results(show_missing=True, coverdir=".")
