codecs — 코덱 레지스트리와 기본 클래스

codecs — 코덱 레지스트리와 기본 클래스

codecs 모듈은 표준 Python 코덱(인코더와 디코더)의 기본 클래스를 정의하고, 코덱과 오류 처리 조회 과정을 관리하는 내부 Python 코덱 레지스트리에 접근할 수 있게 해 줘요. 대부분의 표준 코덱은 텍스트 인코딩으로, 텍스트를 바이트로 인코딩하고(바이트를 텍스트로 디코딩하고) 하지만 텍스트→텍스트나 바이트→바이트로 변환하는 코덱도 있어요. 커스텀 코덱은 임의 타입 사이를 인코딩·디코딩할 수 있지만, 일부 모듈 기능은 텍스트 인코딩이나 바이트로 인코딩하는 코덱에 한정해서 쓰입니다.

출처: Python 표준 라이브러리

본문

인코딩·디코딩 함수

codecs.encode(obj, encoding='utf-8', errors='strict') — encoding으로 등록된 코덱을 사용해 obj를 인코딩해요. errors로 오류 처리 방식을 정할 수 있고, 기본 오류 핸들러는 'strict'라서 인코딩 오류가 나면 ValueError(또는 UnicodeEncodeError 같은 더 구체적인 서브클래스)를 일으킵니다.

codecs.decode(obj, encoding='utf-8', errors='strict') — encoding으로 등록된 코덱을 사용해 obj를 디코딩해요. 기본 오류 핸들러는 'strict'라서 디코딩 오류 시 ValueError(또는 UnicodeDecodeError)를 일으킵니다.

codecs.charmap_build(string) — 사용자 정의 단일 바이트 인코딩에 사용할 매핑을 반환해요. 디코딩 테이블을 나타내는 최대 256자의 str 문자열을 받아 컴팩트한 내부 매핑 객체 EncodingMap이나, 문자 ordinal을 바이트 값으로 매핑하는 딕셔너리를 반환합니다. 잘못된 입력이면 TypeError를 일으켜요.

각 코덱의 자세한 정보는 직접 조회할 수도 있어요.

codecs.lookup(encoding, /) — Python 코덱 레지스트리에서 코덱 정보를 찾아 아래 정의된 CodecInfo 객체를 반환해요. 인코딩은 먼저 레지스트리의 캐시에서 찾고, 없으면 등록된 검색 함수 목록을 훑어요. CodecInfo 객체를 못 찾으면 LookupError를 일으키고, 찾으면 캐시에 저장한 뒤 호출자에게 반환합니다.

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None) — 코덱 레지스트리를 조회할 때의 코덱 세부 정보예요. 생성자 인자는 같은 이름의 속성으로 저장됩니다.

코덱 구성 요소에 쉽게 접근하도록, 모듈은 lookup()을 사용하는 이 추가 함수들을 제공해요.

  • codecs.getencoder(encoding) — 인코더 함수 반환. 못 찾으면 LookupError.
  • codecs.getdecoder(encoding) — 디코더 함수 반환. 못 찾으면 LookupError.
  • codecs.getincrementalencoder(encoding) — 증분 인코더 클래스/팩토리 함수 반환. 못 찾거나 증분 인코더 미지원 시 LookupError.
  • codecs.getincrementaldecoder(encoding) — 증분 디코더 클래스/팩토리 함수 반환. 못 찾거나 미지원 시 LookupError.
  • codecs.getreader(encoding) — StreamReader 클래스/팩토리 함수 반환. 못 찾으면 LookupError.
  • codecs.getwriter(encoding) — StreamWriter 클래스/팩토리 함수 반환. 못 찾으면 LookupError.

커스텀 코덱은 적절한 코덱 검색 함수를 등록해 사용할 수 있어요.

codecs.register(search_function, /) — 코덱 검색 함수를 등록해요. 검색 함수는 인자 하나(하이픈과 공백을 밑줄로 바꾼, 전부 소문자인 인코딩 이름)를 받아 CodecInfo 객체를 반환해야 해요. 주어진 인코딩을 찾지 못하면 검색 함수는 None을 반환해야 합니다.

버전 3.9 변경: 하이픈과 공백이 밑줄로 변환됩니다.

codecs.unregister(search_function, /) — 코덱 검색 함수를 등록 해제하고 레지스트리 캐시를 비워요. 검색 함수가 등록돼 있지 않으면 아무 일도 하지 않습니다.

버전 3.10 추가.

인코딩된 텍스트 파일을 다룰 때는 내장 open()과 관련 io 모듈을 권장하지만, 이 모듈은 바이너리 파일에서 더 넓은 코덱 범위를 쓸 수 있게 하는 추가 유틸리티 함수·클래스도 제공해요.

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1) — 주어진 mode로 인코딩된 파일을 열고, 투명한 인코딩/디코딩을 제공하는 StreamReaderWriter 인스턴스를 반환해요. 기본 파일 모드는 읽기 모드인 'r'입니다.

참고: encoding이 None이 아니면 기본 인코딩 파일은 항상 바이너리 모드로 열려요. 읽기·쓰기에서 '\n'의 자동 변환은 일어나지 않습니다. mode 인자는 내장 open()이 허용하는 바이너리 모드면 되고, 'b'는 자동으로 추가됩니다.

encoding은 파일에 사용할 인코딩을 지정하고, 바이트로 인코딩·디코딩하는 모든 인코딩이 허용돼요. 파일 메서드가 지원하는 데이터 타입은 사용하는 코덱에 따라 다릅니다. errors는 오류 처리를 정의하며 기본값은 'strict'로 인코딩 오류 시 ValueError를 일으켜요. buffering은 내장 open()과 같은 의미로, 기본값 -1은 기본 버퍼 크기를 쓰게 합니다.

버전 3.11 변경: 'U' 모드가 제거되었어요. 버전 3.14부터 비권장: codecs.open()은 open()으로 대체되었습니다.

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict') — 투명한 트랜스코딩을 제공하는 file의 래핑 버전인 StreamRecoder 인스턴스를 반환해요. 래핑 버전이 닫히면 원본 파일도 닫힙니다. 래핑된 파일에 쓰는 데이터는 data_encoding에 따라 디코딩된 뒤 file_encoding으로 바이트로 원본 파일에 써지고, 원본 파일에서 읽은 바이트는 file_encoding에 따라 디코딩된 결과를 data_encoding으로 인코딩해요. file_encoding을 주지 않으면 data_encoding이 기본값입니다.

codecs.iterencode(iterator, encoding, errors='strict', **kwargs) — 증분 인코더를 사용해 iterator가 내놓는 입력을 반복적으로 인코딩해요. iterator는 str 객체를 내놓아야 하고, 이 함수는 제너레이터예요. errors 인자(및 다른 키워드 인자)는 증분 인코더로 전달됩니다. 이 함수는 코드가 텍스트 str 객체를 인코딩하길 요구하므로, base64_codec 같은 바이트→바이트 인코더는 지원하지 않아요.

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs) — 증분 디코더를 사용해 iterator가 내놓는 입력을 반복적으로 디코딩해요. iterator는 bytes 객체를 내놓아야 하고, 제너레이터예요. 이 함수는 코드가 bytes 객체를 디코딩하길 요구하므로 rot_13 같은 텍스트→텍스트 인코더는 지원하지 않지만, rot_13은 iterencode()와 동등하게 쓸 수 있어요.

codecs.readbuffer_encode(buffer, errors=None, /) — buffer(버퍼 호환 객체나 str, 처리가 전에 UTF-8로 인코딩됨)의 원시 바이트와 그 길이를 담은 튜플을 반환해요. errors 인자는 무시됩니다.

>>> codecs.readbuffer_encode(b"Zito")
(b'Zito', 4)

BOM 상수

codecs.BOM, BOM_BE, BOM_LE, BOM_UTF8, BOM_UTF16, BOM_UTF16_BE, BOM_UTF16_LE, BOM_UTF32, BOM_UTF32_BE, BOM_UTF32_LE

이 상수들은 여러 인코딩의 유니코드 BOM(바이트 순서 표시)인 다양한 바이트 시퀀스를 정의해요. UTF-16·UTF-32 데이터 스트림에서 바이트 순서를 나타내는 데 쓰이고, UTF-8에서는 유니코드 서명으로 쓰입니다. BOM_UTF16은 플랫폼의 네이티브 바이트 순서에 따라 BOM_UTF16_BE 또는 BOM_UTF16_LE이며, BOM은 BOM_UTF16의 별칭, BOM_LE는 BOM_UTF16_LE, BOM_BE는 BOM_UTF16_BE의 별칭이에요. 나머지는 UTF-8·UTF-32 인코딩의 BOM을 나타냅니다.

코덱 기본 클래스

codecs 모듈은 코덱 객체를 다루는 인터페이스를 정의하는 기본 클래스 집합을 제공해요. 커스텀 코덱 구현의 기반으로도 쓰입니다. 각 코덱은 Python에서 코덱으로 쓰이려면 네 가지 인터페이스(무상태 인코더, 무상태 디코더, 스트림 리더, 스트림 라이터)를 정의해야 해요. 스트림 리더·라이터는 보통 무상태 인코더/디코더를 재사용해 파일 프로토콜을 구현합니다. 코덱 작성자는 코덱이 인코딩·디코딩 오류를 어떻게 처리할지도 정의해야 해요.

오류 핸들러

오류 처리를 단순화하고 표준화하기 위해, 코덱은 errors 문자열 인자를 받아 다양한 오류 처리 방식을 구현할 수 있어요.

>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German ß, ♬'

모든 Python 표준 인코딩 코덱과 함께 쓸 수 있는 오류 핸들러:

값 의미
'strict' UnicodeError(또는 그 서브클래스)를 일으킴. 기본값. strict_errors()로 구현.
'ignore' 잘못된 데이터를 무시하고 계속 진행. ignore_errors()로 구현.
'replace' 대체 마커로 바꿈. 인코딩 시 ?(ASCII 문자), 디코딩 시 �(U+FFFD, 공식 REPLACEMENT CHARACTER). replace_errors()로 구현.
'backslashreplace' 백슬래시 이스케이프 시퀀스로 바꿈. 인코딩 시 유니코드 코드 포인트의 16진 형태(\xhh, \uxxxx, \Uxxxxxxxx), 디코딩 시 바이트 값의 16진 형태(\xhh). backslashreplace_errors()로 구현.
'surrogateescape' 디코딩 시 바이트를 U+DC80~U+DCFF 범위의 개별 서러게이트 코드로 바꿈. 이 코드는 나중에 데이터를 인코딩할 때 'surrogateescape' 오류 핸들러를 쓰면 같은 바이트로 되돌아갑니다. (자세한 건 PEP 383 참고)

다음 오류 핸들러는 인코딩(텍스트 인코딩 안에서)에만 적용돼요.

값 의미
'xmlcharrefreplace' XML/HTML 숫자 문자 참조(&#num; 형태)로 바꿈. xmlcharrefreplace_errors()로 구현.
'namereplace' \N{...} 이스케이프 시퀀스로 바꿈. 중괄호 안은 유니코드 문자 데이터베이스의 Name 속성이에요. namereplace_errors()로 구현.

다음 오류 핸들러는 특정 코덱 전용이에요.

값 코덱 의미
'surrogatepass' utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le 서러게이트 코드 포인트(U+D800~U+DFFF)를 일반 코드 포인트처럼 인코딩·디코딩 허용. 그 외에는 이 코덱들이 str의 서러게이트를 오류로 취급.

버전 3.1 추가: 'surrogateescape', 'surrogatepass' 오류 핸들러. 버전 3.4 변경: 'surrogatepass'가 utf-16*, utf-32* 코덱에서 동작. 버전 3.5 추가: 'namereplace' 오류 핸들러. 버전 3.5 변경: 'backslashreplace'가 디코딩·번역에서도 동작.

허용 값 집합은 새 이름이 붙은 오류 핸들러를 등록해 확장할 수 있어요.

codecs.register_error(name, error_handler, /) — name 이름으로 오류 처리 함수 error_handler를 등록해요. errors 매개변수로 name을 지정하면 인코딩·디코딩 중 오류 시 이 함수가 호출됩니다. 인코딩에서는 UnicodeEncodeError 인스턴스(오류 위치 정보 포함)와 함께 호출되고, 핸들러는 이(또는 다른) 예외를 일으키거나, 인코딩할 수 없는 부분의 대체물과 인코딩을 계속할 위치를 담은 튜플을 반환해야 해요. 대체물은 str이나 bytes일 수 있고, bytes면 단순히 출력 버퍼에 복사되며, 문자열이면 인코더가 대체물을 인코딩합니다. 음수 위치 값은 입력 문자열 끝 기준으로 취급되고, 결과 위치가 범위를 벗어나면 IndexError가 발생합니다. 디코딩·번역도 비슷하게 동작하되 UnicodeDecodeError/UnicodeTranslateError가 핸들러로 전달되고 핸들러의 대체물이 출력에 직접 들어가요.

이전에 등록된 오류 핸들러(표준 오류 핸들러 포함)는 이름으로 조회할 수 있어요.

codecs.lookup_error(name, /) — 이전에 name으로 등록된 오류 핸들러를 반환해요. 못 찾으면 LookupError.

다음 표준 오류 핸들러는 모듈 수준 함수로도 제공돼요.

  • codecs.strict_errors(exception) — 'strict' 처리 구현. 각 인코딩·디코딩 오류가 UnicodeError를 일으킵니다.
  • codecs.ignore_errors(exception) — 'ignore' 처리 구현. 잘못된 데이터를 무시하고 진행.
  • codecs.replace_errors(exception) — 'replace' 처리 구현. 인코딩 오류는 ?, 디코딩 오류는 �(U+FFFD)로 대체.
  • codecs.backslashreplace_errors(exception) — 'backslashreplace' 처리 구현. 잘못된 데이터를 백슬래시 이스케이프로 대체. 인코딩 시 \xhh/\uxxxx/\Uxxxxxxxx, 디코딩 시 \xhh.
  • codecs.xmlcharrefreplace_errors(exception) — 'xmlcharrefreplace' 처리 구현(텍스트 인코딩 내 인코딩 전용). 인코딩 불가 문자를 &#num; 형태의 XML/HTML 숫자 문자 참조로 대체.
  • codecs.namereplace_errors(exception) — 'namereplace' 처리 구현(텍스트 인코딩 내 인코딩 전용). 인코딩 불가 문자를 \N{...} 이스케이프로 대체. 독일어 소문자 'ß'는 \N{LATIN SMALL LETTER SHARP S}로 변환돼요.

무상태 인코딩·디코딩

기본 Codec 클래스는 무상태 인코더·디코더의 함수 인터페이스도 정의하는 다음 메서드들을 정의해요.

class codecs.Codec — 무상태 인코딩·디코딩을 위한 기본 메서드 집합.

증분 인코딩·디코딩

IncrementalEncoder와 IncrementalDecoder 클래스는 증분 인코딩·디코딩의 기본 인터페이스를 제공해요. 입력을 무상태 함수 한 번 호출로 처리하지 않고, 증분 인코더/디코더의 encode()/decode() 메서드를 여러 번 호출해 처리합니다. 증분 인코더/디코더는 메서드 호출 동안 인코딩·디코딩 진행 상태를 추적해요. encode()/decode() 호출의 이어 붙인 출력은 모든 개별 입력을 하나로 합쳐 무상태 인코더/디코더로 처리한 것과 같습니다.

class codecs.IncrementalEncoder(errors='strict') — 여러 단계로 입력을 인코딩하는 데 쓰는 클래스예요. 모든 증분 인코더는 이 생성자 인터페이스를 제공해야 하며, 추가 키워드 인자를 더할 수 있지만 Python 코덱 레지스트리가 쓰는 건 여기 정의된 것뿐이에요. errors 인자는 같은 이름의 속성에 할당되므로, 객체 수명 동안 이 속성을 바꿔 오류 처리 전략을 전환할 수 있어요.

class codecs.IncrementalDecoder(errors='strict') — 여러 단계로 입력을 디코딩하는 데 쓰는 클래스예요. IncrementalEncoder와 같은 규칙을 따릅니다.

스트림 인코딩·디코딩

StreamWriter와 StreamReader 클래스는 새 인코딩 서브모듈을 아주 쉽게 구현할 수 있는 일반 작업 인터페이스를 제공해요. 예시는 encodings.utf_8을 참고하세요.

class codecs.StreamWriter(stream, errors='strict') — Codec의 서브클래스예요. 모든 스트림 라이터는 이 생성자 인터페이스를 제공해야 해요. stream 인자는 특정 코드에 적합하게 텍스트 또는 바이너리 데이터를 쓰기 위해 연 파일류 객체여야 해요. errors 인자는 같은 이름 속성에 할당됩니다. 위 메서드 외에도 스트림 라이터는 기본 스트림의 다른 메서드·속성을 모두 상속해야 해요.

class codecs.StreamReader(stream, errors='strict') — Codec의 서브클래스예요. 모든 스트림 리더는 이 생성자 인터페이스를 제공해야 해요. stream 인자는 특정 코드에 적합하게 텍스트 또는 바이너리 데이터를 읽기 위해 연 파일류 객체여야 해요. errors 인자의 허용 값 집합은 register_error()로 확장할 수 있어요.

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict') — 읽기·쓰기 모드 모두에서 동작하는 스트림을 감싸는 편의 클래스예요. stream은 파일류 객체여야 하고, Reader/Writer는 각각 StreamReader/StreamWriter 인터페이스를 제공하는 팩토리 함수나 클래스여야 해요. 인스턴스는 StreamReader와 StreamWriter 클래스의 결합 인터페이스를 정의하며 기본 스트림의 나머지 메서드·속성을 상속합니다.

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict') — 한 인코딩에서 다른 인코딩으로 데이터를 번역해요(다른 인코딩 환경을 다룰 때 유용). 양방향 변환을 구현해요. encode/decode는 프런트엔드(즉 read()/write()를 호출하는 코드가 보는 데이터)에서 동작하고, Reader/Writer는 백엔드(즉 stream의 데이터)에서 동작합니다. 예를 들어 Latin-1→UTF-8 및 역방향의 투명 트랜스코딩에 쓸 수 있어요.

인코딩과 유니코드

문자열은 내부적으로 U+0000~U+10FFFF 범위의 코드 포인트 시퀀스로 저장돼요. (구현 상세는 PEP 393 참고) 문자열 객체가 CPU·메모리 밖에서 쓰이면 엔디언과 이 배열이 바이트로 저장되는 방식이 문제가 됩니다. 다른 코덱처럼 문자열을 바이트 시퀀스로 직렬화하는 것을 인코딩, 바이트 시퀀스에서 문자열을 다시 만드는 것을 디코딩이라고 해요. 다양한 텍스트 직렬화 코덱이 있는데, 이를 통틀어 텍스트 인코딩이라 부릅니다.

가장 단순한 텍스트 인코딩('latin-1' 또는 'iso-8859-1')은 코드 포인트 0255를 바이트 0x00xff로 매핑해요. 즉 U+00FF 위의 코드 포인트를 가진 문자열은 이 코덱으로 인코딩할 수 없어요. 그렇게 하면 이런 모습의 UnicodeEncodeError가 나옵니다(오류 메시지 세부는 다를 수 있어요): UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' in position 3: ordinal not in range(256).

또 다른 인코딩 그룹(소위 charmap 인코딩)은 전체 유니코드 코드 포인트에서 다른 부분집합을 고르고, 이 코드 포인트들을 바이트 0x0~0xff에 매핑해요. 예컨대 encodings/cp1252.py(주로 Windows에서 쓰는 인코딩)를 열어 보면, 어떤 문자가 어떤 바이트 값에 매핑되는지 보여 주는 256자짜리 문자열 상수가 있어요.

이 모든 인코딩은 유니코드에 정의된 1114112개 코드 포인트 중 256개만 인코딩할 수 있어요. 모든 유니코드 코드 포인트를 저장하는 간단한 방법은 각 코드 포인트를 연속된 4바이트로 저장하는 거예요. 빅 엔디언 또는 리틀 엔디언 순서 두 가지가 있는데, 이 두 인코딩을 각각 UTF-32-BE, UTF-32-LE라고 해요. 단점은 예를 들어 리틀 엔디언 머신에서 UTF-32-BE를 쓰면 인코딩·디코딩 때마다 바이트를 스왑해야 한다는 거예요. Python의 UTF-16·UTF-32 코덱은 BOM이 없을 때 플랫폼의 네이티브 바이트 순서를 사용해 이 문제를 피합니다. 바이트 순서를 감지하려면 BOM("Byte Order Mark")을 쓰는데, 이것이 유니코드 문자 U+FEFF예요. 이 문자는 모든 UTF-16·UTF-32 바이트 시퀀스 앞에 붙일 수 있고, 바이트 스왑된 버전(0xFFFE)은 유니코드 텍스트에 나타나선 안 되는 불법 문자입니다. UTF-16·UTF-32 시퀀스의 첫 문자가 U+FFFE면 디코딩 시 바이트를 스왑해야 해요.

안타깝게도 U+FEFF는 ZERO WIDTH NO-BREAK SPACE(폭이 없고 단어 분리를 허용하지 않는 문자)라는 두 번째 용도도 있었어요. 유니코드 4.0에서 U+FEFF를 ZERO WIDTH NO-BREAK SPACE로 쓰는 건 비권장됐고(U+2060, WORD JOINER가 그 역할), 그래도 유니코드 소프트웨어는 여전히 U+FEFF를 BOM(인코딩된 바이트의 저장 배치를 정하는 장치)과 ZERO WIDTH NO-BREAK SPACE(일반 문자) 두 역할 모두로 처리할 수 있어야 해요.

유니코드 문자 전체 범위를 인코딩할 수 있는 또 다른 인코딩이 UTF-8이에요. UTF-8은 8비트 인코딩이라 바이트 순서 문제가 없어요. 각 바이트는 마커 비트(최상위 비트)와 페이로드 비트로 구성됩니다. 마커 비트는 0~4개의 1 비트 다음에 0 비트가 오는 시퀀스예요.

범위 인코딩
U-00000000 … U-0000007F 0xxxxxxx
U-00000080 … U-000007FF 110xxxxx 10xxxxxx
U-00000800 … U-0000FFFF 1110xxxx 10xxxxxx 10xxxxxx
U-00010000 … U-0010FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

유니코드 문자의 최하위 비트가 가장 오른쪽의 x 비트예요. UTF-8은 8비트 인코딩이라 BOM이 필요 없고, 디코딩된 문자열의 어떤 U+FEFF 문자(첫 문자라도)도 ZERO WIDTH NO-BREAK SPACE로 취급됩니다.

외부 정보 없이는 문자열 인코딩에 어떤 인코딩이 쓰였는지 확실히 알 수 없어요. 각 charmap 인코딩은 임의 바이트 시퀀스를 디코딩할 수 있는 반면, UTF-8 바이트 시퀀스는 구조가 있어 임의 시퀀스를 허용하지 않아요. UTF-8 인코딩 감지 신뢰성을 높이기 위해 마이크로소프트는 메모장(Notepad)용으로 UTF-8 변형(Python이 "utf-8-sig"라고 부름)을 만들었어요. Unicode 문자를 파일에 쓰기 전에 UTF-8 인코딩된 BOM(바이트 시퀀스로 0xef, 0xbb, 0xbf)이 먼저 쓰입니다. charmap 인코딩 파일이 이 바이트 값들로 시작할 확률은 낮으므로, utf-8-sig 인코딩을 바이트 시퀀스에서 정확히 추측할 가능성이 높아져요. 여기서 BOM은 바이트 순서 결정이 아니라 인코딩 추측을 돕는 서명으로 쓰이는 거죠. 인코딩 시 utf-8-sig 코덱은 처음 세 바이트로 0xef, 0xbb, 0xbf를 쓰고, 디코딩 시 파일의 처음 세 바이트로 나타나면 그 세 바이트를 건너뜁니다. UTF-8에서는 BOM 사용이 권장되지 않으므로 일반적으로 피해야 해요.

표준 인코딩

Python에는 C 함수나 매핑 테이블 딕셔너리로 구현된 코덱이 여러 개 내장돼 있어요. 아래 표는 이름과 몇몇 흔한 별칭, 그리고 해당 인코딩이 쓰일 가능성이 큰 언어를 나열해요. 별칭 목록도 언어 목록도 완전하진 않습니다. 대소문자만 다르거나 밑줄 대신 하이픈을 쓰는 철자 변형도 normalize_encoding()으로 정규화하면 동일하므로 유효한 별칭이에요. 예를 들어 'utf-8'은 'utf_8' 코덱의 유효한 별칭입니다.

참고: 아래 표는 가장 흔한 별칭만 나열해요. 전체 목록은 소스 aliases.py 파일을 참고하세요. Windows에서는 cpXXX 코덱이 모든 코드 페이지에 쓰이고, 다른 플랫폼에서는 아래 표의 코덱만 존재함이 보장됩니다.

주요 코덱과 별칭·언어 예시:

  • ascii (646, us-ascii) — 영어
  • big5 (big5-tw, csbig5) — 번체 중국어
  • cp437 (437, IBM437) — 영어
  • cp932 (932, ms932, mskanji, ms-kanji, windows-31j) — 일본어
  • cp949 (949, ms949, uhc) — 한국어
  • cp1252 (windows-1252) — 서유럽
  • cp1251 (windows-1251) — 벨라루스어·불가리아어·마케도니아어·러시아어·세르비아어
  • euc_jp (eucjp, ujis, u-jis) — 일본어
  • euc_kr (euckr, korean, ksc5601, ks_c-5601, ...) — 한국어
  • gb2312 (chinese, csiso58gb231280, euc-cn, ...) — 간체 중국어
  • gbk (936, cp936, ms936) — 통합 중국어
  • gb18030 (gb18030-2000) — 통합 중국어
  • iso2022_jp (csiso2022jp, iso2022jp, iso-2022-jp) — 일본어
  • iso2022_kr (csiso2022kr, iso2022kr, iso-2022-kr) — 한국어
  • latin_1 (iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1) — 서유럽
  • shift_jis (csshiftjis, shiftjis, sjis, s_jis) — 일본어
  • utf_32 (U32, utf32), utf_16 (U16, utf16), utf_7 (U7, unicode-1-1-utf-7), utf_8 (U8, UTF, utf8, cp65001) — 모든 언어

(그 밖에 cp037, cp273, cp424, cp500, cp720, cp737, cp775, cp850, cp852, cp855, cp856, cp857, cp858, cp860, cp861, cp862, cp863, cp864, cp865, cp866, cp869, cp874, cp875, cp950, cp1006, cp1026, cp1125, cp1140, cp1250, cp1253, cp1254, cp1255, cp1256, cp1257, cp1258, euc_jis_2004, euc_jisx0213, hz, iso2022_jp_1/2/3/2004/ext, iso8859_2~16, johab, koi8_r/t/u, kz1048, mac_cyrillic/greek/iceland/latin2/roman/turkish, ptcp154, shift_jis_2004, shift_jisx0213, utf_32_be/le, utf_16_be/le, utf_8_sig 등 다양한 언어별 코드 페이지·인코딩이 표준 목록에 포함돼 있어요.)

버전 3.4 변경: utf-16*·utf-32* 인코더가 더 이상 서러게이트 코드 포인트(U+D800~U+DFFF)를 인코딩하지 않고, utf-32* 디코더가 서러게이트에 해당하는 바이트 시퀀스를 디코딩하지 않습니다. 버전 3.8 변경: cp65001이 이제 utf_8의 별칭. 버전 3.14 변경: Windows에서 cpXXX 코덱이 모든 코드 페이지에 사용 가능.

Python 특정 인코딩

Python 고유의 미리 정의된 코덱들도 있어요. 코덱 이름이 Python 밖에선 의미가 없어요.

텍스트 인코딩

str→bytes 인코딩과 bytes류 객체→str 디코딩을 제공해요.

  • idna — RFC 3490 구현. errors='strict'만 지원.
  • mbcs (ansi, dbcs) — Windows 전용. ANSI 코드 페이지(CP_ACP)에 따라 피연산자를 인코딩.
  • oem — Windows 전용. OEM 코드 페이지(CP_OEMCP)에 따라 인코딩. (3.6 추가)
  • palmos — PalmOS 3.5 인코딩.
  • punycode — RFC 3492 구현. 상태 유지 코덱 미지원. 디코딩·인코딩 알고리즘이 확장성이 낮으니 신뢰할 수 없는 입력 길이를 제한하세요.
  • raw_unicode_escape — 다른 코드 포인트는 \uXXXX/\UXXXXXXXX를 쓰는 Latin-1 인코딩. 기존 백슬래시는 이스케이프하지 않아요. Python pickle 프로토콜에서 사용.
  • undefined — 테스트용으로만. 모든 변환(빈 문자열 포함)에서 예외 발생, 오류 핸들러 무시.
  • unicode_escape — ASCII 인코딩 Python 소스의 유니코드 리터럴 내용으로 적합한 인코딩(단 따옴표는 이스케이프하지 않음). Latin-1 소스에서 디코딩. Python 소스는 기본적으로 실제로 UTF-8을 쓰니 주의하세요.

버전 3.8 변경: "unicode_internal" 코덱 제거.

바이너리 변환

bytes류 객체→bytes 매핑을 제공해요. bytes.decode()(str 출력만 생성)에선 지원되지 않습니다.

코덱 별칭 의미
base64_codec base64, base_64 피연산자를 여러 줄 MIME base64로 변환(결과에 항상 끝 '\n' 포함). base64.encodebytes()/base64.decodebytes()
bz2_codec bz2 피연산자를 bz2로 압축. bz2.compress()/bz2.decompress()
hex_codec hex 피연산자를 바이트당 두 자리 16진 표현으로 변환. binascii.b2a_hex()/binascii.a2b_hex()
quopri_codec quopri, quotedprintable, quoted_printable 피연산자를 MIME quoted printable로 변환. quopri.encode()(quotetabs=True)/quopri.decode()
uu_codec uu 피연산자를 uuencode로 변환.
zlib_codec zip, zlib 피연산자를 gzip으로 압축. zlib.compress()/zlib.decompress()

버전 3.2 추가: 바이너리 변환 복원. 버전 3.4 변경: 바이너리 변환 별칭 복원.

독립 코덱 함수

코덱과 유사한 인코딩·디코딩 기능을 제공하지만, codecs.encode()/codecs.decode()를 통한 이름 붙은 코덱으로는 쓸 수 없는 함수들이에요. 내부적으로(예: pickle이) 사용하고, Python 3에서 제거된 string_escape 코덱처럼 동작합니다.

codecs.escape_encode(input, errors=None) — 이스케이프 시퀀스로 input을 인코딩해요. repr()이 bytes에 대해 이스케이프된 바이트 값을 만드는 방식과 유사해요. input은 bytes 객체여야 하고, (output, length) 튜플(output은 bytes 객체, length는 소비된 바이트 수)을 반환합니다.

codecs.escape_decode(input, errors=None) — 이스케이프 시퀀스에서 원래 바이트로 input을 디코딩해요. input은 bytes류 객체여야 하고, (output, length) 튜플을 반환합니다.

텍스트 변환

rot_13 (rot13) — 피연산자의 Caesar 암호 암호화를 반환하는 str→str 매핑. str.encode()(bytes 출력만 생성)에선 지원되지 않습니다.

버전 3.2 추가: rot_13 텍스트 변환 복원. 버전 3.4 변경: rot13 별칭 복원.

encodings — 인코딩 패키지

encodings.normalize_encoding(encoding) — 인코딩 이름 encoding을 정규화해요. Python 패키지 이름에 쓰는 점을 제외한 모든 영숫자가 아닌 문자를 접어 하나의 밑줄로 바꾸고, 앞·뒤 밑줄을 제거해요. 예: ' -;#' → '_'. encoding은 ASCII만 사용해야 해요.

참고: 다음 함수들은 테스트 목적 외에는 직접 쓰지 말고 codecs.lookup()을 사용하세요.

encodings.search_function(encoding) — 주어진 인코딩 이름에 해당하는 코덱 모듈을 찾아요. 먼저 normalize_encoding()으로 정규화한 뒤 해당 별칭을 찾고, 별칭이나 정규화된 이름으로 encodings 패키지에서 코덱 모듈을 import하려 시도해요. 모듈을 찾아 codecs.CodecInfo 객체를 반환하는 유효한 getregentry() 함수를 정의하면 코덱을 캐시하고 반환합니다. 코덱 모듈이 getaliases() 함수를 정의하면 반환된 별칭들을 미래 사용을 위해 등록해요.

encodings.win32_code_page_search_function(encoding) — cpXXXX 형태의 Windows 코드 페이지 인코딩을 찾아요. 코드 페이지가 유효하고 지원되면 codecs.CodecInfo 객체를 반환합니다. (Windows 전용, 3.14 추가)

exception encodings.CodecRegistryError — 코덱이 유효하지 않거나 호환되지 않을 때 발생해요.

encodings.idna — 애플리케이션의 국제화 도메인 이름

이 모듈은 RFC 3490(애플리케이션의 국제화 도메인 이름)과 RFC 3492(Nameprep)를 구현해요. punycode 인코딩과 stringprep을 기반으로 합니다. RFC 5891·RFC 5895의 IDNA 2008 표준이 필요하면 서드파티 idna 모듈을 쓰세요.

이 RFC들은 함께 도메인 이름에서 비ASCII 문자를 지원하는 프로토콜을 정의해요. 비ASCII 문자를 포함한 도메인 이름(예: www.Alliancefrançaise.nu)은 ASCII 호환 인코딩(ACE, 예: www.xn--alliancefranaise-npb.nu)으로 변환됩니다. 도메인 이름의 ACE 형태는 DNS 쿼리, HTTP Host 필드처럼 임의 문자를 허용하지 않는 모든 곳에서 쓰여요. 이 변환은 애플리케이션 안에서, 가능하면 사용자에게 보이지 않게 수행돼요. 애플리케이션은 유니코드 도메인 레이블을 와이어에서 IDNA로 투명하게 변환하고, 사용자에게 보여 주기 전에 ACE 레이블을 다시 유니코드로 변환해야 해요.

Python은 이 변환을 여러 방식으로 지원해요. idna 코덱은 유니코드와 ACE 사이를 변환하고, RFC 3490 섹션 3.1의 구분 문자로 입력 문자열을 레이블로 나눈 뒤 각 레이블을 필요에 따라 ACE로 변환합니다. 또한 socket 모듈이 유니코드 호스트 이름을 투명하게 ACE로 변환하므로, 애플리케이션은 호스트 이름을 소켓 모듈에 넘길 때 직접 변환할 걱정이 없어요. 거기에 더해 http.client, ftplib처럼 호스트 이름을 함수 매개변수로 받는 모듈들은 유니코드 호스트 이름을 받아들입니다(http.client는 Host 필드를 보낼 때 그 안에 IDNA 호스트 이름을 투명하게 보내요). 와이어에서 호스트 이름을 받을 때(역방향 이름 조회 등)는 유니코드로의 자동 변환이 수행되지 않으니, 사용자에게 보여 주려면 직접 디코딩해야 해요.

이 모듈은 국제 도메인 이름의 대소문자 무감도를 얻고 유사 문자를 통일하기 위해 호스트 이름에 특정 정규화를 수행하는 nameprep 절차도 구현해요. 원하면 nameprep 함수를 직접 쓸 수도 있어요.

  • encodings.idna.nameprep(label) — label의 nameprep 버전을 반환. 현재 구현은 쿼리 문자열을 가정하므로 AllowUnassigned가 참.
  • encodings.idna.ToASCII(label) — RFC 3490에 따라 레이블을 ASCII로 변환. UseSTD3ASCIIRules는 거짓으로 가정.
  • encodings.idna.ToUnicode(label) — RFC 3490에 따라 레이블을 유니코드로 변환.

encodings.mbcs — Windows ANSI 코드 페이지

ANSI 코드 페이지(CP_ACP)를 구현해요. (Windows 전용)

버전 3.2 변경: 3.2 이전엔 errors 인자가 무시되고 인코딩에는 항상 'replace', 디코딩에는 'ignore'가 쓰였어요. 버전 3.3 변경: 모든 오류 핸들러를 지원.

encodings.utf_8_sig — BOM 서명이 있는 UTF-8 코덱

UTF-8 코덱의 변형을 구현해요. 인코딩 시 UTF-8 인코딩된 BOM이 UTF-8 인코딩된 바이트 앞에 붙어요. 상태 유지 인코더의 경우 이는 한 번만(바이트 스트림에 처음 쓸 때) 수행됩니다. 디코딩 시 데이터 시작의 선택적 UTF-8 인코딩 BOM은 건너뜁니다.

더 알아보기