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은 76이고, 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에 있습니다.

이 함수는 헤더의 디코딩된 각 부분을 포함하는 (decoded_string, charset) 쌍의 리스트를 반환합니다. charset은 헤더의 인코딩되지 않은 부분에 대해 None이며, 그렇지 않으면 인코딩된 문자열에 지정된 문자 집합의 이름을 포함하는 소문자 문자열입니다.

예를 들면 다음과 같습니다:

>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]
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 생성자에서와 같습니다.