"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*에 추가합니다.

-[ 각주 ]-

[1] 원래 3.4에서 *잠정적 모듈*로 추가되었습니다.
