초보잡학

이 글에서는 Python 함수 내부에서 지역변수가 값을 할당받기 전에 참조될 때 발생하는 UnboundLocalError의 정의와 주요 원인, 대표 예제, 그리고 효과적인 해결 방법을 단계별로 알아봅니다. 디버깅 팁과 권장 패턴을 통해 실전 코드에서 발생하는 UnboundLocalError를 쉽고 빠르게 해결할 수 있도록 도와드립니다. 다음 챕터에서는 ImportError / ModuleNotFoundError: 모듈/경로 문제를 다룹니다.

1. UnboundLocalError란?

UnboundLocalError는 함수 내에서 지역변수가 할당되기 전에 해당 변수를 참조하려 할 때 발생하는 내장 예외입니다. Python은 함수 본문에서 변수를 할당(assign)하면 해당 이름을 지역(local) 변수로 간주하기 때문에, 할당 지점 이전에 참조하려 하면 이 오류가 뜹니다. 대표적인 메시지는 UnboundLocalError: local variable 'x' referenced before assignment와 같이 나타나며, 파이썬 인터프리터가 문제의 변수 이름과 위치를 명확히 알려줍니다.

2. 주요 발생 원인

• 함수 내부에서 같은 이름으로 할당 - 함수 안에서 변수를 한 번이라도 할당하면, 전체가 지역 변수로 취급됩니다. - 할당 지점 이전에 참조하면 오류가 발생합니다.
• global/nonlocal 선언 누락 - 전역 변수를 수정하려면 global 키워드, 중첩 함수 변수는 nonlocal 선언이 필요합니다.
• LEGB 스코프 오해 - Python은 Local, Enclosing, Global, Built-in 순으로 이름을 검색(LEGB 규칙)하며, 할당이 감지되면 로컬 검색만 수행합니다.
• 조건문 내부 할당 후 참조 - 특정 조건문 블록에서만 할당되고, 다른 경로에서 참조될 때 할당되지 않은 상태가 됩니다.
• try-except 블록 내 변수 사용 - 예외 처리 블록에서만 변수에 값을 할당하고, 정상 흐름에서 참조하면 오류가 발생합니다.

3. 실습 예제

아래 예제를 통해 UnboundLocalError 발생 상황을 확인해보세요.

# 예제: 함수 내 지역변수 참조 전에 사용
x = 10

def func():
    print(x)      # 전역 x가 아닌 지역 x로 간주 → 오류
    x = x + 5     # 지역변수 x 할당

func()

위 코드에서 함수 내부의 x = x + 5 구문이 실행되면, Python은 전체 함수 본문에서 x를 지역 변수로 인식합니다. 따라서 print(x)는 아직 할당되지 않은 지역 x를 참조하게 되어 UnboundLocalError가 발생합니다.

4. 실행 결과 및 설명

Traceback (most recent call last):
  File "example.py", line 6, in 
    func()
  File "example.py", line 3, in func
    print(x)
UnboundLocalError: local variable 'x' referenced before assignment

에러 메시지는 문제가 된 변수 이름('x')과 함께 할당 이전에 참조되었음을 알려줍니다. 이를 통해 오류 발생 지점을 빠르게 파악할 수 있습니다.

5. 해결 방법 & 디버깅 팁

1. global 키워드 사용 - 전역 변수를 함수에서 수정할 때는 global x 선언을 추가합니다.

   def func():
       global x
       print(x)
       x = x + 5

2. nonlocal 키워드 사용 - 중첩 함수에서 외부 함수의 변수를 수정하려면 nonlocal을 선언합니다.
3. 함수 인자 전달 - 필요한 변수는 인자로 전달해 지역변수와 전역변수 충돌을 피합니다.

   def func(x):
       print(x)
       return x + 5
   
   x = func(x)

4. 조건문 할당 점검 - 모든 코드 경로에서 변수가 할당되도록 보장하거나, 할당 전 기본값을 설정합니다.
5. 스코프 이해 강화 - Real Python과 같은 자료로 LEGB 규칙을 학습해 스코프 동작을 이해하세요.

6. 정리 및 다음 단계

이번 챕터에서는 UnboundLocalError의 정의, 원인, 예제 및 해결 방법을 살펴보았습니다. global/nonlocal 선언 또는 함수 인자를 통해 지역변수 충돌을 예방하세요. 다음 챕터에서는 ImportError / ModuleNotFoundError: 모듈/경로 문제를 다룰 예정입니다.