"email.header": 국제화된 헤더
*****************************

**소스 코드:** Lib/email/header.py

======================================================================

이 모듈은 레거시 ("Compat32") 이메일 API의 일부입니다. 현재 API에서 헤
더의 인코딩과 디코딩은 "EmailMessage" 클래스의 딕셔너리와 유사한 API에
의해 투명하게 처리됩니다. 레거시 코드에서 사용하는 것 외에도, 이 모듈
은 헤더를 인코딩할 때 사용되는 문자 집합을 완전히 제어해야 하는 응용
프로그램에서 유용할 수 있습니다.

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

**RFC 2822**는 이메일 메시지 형식을 기술하는 기본 표준입니다. 대부분의
이메일이 ASCII 문자로만 구성된 당시에 널리 사용된 이전 **RFC 822** 표
준에서 파생됩니다. **RFC 2822**는 이메일에 7비트 ASCII 문자만 포함되어
있다고 가정한 명세입니다.

물론, 이메일이 전 세계에 배포되면서, 국제화되어 언어별 문자 집합을 이
메일 메시지에 사용할 수 있게 되었습니다. 기본 표준에서는 여전히 7비트
ASCII 문자만 사용하여 이메일 메시지를 전송해야 하므로, ASCII가 아닌 문
자가 포함된 이메일을 **RFC 2822** 호환 형식으로 인코딩하는 방법을 설명
하는 많은 RFC가 작성되었습니다. 이러한 RFC에는 **RFC 2045**, **RFC
2046**, **RFC 2047** 및 **RFC 2231**이 포함됩니다. "email" 패키지는
"email.header"와 "email.charset" 모듈에서 이러한 표준을 지원합니다.

이메일 헤더에 ASCII가 아닌 문자를 포함 시키려면 (가령 *Subject*나 *To*
필드에), "Header" 클래스를 사용하고 헤더 값에 문자열을 사용하는 대신
"Message" 객체의 필드를 "Header" 인스턴스로 대입해야 합니다.
"email.header" 모듈에서 "Header" 클래스를 임포트 합니다. 예를 들면:

   >>> from email.message import Message
   >>> from email.header import Header
   >>> msg = Message()
   >>> h = Header('p\xf6stal', 'iso-8859-1')
   >>> msg['Subject'] = h
   >>> msg.as_string()
   'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

*Subject* 필드에 비 ASCII 문자를 포함하기 위해 어떻게 했는지 아시겠습
니까? 우리는 "Header" 인스턴스를 만들고 바이트 문자열이 인코딩된 문자
집합을 전달하여 이를 수행했습니다. 뒤에 "Message" 인스턴스가 평탄화될
때, *Subject* 필드는 올바르게 **RFC 2047** 인코딩되었습니다. MIME 인식
메일 리더는 내장된 ISO-8859-1 문자를 사용하여 이 헤더를 표시하게 됩니
다.

"Header" 클래스 설명은 다음과 같습니다:

class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

   다른 문자 집합의 문자열을 포함할 수 있는 MIME 호환 헤더를 만듭니다.

   선택적 *s*는 초기 헤더 값입니다. "None"(기본값)이면, 초기 헤더 값이
   설정되지 않습니다. 나중에 "append()" 메서드 호출로 헤더에 추가할 수
   있습니다. *s*는 "bytes"나 "str"의 인스턴스일 수 있지만, 의미에 대해
   서는 "append()" 설명서를 참조하십시오.

   선택적 *charset*은 두 가지 용도로 사용됩니다: "append()" 메서드에
   대한 *charset* 인자와 같은 의미입니다. 또한, *charset* 인자를 생략
   하는 모든 후속 "append()" 호출에 대한 기본 문자 집합을 설정합니다.
   *charset*이 생성자에 제공되지 않으면 (기본값), "us-ascii" 문자 집합
   이 *s*의 초기 문자 집합과 후속 "append()" 호출의 기본값으로 사용됩
   니다.

   최대 줄 길이는 *maxlinelen*을 통해 명시적으로 지정할 수 있습니다.
   (*s*에 포함되지 않은 필드 헤더를 고려하기 위해, 예를 들어
   *Subject*) 첫 번째 줄을 더 짧은 값으로 분할하려면 *header_name*에
   필드 이름을 전달하십시오. 기본 *maxlinelen*은 78이고, *header_name*
   의 기본값은 "None"입니다, 이는 긴 분할 헤더의 첫 번째 줄을 고려하지
   않음을 의미합니다.

   선택적인 *continuation_ws*는 **RFC 2822** 호환 접는 공백(folding
   whitespace)이어야하며, 일반적으로 스페이스나 하드 탭 문자입니다. 이
   문자는 연속 줄 앞에 추가됩니다. *continuation_ws*는 기본적으로 단일
   스페이스 문자입니다.

   선택적 *errors*는 "append()" 메서드로 바로 전달됩니다.

   append(s, charset=None, errors='strict')

      문자열 *s*를 MIME 헤더에 추가합니다.

      선택적인 *charset*(제공되면)은 "Charset" 인스턴스
      ("email.charset"을 참조하십시오)나 문자 집합의 이름이어야 하며,
      이는 "Charset" 인스턴스로 변환됩니다. "None"(기본값) 값은 생성자
      에 지정된 *charset*이 사용됨을 의미합니다.

      *s*는 "bytes"나 "str"의 인스턴스일 수 있습니다. "bytes"의 인스턴
      스이면, *charset*은 해당 바이트 문자열의 인코딩이며, 문자열을 해
      당 문자 집합으로 디코딩할 수 없으면 "UnicodeError"가 발생합니다.

      *s*가 "str"의 인스턴스이면, *charset*은 문자열에 있는 문자의 문
      자 집합을 지정하는 힌트입니다.

      두 경우 모두, **RFC 2047** 규칙을 사용하여 **RFC 2822** 호환 헤
      더를 생성할 때, 문자열은 charset의 출력 코덱을 사용하여 인코딩됩
      니다. 출력 코덱을 사용하여 문자열을 인코딩할 수 없으면
      UnicodeError가 발생합니다.

      선택적 *errors*는 *s*가 바이트 문자열일 때 decode 호출에 errors
      인자로 전달됩니다.

   encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

      메시지 헤더를 RFC 호환 형식으로 인코딩합니다. 긴 줄을 래핑하고
      비 ASCII 부분을 base64나 quoted-printable 인코딩으로 캡슐화할 수
      있습니다.

      선택적 *splitchars*는 일반 헤더 래핑 중 분할 알고리즘에 의해 추
      가 가중치를 받아야 하는 문자를 포함하는 문자열입니다. 이것은
      **RFC 2822**의 '높은 수준의 구문 분할'을 아주 거칠게 지원합니다:
      분할 문자 뒤에 오는 분리 점이 줄 분할 중에 선호되며, 문자열에 나
      타나는 순서대로 문자가 선호됩니다. 스페이스와 탭이 문자열에 포함
      되어 다른 분할 문자가 분할되는 줄에 나타나지 않을 때 분할 지점으
      로 어느 것을 선호해야 하는지를 나타낼 수 있습니다. Splitchars는
      **RFC 2047** 인코딩 된 줄에 영향을 미치지 않습니다.

      주어지면, *maxlinelen*은 최대 줄 길이에 대한 인스턴스의 값을 대
      체합니다.

      *linesep*은 접힌 헤더의 줄을 구분하는 데 사용되는 문자를 지정합
      니다. 기본적으로 파이썬 응용 프로그램 코드에 가장 유용한 값이지
      만 ("\n"), RFC 호환 줄 구분자로 헤더를 생성하기 위해 "\r\n"을 지
      정할 수 있습니다.

      버전 3.2에서 변경: *linesep* 인자를 추가했습니다.

   "Header" 클래스는 표준 연산자와 내장 함수를 지원하기 위한 많은 메서
   드도 제공합니다.

   __str__()

      무제한 줄 길이를 사용하여, "Header"의 근삿값을 문자열로 반환합니
      다. 모든 조각은 지정된 인코딩을 사용하여 유니코드로 변환되고 적
      절하게 결합합니다. 문자 집합이 "'unknown-8bit'" 인 조각은
      "'replace'" 에러 처리기를 사용하여 ASCII로 디코딩됩니다.

      버전 3.2에서 변경: "'unknown-8bit'" 문자 집합에 대한 처리가 추가
      되었습니다.

   __eq__(other)

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

   __ne__(other)

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

"email.header" 모듈은 다음과 같은 편의 함수도 제공합니다.

email.header.decode_header(header)

   문자 집합을 변환하지 않고 메시지 헤더 값을 디코딩합니다. 헤더 값은
   *header*에 있습니다.

   For historical reasons, this function may return either:

   1. A list of pairs containing each of the decoded parts of the
      header, "(decoded_bytes, charset)", where *decoded_bytes* is
      always an instance of "bytes", and *charset* is either:

         * A lower case string containing the name of the character
           set specified.

         * "None" for non-encoded parts of the header.

   2. A list of length 1 containing a pair "(string, None)", where
      *string* is always an instance of "str".

   An "email.errors.HeaderParseError" may be raised when certain
   decoding errors occur (e.g. a base64 decoding exception).

   Here are examples:

   >>> from email.header import decode_header
   >>> decode_header('=?iso-8859-1?q?p=F6stal?=')
   [(b'p\xf6stal', 'iso-8859-1')]
   >>> decode_header('unencoded_string')
   [('unencoded_string', None)]
   >>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
   [(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]

   참고:

     This function exists for backwards compatibility only. For new
     code, we recommend using "email.headerregistry.HeaderRegistry".

email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

   "decode_header()"에 의해 반환된 것과 같은 쌍의 시퀀스로부터
   "Header" 인스턴스를 만듭니다.

   "decode_header()"는 헤더 값 문자열을 취하고 "(decoded_string,
   charset)" 형식의 쌍의 시퀀스를 반환합니다. 여기서 *charset*은 문자
   집합의 이름입니다.

   이 함수는 해당 쌍의 시퀀스 중 하나를 취해서 "Header" 인스턴스를 반
   환합니다. 선택적 *maxlinelen*, *header_name* 및 *continuation_ws*는
   "Header" 생성자에서와 같습니다.

   참고:

     This function exists for backwards compatibility only, and is not
     recommended for use in new code.
