18.1.1. email.message：電子メールメッセージの表現—Pythonドキュメント

18.1.1。 email.message ：電子メールメッセージを表す

email パッケージの中心的なクラスは、 email.message モジュールからインポートされた Message クラスです。 email オブジェクトモデルの基本クラスです。 Message は、ヘッダーフィールドの設定とクエリ、およびメッセージ本文へのアクセスのためのコア機能を提供します。

概念的には、メッセージオブジェクトはヘッダーとペイロードで構成されます。 ヘッダーは RFC 2822 スタイルのフィールド名と値で、フィールド名と値はコロンで区切られています。 コロンは、フィールド名またはフィールド値の一部ではありません。

ヘッダーは大文字と小文字を区別せずに保存および返されますが、大文字と小文字は区別されません。 Unix-From ヘッダーまたはFrom_ヘッダーとも呼ばれる単一のエンベロープヘッダーが存在する場合もあります。 ペイロードは、単純なメッセージオブジェクトの場合は文字列、またはMIMEコンテナドキュメントの場合は Message オブジェクトのリストです（例： multipart / * および message / rfc822 ）。

Message オブジェクトは、メッセージヘッダーにアクセスするためのマッピングスタイルのインターフェイスと、ヘッダーとペイロードの両方にアクセスするための明示的なインターフェイスを提供します。 メッセージオブジェクトツリーのフラットテキスト表現を生成したり、一般的に使用されるヘッダーパラメータにアクセスしたり、オブジェクトツリーを再帰的にウォークオーバーしたりするための便利なメソッドを提供します。

Message クラスのメソッドは次のとおりです。

class email.message.Message

コンストラクターは引数を取りません。

as_string([unixfrom])

平坦化されたメッセージ全体を文字列として返します。 オプションの unixfrom がTrueの場合、エンベロープヘッダーは返される文字列に含まれます。 unixfrom のデフォルトはFalseです。 文字列への変換を完了するためにデフォルトを入力する必要がある場合、メッセージをフラット化すると、メッセージへの変更がトリガーされる場合があります（たとえば、MIME境界が生成または変更される場合があります）。

この方法は便宜上提供されており、必ずしもメッセージを希望どおりにフォーマットするとは限らないことに注意してください。 たとえば、デフォルトでは、Fromで始まる行がマングルされます。 柔軟性を高めるには、 Generator インスタンスをインスタンス化し、その flatten（）メソッドを直接使用します。 例えば：

from cStringIO import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=False, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

__str__()

as_string(unixfrom=True)と同等です。

is_multipart()

メッセージのペイロードがサブメッセージオブジェクトのリストである場合はTrueを返し、それ以外の場合はFalseを返します。 is_multipart（）がFalseを返す場合、ペイロードは文字列オブジェクトである必要があります。

set_unixfrom(unixfrom)

メッセージのエンベロープヘッダーを unixfrom に設定します。これは文字列である必要があります。

get_unixfrom()

メッセージのエンベロープヘッダーを返します。 エンベロープヘッダーが設定されていない場合、デフォルトはNoneです。

attach(payload)

指定された payload を現在のペイロードに追加します。現在のペイロードはNoneまたは Message オブジェクトのリストである必要があります。 呼び出し後、ペイロードは常に Message オブジェクトのリストになります。 ペイロードをスカラーオブジェクトに設定する場合（例： 文字列）、代わりに set_payload（）を使用します。

get_payload([i[, decode]])

現在のペイロードを返します。これは、 is_multipart（）がTrueの場合はメッセージオブジェクトのリスト、 is_multipart（）の場合は文字列になります。 Falseです。 ペイロードがリストであり、リストオブジェクトを変更する場合は、メッセージのペイロードをその場で変更します。

オプションの引数 i を使用すると、 is_multipart（）[X153Xの場合、 get_payload（）はペイロードの i 番目の要素をゼロから数えて返します。 ]はTrueです。 IndexErrorが発生します。 ペイロードが文字列の場合（つまり is_multipart（）はFalse）であり、 i が指定されると、TypeErrorが発生します。

オプションの decode は、 Content-Transfer-Encoding ヘッダーに従って、ペイロードをデコードする必要があるかどうかを示すフラグです。 Trueでメッセージがマルチパートでない場合、このヘッダーの値がquoted-printableまたはbase64の場合、ペイロードはデコードされます。 他のエンコーディングが使用されている場合、 Content-Transfer-Encoding ヘッダーが欠落している場合、またはペイロードに偽のbase64データがある場合、ペイロードはそのまま（デコードされていない）で返されます。 メッセージがマルチパートであり、 decode フラグがTrueの場合、Noneが返されます。 デコードのデフォルトはFalseです。

set_payload(payload[, charset])

メッセージオブジェクト全体のペイロードを payload に設定します。 ペイロードの不変条件を保証するのはクライアントの責任です。 オプションの charset は、メッセージのデフォルトの文字セットを設定します。 詳細については、 set_charset（）を参照してください。

バージョン2.2.2で変更： charset 引数が追加されました。

set_charset(charset)

ペイロードの文字セットを charset に設定します。これは、 Charset インスタンス（ email.charset を参照）、文字セットに名前を付ける文字列、またはNone。 文字列の場合は、 Charset インスタンスに変換されます。 charset がNoneの場合、charsetパラメーターは Content-Type ヘッダーから削除されます（メッセージは他の方法で変更されません）。 それ以外のものはTypeErrorを生成します。

既存の MIME-Version ヘッダーがない場合は、ヘッダーが追加されます。 既存の Content-Type ヘッダーがない場合は、 text / plain の値でヘッダーが追加されます。 Content-Type ヘッダーがすでに存在するかどうかに関係なく、そのcharsetパラメーターは charset.output_charset に設定されます。 charset.input_charset と charset.output_charset が異なる場合、ペイロードは output_charset に再エンコードされます。 既存の Content-Transfer-Encoding ヘッダーがない場合、ペイロードは、必要に応じて、指定された Charset を使用して転送エンコードされ、適切な値のヘッダーは次のようになります。追加した。 Content-Transfer-Encoding ヘッダーがすでに存在する場合、ペイロードはその Content-Transfer-Encoding を使用してすでに正しくエンコードされていると見なされ、変更されません。

メッセージはタイプ text / * であると想定され、ペイロードはユニコードであるか、 charset.input_charset でエンコードされています。 メッセージのプレーンテキスト表現を生成するときに、エンコードまたは charset.output_charset に変換され、必要に応じて適切に転送エンコードされます。 必要に応じて、MIMEヘッダー（ MIME-Version 、 Content-Type 、 Content-Transfer-Encoding ）が追加されます。

バージョン2.2.2の新機能。

get_charset()

メッセージのペイロードに関連付けられている Charset インスタンスを返します。

バージョン2.2.2の新機能。

次のメソッドは、メッセージの RFC 2822 ヘッダーにアクセスするためのマッピングのようなインターフェイスを実装します。 これらのメソッドと法線マッピングの間にはいくつかのセマンティックの違いがあることに注意してください（つまり、 辞書）インターフェース。 たとえば、辞書には重複するキーはありませんが、ここでは重複するメッセージヘッダーが存在する可能性があります。 また、辞書では、 keys（）によって返されるキーの順序は保証されていませんが、 Message オブジェクトでは、ヘッダーは常に元のメッセージに表示された順序で返されます。または後でメッセージに追加されました。 削除されてから再追加されたヘッダーは、常にヘッダーリストの最後に追加されます。

これらのセマンティックの違いは意図的なものであり、最大限の利便性に偏っています。

すべての場合において、メッセージに存在するエンベロープヘッダーはマッピングインターフェイスに含まれないことに注意してください。

__len__()

重複を含むヘッダーの総数を返します。

__contains__(name)

メッセージオブジェクトに name という名前のフィールドがある場合はtrueを返します。 マッチングは大文字と小文字を区別せずに行われ、 name には末尾のコロンを含めないでください。 in演算子に使用されます。例：

if 'message-id' in myMessage:
    print 'Message-ID:', myMessage['message-id']

__getitem__(name)

名前付きヘッダーフィールドの値を返します。 name には、コロンフィールド区切り文字を含めないでください。 ヘッダーがない場合は、Noneが返されます。 KeyErrorが発生することはありません。

名前付きフィールドがメッセージのヘッダーに複数回表示される場合、それらのフィールド値のどれが返されるかは正確には定義されていないことに注意してください。 get_all（）メソッドを使用して、現存するすべての名前付きヘッダーの値を取得します。

__setitem__(name, val)

フィールド名名前および値 val のヘッダーをメッセージに追加します。 このフィールドは、メッセージの既存のフィールドの最後に追加されます。

これは、同じ名前の既存のヘッダーを上書きまたは削除しないことに注意してください。 新しいヘッダーがフィールド名 name のメッセージに存在する唯一のヘッダーであることを確認する場合は、最初にフィールドを削除します。例：

del msg['subject']
msg['subject'] = 'Python roolz!'

__delitem__(name)

メッセージのヘッダーから name という名前のフィールドのすべての出現箇所を削除します。 名前付きフィールドがヘッダーに存在しない場合、例外は発生しません。

has_key(name)

メッセージに name という名前のヘッダーフィールドが含まれている場合はtrueを返し、それ以外の場合はfalseを返します。

keys()

すべてのメッセージのヘッダーフィールド名のリストを返します。

values()

すべてのメッセージのフィールド値のリストを返します。

items()

すべてのメッセージのフィールドヘッダーと値を含む2タプルのリストを返します。

get(name[, failobj])

名前付きヘッダーフィールドの値を返します。 これは __ getitem __（）と同じですが、名前付きヘッダーがない場合にオプションの failobj が返される点が異なります（デフォルトはNone）。

ここにいくつかの追加の便利な方法があります：

get_all(name[, failobj])

name という名前のフィールドのすべての値のリストを返します。 メッセージにそのような名前付きヘッダーがない場合は、 failobj が返されます（デフォルトはNone）。

add_header(_name, _value, **_params)

拡張ヘッダー設定。 このメソッドは __ setitem __（）に似ていますが、追加のヘッダーパラメーターをキーワード引数として指定できる点が異なります。 _name は追加するヘッダーフィールドであり、 _value はヘッダーの primary 値です。

キーワード引数ディクショナリ _params の各項目について、キーがパラメータ名として使用され、アンダースコアがダッシュに変換されます（ダッシュはPython識別子では無効であるため）。 通常、パラメータは、値がNoneの場合、キーのみが追加されます。 値に非ASCII文字が含まれている場合は、(CHARSET, LANGUAGE, VALUE)の形式で3つのタプルとして指定する必要があります。ここで、CHARSETは、値のエンコードに使用する文字セットを指定する文字列[X186X ] は通常、Noneまたは空の文字列に設定でき（他の可能性については RFC 2231 を参照）、VALUEは文字列です非ASCIIコードポイントを含む値。

次に例を示します。

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

これにより、次のようなヘッダーが追加されます

Content-Disposition: attachment; filename="bud.gif"

非ASCII文字の例：

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

どちらが生成します

Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"

replace_header(_name, _value)

ヘッダーを置き換えます。 _name に一致するメッセージで見つかった最初のヘッダーを置き換え、ヘッダーの順序とフィールド名の大文字と小文字を保持します。 一致するヘッダーが見つからなかった場合、KeyErrorが発生します。

バージョン2.2.2の新機能。

get_content_type()

メッセージのコンテンツタイプを返します。 返される文字列は、 maintype / subtype の形式の小文字に強制変換されます。 メッセージに Content-Type ヘッダーがない場合、 get_default_type（）で指定されたデフォルトタイプが返されます。 RFC 2045 によると、メッセージには常にデフォルトタイプがあるため、 get_content_type（）は常に値を返します。

RFC 2045 は、メッセージのデフォルトタイプを text / plain と定義しています。ただし、 multipart / digest コンテナ内に表示される場合は、 message / rfc822 になります。 Content-Type ヘッダーに無効な型指定がある場合、 RFC 2045 は、デフォルトの型を text / plain にすることを義務付けています。

バージョン2.2.2の新機能。

get_content_maintype()

メッセージのメインコンテンツタイプを返します。 これは、 get_content_type（）によって返される文字列の maintype 部分です。

バージョン2.2.2の新機能。

get_content_subtype()

メッセージのサブコンテンツタイプを返します。 これは、 get_content_type（）によって返される文字列のサブタイプの部分です。

バージョン2.2.2の新機能。

get_default_type()

デフォルトのコンテンツタイプを返します。 マルチパート/ダイジェストコンテナーのサブパートであるメッセージを除いて、ほとんどのメッセージのデフォルトのコンテンツタイプはテキスト/プレーンです。 このようなサブパーツのデフォルトのコンテンツタイプは message / rfc822 です。

バージョン2.2.2の新機能。

set_default_type(ctype)

デフォルトのコンテンツタイプを設定します。 ctype は text / plain または message / rfc822 のいずれかである必要がありますが、これは強制されません。 デフォルトのコンテンツタイプは、 Content-Type ヘッダーに保存されません。

バージョン2.2.2の新機能。

get_params([failobj[, header[, unquote]]])

メッセージの Content-Type パラメータをリストとして返します。 返されるリストの要素は、'='記号で分割されているように、キーと値のペアの2タプルです。 '='の左側がキーで、右側が値です。 パラメータに'='記号がない場合、値は空の文字列です。それ以外の場合、値は get_param（）で説明されているとおりであり、オプションの unquote がTrue（デフォルト）。

オプションの failobj は、 Content-Type ヘッダーがない場合に返されるオブジェクトです。 オプションの header は、 Content-Type の代わりに検索するヘッダーです。

バージョン2.2.2で変更： unquote 引数が追加されました。

get_param(param[, failobj[, header[, unquote]]])

Content-Type ヘッダーのパラメーター param の値を文字列として返します。 メッセージに Content-Type ヘッダーがない場合、またはそのようなパラメーターがない場合は、 failobj が返されます（デフォルトはNone）。

オプションの header が指定されている場合、 Content-Type の代わりに使用するメッセージヘッダーを指定します。

パラメータキーは常に大文字と小文字を区別せずに比較されます。 戻り値は、文字列、またはパラメータが RFC 2231 でエンコードされている場合は3タプルのいずれかです。 3タプルの場合、値の要素は(CHARSET, LANGUAGE, VALUE)の形式になります。 CHARSETとLANGUAGEはどちらもNoneにすることができます。その場合、VALUEはus-ascii文字セットでエンコードされていると見なす必要があります。 通常、LANGUAGEは無視できます。

アプリケーションがパラメーターが RFC 2231 のようにエンコードされているかどうかを気にしない場合は、 email.utils.collapse_rfc2231_value（）を呼び出すことでパラメーター値を折りたたむことができます。 、 get_param（）からの戻り値を渡します。 これにより、値がタプルの場合は適切にデコードされたUnicode文字列が返され、そうでない場合は引用符で囲まれていない元の文字列が返されます。 例えば：

rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)

いずれの場合も、 unquote がFalseに設定されていない限り、パラメーター値（返される文字列、または3タプルのVALUE項目）は常に引用符で囲まれません。

バージョン2.2.2で変更： unquote 引数が追加され、3タプルの戻り値が可能になりました。

set_param(param, value[, header[, requote[, charset[, language]]]])

Content-Type ヘッダーにパラメーターを設定します。 パラメータがすでにヘッダーに存在する場合、その値は value に置き換えられます。 このメッセージに対して Content-Type ヘッダーがまだ定義されていない場合は、 text / plain に設定され、 に従って新しいパラメーター値が追加されます。 ] RFC 2045 。

オプションの header は、 Content-Type の代替ヘッダーを指定し、オプションの requote がFalse（デフォルト）でない限り、すべてのパラメーターが必要に応じて引用されます。 True）です。

オプションの charset が指定されている場合、パラメーターは RFC 2231 に従ってエンコードされます。 オプションの language は、RFC 2231言語を指定し、デフォルトで空の文字列になります。 charset と language はどちらも文字列である必要があります。

バージョン2.2.2の新機能。

del_param(param[, header[, requote]])

Content-Type ヘッダーから指定されたパラメーターを完全に削除します。 ヘッダーは、パラメーターまたはその値なしでその場で書き直されます。 requote がFalse（デフォルトはTrue）でない限り、すべての値が必要に応じて引用されます。 オプションの header は、 Content-Type の代替を指定します。

バージョン2.2.2の新機能。

set_type(type[, header][, requote])

Content-Type ヘッダーのメインタイプとサブタイプを設定します。 type は、 maintype / subtype の形式の文字列である必要があります。そうでない場合、ValueErrorが発生します。

このメソッドは、 Content-Type ヘッダーを置き換え、すべてのパラメーターを所定の位置に保持します。 requote がFalseの場合、既存のヘッダーの引用はそのままになります。それ以外の場合、パラメーターは引用されます（デフォルト）。

header 引数で代替ヘッダーを指定できます。 Content-Type ヘッダーが設定されている場合、 MIME-Version ヘッダーも追加されます。

バージョン2.2.2の新機能。

get_filename([failobj])

メッセージの Content-Disposition ヘッダーのfilenameパラメーターの値を返します。 ヘッダーにfilenameパラメーターがない場合、このメソッドは Content-Type ヘッダーでnameパラメーターを探すことにフォールバックします。 どちらも見つからない場合、またはヘッダーがない場合は、 failobj が返されます。 返される文字列は、 email.utils.unquote（）に従って、常に引用符で囲まれていません。

get_boundary([failobj])

メッセージの Content-Type ヘッダーのboundaryパラメーターの値を返します。ヘッダーがないか、 [がない場合は、 failobj を返します。 X163X]パラメータ。 返される文字列は、 email.utils.unquote（）に従って、常に引用符で囲まれていません。

set_boundary(boundary)

Content-Type ヘッダーのboundaryパラメーターを boundary に設定します。 set_boundary（）は、必要に応じて常に boundary を引用します。 メッセージオブジェクトに Content-Type ヘッダーがない場合、 HeaderParseError が発生します。

set_boundary（）[ X195X]は、ヘッダーのリスト内の Content-Type ヘッダーの順序を保持します。 ただし、元の Content-Type ヘッダーに存在していた可能性のある継続行は保存されません。

get_content_charset([failobj])

Content-Type ヘッダーのcharsetパラメーターを小文字に強制変換して返します。 Content-Type ヘッダーがない場合、またはそのヘッダーにcharsetパラメーターがない場合は、 failobj が返されます。

このメソッドは、メッセージ本文のデフォルトエンコーディングの Charset インスタンスを返す get_charset（）とは異なることに注意してください。

バージョン2.2.2の新機能。

get_charsets([failobj])

メッセージ内の文字セット名を含むリストを返します。 メッセージが multipart の場合、リストにはペイロード内のサブパートごとに1つの要素が含まれます。それ以外の場合は、長さ1のリストになります。

リスト内の各項目は、表されたサブパーツの Content-Type ヘッダーのcharsetパラメーターの値である文字列になります。 ただし、サブパーツに Content-Type ヘッダーがない場合、charsetパラメーターがない場合、または text メインMIMEタイプでない場合、返されるリストのその項目 failobj になります。

walk()

walk（）メソッドは、メッセージオブジェクトツリーのすべての部分とサブ部分を深さ優先の走査順序で反復するために使用できる汎用ジェネレーターです。 通常、 walk（）をforループのイテレータとして使用します。 各反復は次のサブパートを返します。

マルチパートメッセージ構造のすべての部分のMIMEタイプを出力する例を次に示します。

>>> for part in msg.walk():
...     print part.get_content_type()
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822

バージョン2.5での変更：以前に非推奨になったメソッドget_type()、get_main_type()、およびget_subtype()は削除されました。

Message オブジェクトには、オプションで2つのインスタンス属性を含めることもできます。これらの属性は、MIMEメッセージのプレーンテキストを生成するときに使用できます。

preamble

MIMEドキュメントの形式では、ヘッダーに続く空白行と最初のマルチパート境界文字列の間にテキストを含めることができます。 通常、このテキストは標準のMIMEアーマーの範囲外であるため、MIME対応のメールリーダーには表示されません。 ただし、メッセージの生のテキストを表示する場合、またはMIMEに対応していないリーダーでメッセージを表示する場合、このテキストが表示される可能性があります。

preamble 属性には、MIMEドキュメント用のこの主要な追加アーマーテキストが含まれています。 Parser は、ヘッダーの後、最初の境界文字列の前にテキストを検出すると、このテキストをメッセージの preamble 属性に割り当てます。 Generator がMIMEメッセージのプレーンテキスト表現を書き出していて、メッセージに preamble 属性があることがわかった場合、ヘッダーと最初の境界。 詳細については、 email.parser および email.generator を参照してください。

メッセージオブジェクトにプリアンブルがない場合、プリアンブル属性はNoneになることに注意してください。

epilogue

epilogue 属性は、 preamble 属性と同じように機能しますが、最後の境界とメッセージの終わりの間に表示されるテキストが含まれている点が異なります。

バージョン2.5で変更： Generator がファイルの最後に改行を出力するために、エピローグを空の文字列に設定する必要はありません。

defects

defects 属性には、このメッセージの解析時に見つかったすべての問題のリストが含まれています。 考えられる解析の欠陥の詳細については、 email.errors を参照してください。

バージョン2.4の新機能。