traceback — 스택 traceback 출력 또는 검색

traceback — 스택 traceback 출력 또는 검색

이 모듈은 Python 프로그램의 스택 추적(trace)을 추출, 형식화, 출력하는 표준 인터페이스를 제공해요. 인터프리터의 기본 traceback 표시보다 유연해서, 출력의 특정 측면을 구성할 수 있게 해줘요. 마지막으로, 실제 예외에 대한 참조를 저장할 필요 없이 나중에 인쇄할 수 있도록 예외에 대한 충분한 정보를 캡처하는 유틸리티를 포함해요. 예외는 큰 객체 그래프의 루트가 될 수 있으므로, 이 유틸리티는 메모리 관리를 크게 개선할 수 있어요.

이 모듈은 traceback 객체를 사용해요. 이는 BaseException 인스턴스의 __traceback__ 필드에 할당되는 types.TracebackType 타입의 객체예요.

출처: Python documentation

본문

  • faulthandler 모듈: 오류 발생 시, 시간 초과 후, 또는 사용자 신호 시에 Python traceback을 명시적으로 덤프하는 데 사용해요.
  • pdb 모듈: Python 프로그램용 대화형 소스 코드 디버거예요.

모듈의 API는 두 부분으로 나뉘어요:

  1. 예외와 traceback의 대화형 검사에 유용한 기본 기능을 제공하는 모듈 수준 함수
  2. TracebackException 클래스와 그 헬퍼 클래스 StackSummary, FrameSummary. 이들은 생성되는 출력에서 더 큰 유연성과, 실제 예외와 traceback 객체에 대한 참조를 유지하지 않고도 나중에 형식화에 필요한 정보를 저장하는 능력을 제공해요.

버전 3.13에서 추가: 출력이 기본적으로 색상화되며 환경 변수로 제어할 수 있어요.

모듈 수준 함수 (Module-Level Functions)

traceback.print_tb(tb, limit=None, file=None)

limit이 양수이면 traceback 객체 tb에서(호출자 프레임부터 시작) 최대 limit개 스택 추적 항목을 인쇄해요. 그렇지 않으면 마지막 abs(limit)개 항목을 인쇄해요. limit이 생략되거나 None이면 모든 항목을 인쇄해요. file이 생략되거나 None이면 출력은 sys.stderr로 가고, 그렇지 않으면 출력을 받을 열린 파일이나 파일류 객체여야 해요. limit 매개변수의 의미는 sys.tracebacklimit과 다르다는 점에 주의하세요.

traceback.print_exception(exc, /, [value, tb, ]limit=None, file=None, chain=True)

예외 정보와 traceback 객체 tb의 스택 추적 항목을 file로 인쇄해요. print_tb()와 다음 점에서 다릅니다: tb가 None이 아니면 Traceback (most recent call last): 헤더를 인쇄하고, 스택 추적 후 예외 타입과 값을 인쇄하며, type(value)가 SyntaxError이고 형식이 적절하면 구문 오류가 발생한 줄을 오류의 대략적 위치를 가리키는 캐럿과 함께 인쇄해요. Python 3.10부터 value와 tb를 전달하는 대신 예외 객체를 첫 번째 인자로 전달할 수 있어요. chain이 true(기본)이면 연결된 예외(__cause__ 또는 __context__ 속성)도 인터프리터가 처리되지 않은 예외를 인쇄할 때처럼 인쇄돼요.

traceback.print_exc(limit=None, file=None, chain=True)

print_exception(sys.exception(), limit=limit, file=file, chain=chain)의 줄임 표현이에요.

traceback.print_last(limit=None, file=None, chain=True)

print_exception(sys.last_exc, limit=limit, file=file, chain=chain)의 줄임 표현이에요. 일반적으로는 예외가 대화형 프롬프트에 도달한 후에만 작동해요.

traceback.print_stack(f=None, limit=None, file=None)

limit이 양수이면(호출 지점부터) 최대 limit개 스택 추적 항목을 인쇄하고, 그렇지 않으면 마지막 abs(limit)개 항목을 인쇄해요. 선택적 f 인자는 시작할 대체 스택 프레임을 지정해요.

traceback.extract_tb(tb, limit=None)

traceback 객체 tb에서 추출한 "전처리된" 스택 추적 항목 목록을 나타내는 StackSummary 객체를 반환해요. 대체 형식화에 유용해요.

traceback.extract_stack(f=None, limit=None)

현재 스택 프레임에서 원시 traceback을 추출해요. 반환값은 extract_tb()와 같은 형식이에요.

traceback.print_list(extracted_list, file=None)

extract_tb() 또는 extract_stack()이 반환한 튜플 목록을 형식화된 스택 추적으로 주어진 파일에 인쇄해요.

traceback.format_list(extracted_list)

extract_tb() 또는 extract_stack()이 반환한 튜플 또는 FrameSummary 객체 목록이 주어지면 인쇄할 준비가 된 문자열 목록을 반환해요.

traceback.format_exception_only(exc, /, [value, ]*, show_group=False)

sys.last_exc가 주는 것 같은 예외 값을 사용해 traceback의 예외 부분을 형식화해요. 각각 개행으로 끝나는 문자열 목록을 반환해요. show_group이 True이고 예외가 BaseExceptionGroup의 인스턴스이면 중첩 예외도 중첩 깊이에 상대적인 들여쓰기로 재귀적으로 포함돼요.

traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)

스택 추적과 예외 정보를 형식화해요. 각각 개행으로 끝나는 문자열 목록을 반환해요. 이 줄들을 연결해 인쇄하면 print_exception()이 인쇄하는 것과 정확히 같은 텍스트가 돼요.

traceback.format_exc(limit=None, chain=True)

print_exc(limit)와 같지만 파일에 인쇄하는 대신 문자열을 반환해요.

traceback.format_tb(tb, limit=None)

format_list(extract_tb(tb, limit))의 줄임 표현이에요.

traceback.format_stack(f=None, limit=None)

format_list(extract_stack(f, limit))의 줄임 표현이에요.

traceback.clear_frames(tb)

각 프레임 객체의 clear() 메서드를 호출해 traceback tb의 모든 스택 프레임의 지역 변수를 지워요. 버전 3.4에서 추가되었어요.

traceback.walk_stack(f)

주어진 프레임에서 f.f_back을 따라 스택을 탐색하며 각 프레임의 프레임과 줄 번호를 생성해요. f가 None이면 현재 스택을 사용해요. StackSummary.extract()와 함께 사용해요.

traceback.walk_tb(tb)

tb_next를 따라 traceback을 탐색하며 각 프레임의 프레임과 줄 번호를 생성해요. StackSummary.extract()와 함께 사용해요.

TracebackException 객체

TracebackException 객체는 실제 예외에서 생성되어 나중에 인쇄하기 위한 데이터를 캡처해요. traceback과 frame 객체에 대한 참조를 유지하지 않아 정보를 더 가볍게 저장할 수 있어요.

classtraceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)

나중에 렌더링하기 위해 예외를 캡처해요. compact가 true이면 TracebackException의 format() 메서드가 요구하는 데이터만 클래스 속성에 저장돼요. 특히 __context__ 필드는 __cause__가 None이고 __suppress_context__가 false일 때만 계산돼요. 지역 변수가 캡처되면 traceback에도 표시된다는 점에 주의하세요. max_group_width와 max_group_depth는 예외 그룹의 형식화를 제어해요.

주요 속성:

  • __cause__ — 원래 __cause__의 TracebackException
  • __context__ — 원래 __context__의 TracebackException
  • exceptions — ExceptionGroup을 나타내면 중첩 예외를 나타내는 TracebackException 인스턴스 목록, 그렇지 않으면 None
  • __suppress_context__ — 원래 예외의 __suppress_context__ 값
  • __notes__ — 원래 예외의 __notes__ 값 또는 None
  • stack — traceback을 나타내는 StackSummary
  • exc_type — 원래 예외의 클래스 (버전 3.13에서 더 이상 사용되지 않음)
  • exc_type_str — 원래 예외 클래스의 문자열 표시
  • filename, lineno, end_lineno, text, offset, end_offset, msg — 구문 오류용 정보

classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10) — 나중에 렌더링하기 위해 예외를 캡처해요.

print(*, file=None, chain=True) — format()이 반환한 예외 정보를 file(기본 sys.stderr)로 인쇄해요.

format(*, chain=True) — 예외를 형식화해요. chain이 True가 아니면 __cause__와 __context__는 형식화되지 않아요. 개행으로 끝나는 문자열의 제너레이터를 반환해요.

format_exception_only(*, show_group=False) — traceback의 예외 부분을 형식화해요. 개행으로 끝나는 문자열의 제너레이터를 반환해요.

StackSummary 객체

StackSummary 객체는 형식화할 준비가 된 호출 스택을 나타내요.

classtraceback.StackSummary

  • classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False) — 프레임 제너레이터(예: walk_stack() 또는 walk_tb()가 반환한 것)에서 StackSummary 객체를 구축해요.
  • classmethod from_list(a_list) — 제공된 FrameSummary 객체 목록 또는 구식 튜플 목록에서 StackSummary를 구축해요. 각 튜플은 filename, lineno, name, line 요소를 가진 4-tuple이어야 해요.
  • format() — 인쇄할 준비가 된 문자열 목록을 반환해요.
  • format_frame_summary(frame_summary) — 스택에 관련된 프레임 중 하나를 인쇄하기 위한 문자열을 반환해요. None을 반환하면 프레임은 출력에서 생략돼요.

FrameSummary 객체

FrameSummary 객체는 traceback의 단일 프레임을 나타내요.

classtraceback.FrameSummary(filename, lineno, name, *, lookup_line=True, locals=None, line=None, end_lineno=None, colno=None, end_colno=None)

형식화되거나 인쇄되는 traceback 또는 스택의 단일 프레임을 나타내요. 주요 속성: filename, lineno, name, line, end_lineno, colno, end_colno.

모듈 수준 함수 사용 예제

다음 간단한 예제는 기본적인 read-eval-print 루프를 구현해요:

import sys, traceback

def run_user_code(envdir):
    source = input(">>> ")
    try:
        exec(source, envdir)
    except Exception:
        print("Exception in user code:")
        print("-"*60)
        traceback.print_exc(file=sys.stdout)
        print("-"*60)

envdir = {}
while True:
    run_user_code(envdir)

다음 예제는 예외와 traceback을 인쇄하고 형식화하는 다양한 방법을 보여줘요:

import sys, traceback

def lumberjack():
    bright_side_of_life()

def bright_side_of_life():
    return tuple()[0]

try:
    lumberjack()
except IndexError as exc:
    print("*** print_tb:")
    traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
    print("*** print_exception:")
    traceback.print_exception(exc, limit=2, file=sys.stdout)
    ...

TracebackException 사용 예제:

>>> import sys
>>> from traceback import TracebackException
>>> def lumberjack():
...     bright_side_of_life()
>>> def bright_side_of_life():
...     t = "bright", "side", "of", "life"
...     return t[5]
>>> try:
...     lumberjack()
... except IndexError as e:
...     exc = e
>>> # limit은 모듈 수준 함수와 같이 작동
>>> TracebackException.from_exception(exc, limit=-2).print()

capture_locals=True를 주면 프레임의 지역 변수가 추가되고, print()의 chain kwarg는 연결된 예외 표시를 제어해요.

더 알아보기 (Learn more)