Documentation과 에러 메시지 읽는 법

이 토픽을 마치면

Python 에러 메시지(Traceback)를 읽고 문제 위치를 찾는 방법, 그리고 공식 문서에서 원하는 정보를 빠르게 찾는 습관을 익힙니다.

에러가 나면 어디를 봐야 하나

Traceback (most recent call last):
  File "main.py", line 12, in <module>
    result = calculate(data)
  File "main.py", line 7, in calculate
    return total / count
ZeroDivisionError: division by zero

초보 때는 빨간 글씨가 나오면 당황합니다. 하지만 Python의 에러 메시지는 매우 친절합니다. 읽는 순서가 있습니다:

1. 맨 아래 줄부터 읽으세요 — ZeroDivisionError: division by zero. 뭐가 잘못됐는지 알려줍니다
2. 바로 위 — return total / count. 어디서 발생했는지 코드를 보여줍니다
3. 그 위 — File "main.py", line 7. 파일명과 줄 번호를 알려줍니다

Traceback은 아래에서 위로 읽는 겁니다. 맨 아래가 실제 에러, 위로 올라갈수록 "어디서 이 함수를 호출했는지" 추적 경로입니다.

자주 보는 에러 5가지

이 다섯 개가 초보 때 보는 에러의 80% 이상을 차지합니다.

에러 메시지로 검색하기

에러를 해결하는 가장 빠른 방법:

1. 마지막 줄 전체를 복사합니다 — ZeroDivisionError: division by zero
2. 그대로 검색합니다
3. Stack Overflow나 공식 문서에서 같은 에러를 겪은 사람의 해결책을 봅니다

이때 중요한 건 자기 변수명은 빼고 검색하는 것입니다. my_data는 나만 쓰는 이름이니까 검색에 도움이 안 됩니다. 에러 타입 + 에러 메시지만 검색하세요.

공식 문서 읽는 법

Python 공식 문서(docs.python.org)는 처음엔 읽기 어렵게 느껴집니다. 전부 읽으려 하지 마세요. 필요한 부분만 찾으면 됩니다.

# "리스트에서 특정 값을 제거하고 싶다"
# → 검색: "python list remove"
# → docs.python.org/3/tutorial/datastructures.html

# list.remove(x)
#   Remove the first item from the list whose value
#   is equal to x. It raises a ValueError if there
#   is no such item.

공식 문서가 알려주는 것:

• 무슨 일을 하는지 — 첫 번째 일치 항목 제거
• 주의사항 — 없으면 ValueError 발생
• 반환값 — (여기선 None — 원본을 수정함)

이 세 가지만 확인하면 됩니다. 실습 환경에서 직접 테스트하면서 문서를 읽는 게 가장 효과적입니다.

유용한 내장 도움말

# 터미널에서 바로 문서 보기
help(str.split)

# 객체가 가진 메서드 목록 보기
dir(str)

# 타입 확인
type(my_variable)

help()는 대화형 셸(REPL)에서 쓸 수 있습니다. 인터넷 없이도 문서를 볼 수 있습니다.

dir()은 "이 객체에 뭐가 있지?" 할 때 씁니다. 리스트가 나오면 .sort(), .reverse() 같은 메서드를 발견할 수 있습니다.

디버깅 습관

에러가 안 나는데 결과가 이상할 때:

# 1. 중간중간 print 찍기
print(f"data: {data}")
print(f"count: {count}")
result = total / count

# 2. 타입 확인
print(type(result))  # <class 'float'> vs <class 'str'>

# 3. 작은 단위로 테스트
# 함수 전체를 실행하지 말고, 한 줄씩 REPL에서 확인

print로 디버깅하는 건 원시적이지만, 초보 단계에서는 가장 확실합니다. 변수에 뭐가 들어있는지 추측하지 말고 찍어보세요.

핵심

에러 메시지는 아래에서 위로 읽습니다. 맨 아래 = 뭐가 잘못됐는지, 위 = 어디서 발생했는지. 검색할 때는 에러 타입 + 메시지만 복사하고, 자기 변수명은 빼세요. 공식 문서는 전부 읽지 마세요 — 뭘 하는지, 주의사항, 반환값 세 가지만 확인하면 됩니다.