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

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

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

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

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

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

Of course, as email has been deployed worldwide, it has become
internationalized, such that language specific character sets can now
be used in email messages.  The base standard still requires email
messages to be transferred using only 7-bit ASCII characters, so a
slew of RFCs have been written describing how to encode email
containing non-ASCII characters into **RFC 2822**-compliant format.
These RFCs include **RFC 2045**, **RFC 2046**, **RFC 2047**, and **RFC
2231**. The "email" package supports these standards in its
"email.header" and "email.charset" modules.

If you want to include non-ASCII characters in your email headers, say
in the *Subject* or *To* fields, you should use the "Header" class and
assign the field in the "Message" object to an instance of "Header"
instead of using a string for the header value.  Import the "Header"
class from the "email.header" module. For example:

   >>> 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" 인스턴스가 다른지 비교할 수 있
      습니다.

The "email.header" module also provides the following convenient
functions.

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.
