"email.contentmanager": MIME コンテンツの管理
*********************************************

**ソースコード:** Lib/email/contentmanager.py

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

Added in version 3.6: [1]

class email.contentmanager.ContentManager

   コンテンツマネージャーの基底クラスです。 MIME コンテンツと他の表現
   との変換処理を登録する標準のレジストリ機構と、処理を振り分ける
   "get_content()"、"set_content()" メソッドを提供します。

   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__")

      * 型の "name" ("typ.__name__")。

      いずれも一致しない場合、*MRO* ("typ.__mro__") 内の各型について、
      上記の確認をすべて繰り返します。 それでもハンドラーが見つからな
      い場合、最後にキー "None" のハンドラーを探します。 "None" のハン
      ドラーもなければ、型の完全修飾名を示す "KeyError" を送出します。

      Also add a *MIME-Version* header if one is not present (see also
      "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')

      Return the payload of the part as either a string (for "text"
      parts), an "EmailMessage" object (for "message/rfc822" parts),
      or a "bytes" object (for all other non-multipart types).  Raise
      a "KeyError" if called on a "multipart".  If the part is a
      "text" part and *errors* is specified, use it as the error
      handler when decoding the payload to a string.  The default
      error handler is "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" の場合はエラーを送出します ("message/partial" パート
        の作成には "bytes" オブジェクトを使う必要があります)。

      *charset* が指定されている場合 ("str" でのみ有効)、指定された文
      字セットで文字列をバイト列にエンコードします。 デフォルトは
      "utf-8" です。 指定された *charset* が標準の MIME 文字セット名の
      既知の別名であれば、標準の文字セット名を使います。

      *cte* が設定されている場合、指定されたコンテンツ転送エンコーディ
      ングでペイロードをエンコードし、*Content-Transfer-Encoding* ヘッ
      ダーをその値に設定します。 *cte* に指定できる値は "quoted-
      printable"、"base64"、"7bit"、"8bit"、"binary" です。 非 ASCII
      値を含む入力に *cte* として "7bit" を指定するなど、入力を指定さ
      れた形式でエンコードできない場合は "ValueError" を送出します。

      * "str" オブジェクトで *cte* を設定していない場合、ヒューリステ
        ィックによって最もコンパクトなエンコーディングを決めます。 エ
        ンコード前に "str.splitlines()" ですべての行境界を正規化し、ペ
        イロードの各行が現在のポリシーの "linesep" プロパティで終わる
        ようにします (元の文字列が改行で終わっていなくても同様です)。

      * "bytes" オブジェクトの場合、*cte* を設定していなければ base64
        とみなし、上記の改行変換は行いません。

      * "EmailMessage" の場合、**RFC 2046** に従い、*subtype* が
        "rfc822" で *cte* に "quoted-printable" または "base64" を指定
        した場合と、*subtype* が "external-body" で *cte* に "7bit" 以
        外を指定した場合にはエラーを送出します。 "message/rfc822" で
        *cte* が指定されていなければ "8bit" を使います。 それ以外の
        *subtype* では "7bit" を使います。

      注釈:

        *cte* の "binary" は、まだ正しく動作しません。 "set_content()"
        によって変更された "EmailMessage" オブジェクトは正しいものの、
        "BytesGenerator" が正しく直列化しません。

      *disposition* が設定されていれば、*Content-Disposition* ヘッダー
      の値として使います。 指定されておらず、*filename* が指定されてい
      る場合は、値を "attachment" としてヘッダーを追加します。
      *disposition* も *filename* も指定されていなければ、ヘッダーは追
      加しません。 *disposition* に有効な値は "attachment" と "inline"
      だけです。

      *filename* が指定されている場合、*Content-Disposition* ヘッダー
      の "filename" パラメータの値として使います。

      *cid* が指定されている場合、その値を持つ *Content-ID* ヘッダーを
      追加します。

      *params* が指定されている場合、その "items()" メソッドの結果を反
      復処理し、得られた "(key, value)" ペアを使って *Content-Type* ヘ
      ッダーに追加のパラメータを設定します。

      *headers* が指定されていて、"headername: headervalue" 形式の文字
      列のリスト、または "header" オブジェクトのリスト ("name" 属性を
      持つことで文字列と区別します) である場合、そのヘッダーを *msg*
      に追加します。

-[ 脚注 ]-

[1] 当初は 3.4 で *暫定モジュール* として追加されました。
