기술 · 실용 가이드
Python charmap UnicodeEncodeError? 먼저 출력 대상을 감사하세요
UTF-8 강제, 전역 모드 변경, 문자 삭제 전에 어떤 writer·대상·consumer가 codec을 선택했는지 증명합니다.
charmap UnicodeEncodeError는 출력 경계 오류입니다. Python의 Unicode 텍스트는 유효하지만 writer의 codec이 어떤 문자를 표현하지 못합니다.
이 감사는 실제 출력 대상을 찾고 console과 redirection을 분리한 뒤 형식을 소유한 경계만 고치고 consumer가 받는 byte를 검증합니다.
실패한 출력 대상과 runtime 계약을 고정합니다
정확한 command, traceback, 문자, Python 버전을 저장하고 sys.stdout.encoding, errors, isatty()를 기록합니다. file object라면 여는 방식과 encoding 인수도 남깁니다. 예외의 codec은 그 경계가 실제 사용한 encoder이며 입력이 망가졌다는 증거가 아닙니다.
console, shell redirection, pipe, IDE, scheduled job, 명시적 file이라는 실제 대상에서 같은 payload를 재현합니다. 한 대상에서만 실패하면 계약 차이의 증거입니다. repr()나 stderr escape 진단으로 code point를 보존하되 원 데이터를 바꾸지 않습니다.
text, character, encoded bytes를 분리합니다
Python str은 Unicode text입니다. text writer가 byte로 바꿀 때 codec이 문자를 표현하지 못하면 UnicodeEncodeError가 납니다. print, text file 쓰기, bytes 전송은 다른 경계입니다. 이미 decode된 text에 decode()를 쓰지 말고 type, code point, writer encoding을 봅니다.
동일 문자와 대상으로 최소 probe를 만듭니다. file은 의도한 encoding으로 열고 byte를 다시 읽습니다. stream은 같은 consumer에 보내 기대 형식을 검증합니다. encoder와 이를 소비하는 프로그램·형식·protocol 양쪽을 증명해야 합니다.
Windows console, redirection, wrapper 차이를 증명합니다
Python 문서는 standard stream encoding이 console 연결, file redirection, wrapper 교체에 따라 달라질 수 있다고 설명합니다. Windows console device와 일반 file은 같은 경로가 아닐 수 있습니다. Microsoft code page는 console I/O 속성이지 모든 file의 범용 encoding이 아닙니다.
console, redirect, 실패하는 IDE/service에서 같은 command를 실행하고 세 runtime field를 비교합니다. sys.stdout이 교체됐다면 type과 설정을 봅니다. chcp만으로 file encoding을 추론하거나 terminal 성공만으로 downstream file이 UTF-8이라 단정하지 않습니다.
형식을 소유한 경계에 수정을 둡니다
UTF-8 text file을 만들면 encoding='utf-8'로 명시해 열고 형식을 문서화합니다. subprocess가 UTF-8을 원하면 그 경계를 설정하고 byte를 확인합니다. CLI의 UTF-8 mode나 PYTHONIOENCODING은 stdout/stderr의 모든 consumer를 확인한 뒤 고려합니다.
sys.stdout.reconfigure()는 application이 stream을 소유하고 비호환 buffered data를 아직 쓰지 않았을 때만 씁니다. library가 host의 global policy를 몰래 바꾸면 안 됩니다. framework나 notebook이 writer를 제공하면 그 owner를 설정합니다.
손실 억제를 기본 해결책으로 쓰지 않습니다
errors='ignore'는 문자를 삭제하고 errors='replace'는 데이터를 바꿉니다. name, path, identifier, export record를 손상시키면서 test만 통과할 수 있습니다. 출력 계약이 명시적으로 허용할 때만 쓰고 변하는 문자를 기록합니다.
UTF-8로 encode한 직후 무관한 legacy codec으로 decode하면 명확한 경계 오류가 mojibake나 후속 실패로 바뀝니다. system locale나 모든 Python process를 바꾸기보다 consumer 계약을 아는 가장 좁은 writer를 고칩니다.
byte, consumer 동작, rollback을 검증합니다
ASCII, 원래 실패 문자, local code page 밖 문자, 혼합 언어 줄로 matrix를 만들고 console, redirected file, 실제 downstream에서 시험합니다. 정확한 byte나 hash를 기록하고 선언한 형식으로 decode하여 같은 text를 표시·해석하는지 확인합니다.
runtime field, sample, boundary, encoding, error policy, consumer 결과를 보관합니다. rollback은 다른 stream을 건드리지 않고 writer 설정만 되돌립니다. Python, Windows, IDE, service wrapper 업데이트 후에도 기본값 변경에 대비해 다시 시험합니다.
