# `email.charset`: 문자 집합 표현

소스 코드: Lib/email/charset.py

이 모듈은 레거시 (`Compat32`) 이메일 API의 일부입니다. 새 API에서는 별칭 표만 사용됩니다.

이 섹션의 나머지 텍스트는 모듈의 원본 설명서입니다.

이 모듈은 문자 집합 레지스트리와 이 레지스트리를 조작하기 위한 몇 가지 편의 메서드뿐만 아니라, 이메일 메시지의 문자 집합과 문자 집합 변환을 나타내는 `Charset` 클래스를 제공합니다. `Charset` 인스턴스는 `email` 패키지 내의 다른 여러 모듈에서 사용됩니다.

`email.charset` 모듈에서 이 클래스를 임포트 하십시오.

class `email.charset.``Charset`(input_charset=DEFAULT_CHARSET)

  문자 집합을 이메일 속성으로 매핑합니다.

  이 클래스는 특정 문자 집합에 대해 이메일에 요구되는 요구 사항에 대한 정보를 제공합니다. 또한 해당 코덱을 사용할 수 있으면, 문자 집합 간 변환을 위한 편의 루틴을 제공합니다. 문자 집합이 주어지면, RFC 호환 방식으로 이메일 메시지에서 해당 문자 집합을 사용하는 방법에 대한 정보를 제공하는 데 최선을 다합니다.

  이메일 헤더나 본문에 사용될 때 특정 문자 집합은 quoted-printable이나 base64로 인코딩해야 합니다. 특정 문자 집합은 완전히 변환해야 하며, 이메일에서는 허용되지 않습니다.

  선택적 input_charset은 아래에 설명된 것과 같습니다; 항상 소문자로 강제 변환됩니다. 별칭이 정규화된 후에는 문자 집합 레지스트리에서 조회로 사용되어 문자 집합을 위해 사용할 헤더 인코딩, 본문 인코딩 및 출력 변환 코덱을 찾습니다. 예를 들어, input_charset이 `iso-8859-1`이면, 헤더와 본문은 quoted-printable을 사용하여 인코딩되며 출력 변환 코덱은 필요하지 않습니다. input_charset이 `euc-jp`면, 헤더는 base64로 인코딩되고, 본문은 인코딩되지 않지만, 출력 텍스트는 `euc-jp` 문자 집합에서 `iso-2022-jp` 문자 집합으로 변환됩니다.

  `Charset` 인스턴스에는 다음과 같은 데이터 어트리뷰트가 있습니다:

  `input_charset`

    지정된 초기 문자 집합. 일반적인 별칭은 공식 이메일 이름으로 변환됩니다 (예를 들어 `latin_1`은 `iso-8859-1`로 변환됩니다). 기본값은 7비트 `us-ascii`입니다.

  `header_encoding`

    If the character set must be encoded before it can be used in an email header, this attribute will be set to `charset.QP` (for quoted-printable), `charset.BASE64` (for base64 encoding), or `charset.SHORTEST` for the shortest of QP or BASE64 encoding. Otherwise, it will be `None`.

  `body_encoding`

    Same as header_encoding, but describes the encoding for the mail message’s body, which indeed may be different than the header encoding. `charset.SHORTEST` is not allowed for body_encoding.

  `output_charset`

    일부 문자 집합은 이메일 헤더나 본문에 사용하기 전에 변환해야 합니다. input_charset이 그중 하나이면, 이 어트리뷰트에는 출력이 변환될 문자 집합의 이름이 포함됩니다. 그렇지 않으면 `None`이 됩니다.

  `input_codec`

    input_charset을 유니코드로 변환하는 데 사용되는 파이썬 코덱의 이름. 변환 코덱이 필요하지 않으면, 이 어트리뷰트는 `None`입니다.

  `output_codec`

    유니코드를 output_charset으로 변환하는 데 사용되는 파이썬 코덱의 이름. 변환 코덱이 필요하지 않으면, 이 어트리뷰트의 값은 input_codec과 같습니다.

  `Charset` 인스턴스에는 다음과 같은 메서드도 있습니다:

  `get_body_encoding`()

    본문 인코딩에 사용된 콘텐츠 전송 인코딩(content transfer encoding)을 반환합니다.

    사용된 인코딩에 따라 문자열 `quoted-printable`이나 `base64`입니다. 또는 함수일 수 있는데, 이때는 인코딩되는 Message 객체를 단일 인자로 함수를 호출해야 합니다. 그러면 함수는 Content-Transfer-Encoding 헤더 자체를 적절한 것으로 설정해야 합니다.

    body_encoding이 `QP`이면 문자열 `quoted-printable`을 반환하고, body_encoding이 `BASE64`이면 문자열 `base64`를 반환하고, 그렇지 않으면 문자열 `7bit`를 반환합니다.

  `get_output_charset`()

    출력 문자 집합을 반환합니다.

    `None`이 아니라면 output_charset 어트리뷰트이고, 그렇지 않으면 input_charset입니다.

  `header_encode`(string)

    문자열 string을 헤더 인코딩합니다.

    인코딩 유형(base64나 quoted-printable)은 header_encoding 어트리뷰트를 기반으로 합니다.

  `header_encode_lines`(string, maxlengths)

    string을 먼저 바이트열로 변환하여 헤더 인코딩합니다.

    이는 문자열이 인자 maxlengths에 의해 주어진 최대 줄 길이에 맞춰진다는 점을 제외하고는 `header_encode()`와 유사합니다. maxlengths는 이터레이터여야 합니다: 이 이터레이터에서 반환된 각 요소는 다음 최대 줄 길이를 제공합니다.

  `body_encode`(string)

    문자열 string을 본문 인코딩합니다.

    인코딩 유형(base64나 quoted-printable)은 body_encoding 어트리뷰트를 기반으로 합니다.

  `Charset` 클래스는 표준 연산과 내장 함수를 지원하는 여러 가지 메서드도 제공합니다.

  `__str__`()

    input_charset을 소문자로 강제 변환된 문자열로 반환합니다. `__repr__()`은 `__str__()`의 별칭입니다.

  `__eq__`(other)

    이 메서드를 사용하면 두 개의 `Charset` 인스턴스가 같은지 비교할 수 있습니다.

  `__ne__`(other)

    이 메서드를 사용하면 두 `Charset` 인스턴스가 다른지 비교할 수 있습니다.

`email.charset` 모듈은 또한 전역 문자 집합, 별명 및 코덱 레지스트리에 새 항목을 추가하기 위해 다음 함수를 제공합니다:

`email.charset.``add_charset`(charset, header_enc=None, body_enc=None, output_charset=None)

  전역 레지스트리에 문자 속성을 추가합니다.

  charset은 입력 문자 집합이며, 문자 집합의 규범적 이름이어야 합니다.

  Optional header_enc and body_enc is either `charset.QP` for quoted-printable, `charset.BASE64` for base64 encoding, `charset.SHORTEST` for the shortest of quoted-printable or base64 encoding, or `None` for no encoding. `SHORTEST` is only valid for header_enc. The default is `None` for no encoding.

  선택적 output_charset은 출력에 적용되어야 하는 문자 집합입니다. `Charset.convert()` 메서드가 호출될 때 입력 문자 집합에서 유니코드로, 다시 출력 문자 집합으로 변환이 진행됩니다. 기본값은 입력과 같은 문자 집합으로 출력하는 것입니다.

  input_charset과 output_charset은 모두 모듈의 문자 집합에서 코덱으로의 매핑에 유니코드 코덱 항목이 있어야 합니다; `add_codec()`을 사용하여 모듈이 모르는 코덱을 추가하십시오. 자세한 내용은 `codecs` 모듈 설명서를 참조하십시오.

  전역 문자 집합 레지스트리는 모듈 전역 딕셔너리 `CHARSETS`에 유지됩니다.

`email.charset.``add_alias`(alias, canonical)

  문자 집합 별칭을 추가합니다. alias는 별칭 이름입니다, 예를 들어 `latin-1`. canonical은 문자 집합의 규범적 이름입니다, 예를 들어 `iso-8859-1`.

  전역 문자 집합 별칭 레지스트리는 모듈 전역 딕셔너리 `ALIASES`에 유지됩니다.

`email.charset.``add_codec`(charset, codecname)

  주어진 문자 집합의 문자를 유니코드와 매핑하는 코덱을 추가합니다.

  charset은 문자 집합의 규범적 이름입니다. codecname은 `str`의 `encode()` 메서드의 두 번째 인자에 적합한 파이썬 코덱의 이름입니다.