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 に追加します。

脚注