email.contentmanager: Managing MIME Content

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

Added in version 3.6: [1]

class email.contentmanager.ContentManager

콘텐츠 관리자를 위한 베이스 클래스. get_content와 set_content 디스패치 메서드뿐만 아니라 MIME 콘텐츠와 다른 표현 간의 변환기를 등록하는 표준 등록소 메커니즘을 제공합니다.

get_content(msg, *args, **kw)

msg의 mimetype을 기반으로 처리기 함수를 찾고 (다음 단락을 참조하십시오), 모든 인자를 전달하여 그것을 호출하고, 이 호출의 결과를 반환합니다. 처리기가 msg에서 페이 로드를 추출하고 추출된 데이터에 대한 정보를 인코딩하는 객체를 반환할 것으로 기대합니다.

처리기를 찾으려면, 등록소에서 다음 키를 찾는데, 처음 발견되는 것에서 멈춥니다:

  • 전체 MIME 유형을 나타내는 문자열 (maintype/subtype)

  • maintype을 나타내는 문자열

  • 빈 문자열

이러한 키 중 아무것도 이러한 처리기를 생성하지 않으면, 전체 MIME 유형에 대해 KeyError를 발생시킵니다.

set_content(msg, obj, *args, **kw)

maintype이 multipart이면, TypeError를 발생시킵니다; 그렇지 않으면 obj의 형을 기반으로 처리기 함수를 찾고 (다음 단락을 참조하십시오), msg에서 clear_content()를 호출한 다음, 모든 인자를 전달해서 처리기 함수를 호출합니다. 처리기가 obj를 msg로 변환하고 저장할 것으로 기대하는데, 저장된 데이터를 해석하는 데 필요한 정보를 인코딩하기 위해 다양한 MIME 헤더를 추가하는 등 msg에 다른 변경을 가할 수 있습니다.

처리기를 찾으려면, obj의 형을 얻고 (typ = type(obj)), 등록소에서 다음 키를 찾는데 처음 발견되는 것에서 멈춥니다:

  • 형 자체 (typ)

  • 형의 완전히 정규화된 이름 (typ.__module__ + '.' + typ.__qualname__).

  • the type’s qualname (typ.__qualname__)

  • the type’s name (typ.__name__).

If none of the above match, repeat all of the checks above for each of the types in the MRO (typ.__mro__). Finally, if no other key yields a handler, check for a handler for the key None. If there is no handler for None, raise a KeyError for the fully qualified name of the type.

MIME-Version 헤더가 없으면 추가합니다 (MIMEPart를 참조하십시오).

add_get_handler(key, handler)

함수 handler를 key의 처리기로 기록합니다. 가능한 key 값은 get_content()를 참조하십시오.

add_set_handler(typekey, handler)

typekey와 일치하는 형의 객체가 set_content()에 전달될 때 호출할 함수로 handler를 기록합니다. 가능한 typekey 값은 set_content()를 참조하십시오.

콘텐츠 관리자 인스턴스

현재 email 패키지는 하나의 구상 콘텐츠 관리자 raw_data_manager만 제공하지만, 향후에는 더 추가될 수 있습니다. raw_data_manager는 EmailPolicy와 그 파생물에 의해 제공되는 content_manager입니다.

email.contentmanager.raw_data_manager

이 콘텐츠 관리자는 Message 자체에서 제공하는 것 외에는 최소 인터페이스 만 제공합니다: 텍스트, 날 바이트열 및 Message 객체만 다룹니다. 그런데도 기본 API와 비교할 때 상당한 이점을 제공합니다: 텍스트 파트에 대한 get_content는 응용 프로그램이 수동으로 디코딩할 필요 없이 유니코드 문자열을 반환하고, set_content는 파트에 추가된 헤더를 제어하고 콘텐츠 전송 인코딩을 제어하기 위한 다양한 옵션을 제공하고, 다양한 add_ 메서드를 사용할 수 있도록 해서, 멀티 파트 메시지 작성을 단순화합니다.

email.contentmanager.get_content(msg, errors='replace')

파트의 페이 로드를 문자열(text 파트의 경우), EmailMessage 객체 (message/rfc822 파트의 경우) 또는 bytes 객체 (다른 모든 비 멀티 파트 유형의 경우)로 반환합니다. multipart에서 호출되면 KeyError를 발생시킵니다. 파트가 text 파트이고 errors가 지정되면, 페이 로드를 유니코드로 디코딩할 때 에러 처리기로 사용합니다. 기본 에러 처리기는 replace입니다.

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

msg에 헤더와 페이 로드를 추가합니다:

maintype/subtype 값으로 Content-Type 헤더를 추가합니다.

  • str의 경우, MIME maintype을 text로 설정하고, 서브 유형은 지정되었으면 subtype으로 설정하고, 지정되지 않았으면 plain으로 설정합니다.

  • bytes의 경우, 지정된 maintype과 subtype을 사용하거나, 지정되지 않았으면 TypeError를 발생시킵니다.

  • EmailMessage 객체의 경우, 메인 유형을 message로 설정하고, 서브 유형은 지정되었으면 subtype으로 설정하고, 지정되지 않았으면 rfc822로 설정합니다. subtype이 partial이면 에러를 발생시킵니다 (bytes 객체를 사용하여 message/partial 파트를 구성해야 합니다).

charset이 제공되면 (str에만 유효합니다), 지정된 문자 집합을 사용하여 문자열을 바이트열로 인코딩합니다. 기본값은 utf-8입니다. 지정된 charset이 표준 MIME 문자 집합 이름의 알려진 별칭이면, 표준 문자 집합을 대신 사용합니다.

cte가 설정되면, 지정된 콘텐츠 전송 인코딩을 사용하여 페이 로드를 인코딩하고, Content-Transfer-Encoding 헤더를 해당 값으로 설정합니다. cte의 가능한 값은 quoted-printable, base64, 7bit, 8bit 및 binary입니다. 지정된 인코딩으로 입력을 인코딩할 수 없으면 (예를 들어, 비 ASCII 값을 포함하는 입력에 대해 cte를 7bit로 지정합니다), ValueError를 발생시킵니다.

  • For str objects, if cte is not set use heuristics to determine the most compact encoding. Prior to encoding, str.splitlines() is used to normalize all line boundaries, ensuring that each line of the payload is terminated by the current policy’s linesep property (even if the original string did not end with one).

  • For bytes objects, cte is taken to be base64 if not set, and the aforementioned newline translation is not performed.

  • EmailMessage의 경우, RFC 2046에 따라, subtype rfc822에 대해 quoted-printable이나 base64의 cte가 요청되거나, subtype external-body에 대해 7bit 이외의 cte에 대해 에러를 발생시킵니다. message/rfc822의 경우, cte가 지정되지 않으면 8bit를 사용합니다. subtype의 다른 모든 값에는 7bit를 사용합니다.

참고

binary의 cte는 실제로 아직 제대로 작동하지 않습니다. set_content에 의해 수정된 EmailMessage 객체는 올바르지만, BytesGenerator는 이것을 올바르게 직렬화하지 않습니다.

disposition이 설정되면, 이를 Content-Disposition 헤더의 값으로 사용합니다. 지정되지 않고 filename이 지정되면, 값이 attachment인 헤더를 추가합니다. disposition이 지정되지 않고 filename도 지정되지 않으면, 헤더를 추가하지 않습니다. disposition에 유효한 값은 attachment와 inline뿐 입니다.

filename이 지정되면, 이를 Content-Disposition 헤더의 filename 파라미터의 값으로 사용합니다.

cid가 지정되면, cid를 값으로 사용하여 Content-ID 헤더를 추가합니다.

params가 지정되면, 그것의 items 메서드를 이터레이트하고 결과 (key, value) 쌍을 사용하여 Content-Type 헤더에 추가 파라미터를 설정합니다.

headers가 지정되고 headername: headervalue 형식의 문자열 리스트나 header 객체 (name 어트리뷰트를 가진 것으로 문자열과 구별됩니다) 리스트면, 헤더를 msg에 추가합니다.

각주