13. Python UnicodeError(인코딩·디코딩 오류) 완벽 가이드

이 글에서는 Python에서 텍스트 데이터를 바이트로 변환하거나 바이트를 텍스트로 변환하면서 발생하는 UnicodeError의 정의와 대표 사례를 살펴봅니다. 특히 UnicodeEncodeError와 UnicodeDecodeError의 차이점을 설명하고, 실제 코딩 현장에서 마주치는 주요 원인들을 정리합니다. 단계별 실습 예제와 함께 예외 메시지를 해석하는 방법을 배우고, 효과적인 디버깅 및 예외 처리 기법을 제시합니다. 마지막으로 다음 챕터인 MemoryError & OverflowError: 메모리/산술 오버플로우를 예고합니다.

1. UnicodeError란?

UnicodeError는 Python이 내부적으로 텍스트(str)와 바이트(bytes) 간 변환을 수행할 때, 잘못된 인코딩 또는 디코딩 시퀀스를 만나면 발생하는 내장 예외입니다. UnicodeEncodeError는 텍스트를 바이트로 인코딩할 때, UnicodeDecodeError는 바이트를 텍스트로 디코딩할 때 각각 발생합니다. 예를 들어, UTF-8로 디코딩해야 할 바이트를 ASCII로 처리하거나, 지원하지 않는 코드 포인트를 대상으로 인코딩을 시도하면 해당 예외가 뜹니다. 에러 메시지에는 “codec can't decode byte” 또는 “codec can't encode character” 등의 문구가 포함되어 있어 원인을 파악하는 데 도움을 줍니다.

2. 주요 발생 원인

• 잘못된 인코딩 지정: 파일이나 네트워크로부터 받은 데이터의 실제 인코딩과 open(..., encoding='...')에 지정된 인코딩이 일치하지 않을 때 발생합니다. 
• 기본 디코딩 충돌: Python 2에서는 기본 인코딩이 ASCII, Python 3에서는 UTF-8이지만, 환경 설정이 달라 충돌이 일어날 수 있습니다.
• 외부 라이브러리 데이터: API 응답이나 외부 서비스가 반환한 바이트 스트림이 예상과 다른 인코딩을 사용할 때 오류가 발생합니다.
• 잘못된 이스케이프 시퀀스: 소스 코드 내 문자열에 `\u` 또는 `\U` 이스케이프가 불완전하게 쓰이면 SyntaxError로 처리되기도 하나, 런타임에 UnicodeError가 발생할 수 있습니다.
• 파일 시스템 인코딩 불일치: 운영체제의 파일 시스템 인코딩과 애플리케이션의 디폴트 인코딩이 다를 때, 파일명 처리에서 오류가 생깁니다.

3. 실습 예제

다음 예제 코드를 실행하면 대표적인 UnicodeDecodeError와 UnicodeEncodeError를 재현할 수 있습니다.

# 예제 1: 잘못된 디코딩
data = b'\xff\xfe\x41\x00'
text = data.decode('utf-8')  # UnicodeDecodeError

# 예제 2: 잘못된 인코딩
text = '안녕'
encoded = text.encode('ascii')  # UnicodeEncodeError

첫 번째 예제는 UTF-8이 아닌 바이트를 UTF-8로 디코딩하려 했기 때문에 발생합니다. 두 번째 예제는 Unicode 문자 '안녕'을 ASCII로 인코딩하려 했기 때문에 오류가 뜹니다.

4. 실행 결과 및 설명

Traceback (most recent call last):
  File "example.py", line 2, in 
    text = data.decode('utf-8')
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 0: invalid start byte

Traceback (most recent call last):
  File "example.py", line 6, in 
    encoded = text.encode('ascii')
UnicodeEncodeError: 'ascii' codec can't encode characters in position 0-1: ordinal not in range(128)

에러 메시지는 문제된 바이트 위치와 기대 인코딩을 명시하여, 어느 부분을 어떻게 수정해야 하는지 알려줍니다. 

5. 해결 방법 & 디버깅 팁

1. 인코딩 명시적 지정
   파일 입출력 시 open(path, mode, encoding='utf-8', errors='ignore')와 같이 올바른 인코딩과 오류 처리 정책을 함께 지정하세요.
2. chardet 라이브러리 사용
   pip install chardet 후 chardet.detect()로 바이트 스트림의 인코딩을 추측하여 디코딩합니다.
3. try-except 블록
   ```python try: text = data.decode('utf-8') except UnicodeDecodeError as e: print("디코딩 실패:", e) ``` 런타임 예외를 잡아 상세 정보를 로깅하고, 대체 로직을 실행하세요.
4. binary mode 활용
   텍스트 처리가 아닌 바이너리 처리만 필요하면 open(..., mode='rb')로 파일을 읽어, 후처리 로직을 분리합니다. 
5. 환경 일관성 유지
   개발·배포 환경의 로케일(locale)과 Python 디폴트 인코딩을 통일하거나, PYTHONIOENCODING 환경 변수를 설정해 일관된 동작을 보장합니다.

6. 정리 및 다음 단계

이번 챕터에서는 UnicodeError의 정의, 주요 원인, 실습 예제 및 해결 방법을 살펴보았습니다. 올바른 인코딩 지정과 오류 처리 정책을 통해 인코딩·디코딩 오류를 예방하고, 발생 시 예외 메시지를 바탕으로 빠르게 대처하세요. 다음 챕터에서는 MemoryError & OverflowError: 메모리/산술 오버플로우 문제를 다룰 예정이니 많은 기대 부탁드립니다.