"email.contentmanager": MIME 콘텐츠 관리
****************************************

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

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

버전 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__").

         * 형의 qualname ("typ.__qualname__")

         * 형의 이름 ("typ.__name__").

      이 중 아무것도 일치하지 않으면, *MRO*("typ.__mro__")의 각 형에
      대해 위의 모든 검사를 반복합니다. 마지막으로, 다른 키가 처리기를
      생성하지 않으면, "None" 키의 처리기를 확인합니다. "None"에 대한
      처리기가 없으면, 형의 완전히 정규화된 이름으로 "KeyError"를 발생
      시킵니다.

      *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"를 발생시킵니다.

         * "str" 객체의 경우, *cte*가 설정되지 않으면 휴리스틱을 사용
           하여 가장 간결한 인코딩을 결정합니다.

         * "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에서 *잠정적 모듈*로 추가되었습니다.
