# `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.