 |
 |
 |
Python ライブラリリファレンス |  |
 |
 |
|
|
|
Python ライブラリリファレンス | |
|
|
Message クラスは、 email パッケージの中心となるクラスです。 これは email オブジェクトモデルの基底クラスになっています。 Message はヘッダフィールドを検索したりメッセージ本体にアクセスするための 核となる機能を提供します。
概念的には、(email.messageモジュールからインポートされる) Message オブジェクトには ヘッダ と ペイロード が 格納されています。ヘッダは、RFC 2822 形式のフィールド名およびフィールド値が コロンで区切られたものです。コロンはフィールド名またはフィールド値の どちらにも含まれません。
ヘッダは大文字小文字を区別した形式で保存されますが、ヘッダ名が一致するかどうかの検査は
大文字小文字を区別せずにおこなうことができます。Unix-From ヘッダまたは
From_ ヘッダとして知られるエンベロープヘッダがひとつ存在することもあります。
ペイロードは、単純なメッセージオブジェクトの場合は単なる文字列ですが、
MIME コンテナ文書 (multipart/* または
message/rfc822 など) の場合は Message オブジェクトの
リストになっています。
Message オブジェクトは、メッセージヘッダにアクセスするための マップ (辞書) 形式のインタフェイスと、ヘッダおよびペイロードの両方に アクセスするための明示的なインタフェイスを提供します。 これにはメッセージオブジェクトツリーからフラットなテキスト文書を 生成したり、一般的に使われるヘッダのパラメータにアクセスしたり、また オブジェクトツリーを再帰的にたどったりするための便利なメソッドを含みます。
Message クラスのメソッドは以下のとおりです:
| ) |
| [unixfrom]) |
True の場合、返される文字列には
エンベロープヘッダも含まれます。unixfrom のデフォルトは False です。
このメソッドは手軽に利用する事ができますが、必ずしも期待通りにメッセージを
フォーマットするとは限りません。たとえば、これはデフォルトでは 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()
| ) |
| ) |
True を返し、そうでなければ False を返します。
is_multipart() が False を返した場合は、ペイロードは
文字列オブジェクトである必要があります。
| unixfrom) |
| ) |
| payload) |
None か、あるいは Message オブジェクトの
リストである必要があります。このメソッドの実行後、ペイロードは必ず
Message オブジェクトのリストになります。ペイロードに
スカラーオブジェクト (文字列など) を格納したい場合は、かわりに
set_payload() を使ってください。
| [i[, decode]]) |
True
の場合 Message オブジェクトのリストになり、is_multipart() が
False の場合は文字列になります。ペイロードがリストの場合、
リストを変更することはそのメッセージのペイロードを変更することになります。
オプション引数の i がある場合、
is_multipart() が True ならば get_payload() は
ペイロード中で 0 から数えて i 番目の要素を返します。i が
0 より小さい場合、あるいはペイロードの個数以上の場合は
IndexError が発生します。ペイロードが文字列
(つまり is_multipart() が False) にもかかわらず
i が与えられたときは TypeError が発生します。
オプションの decode はそのペイロードが
Content-Transfer-Encoding: ヘッダに従って
デコードされるべきかどうかを指示するフラグです。
この値が True でメッセージが multipart ではない場合、
ペイロードはこのヘッダの値が "quoted-printable" または
"base64" のときにかぎりデコードされます。これ以外のエンコーディングが
使われている場合、Content-Transfer-Encoding: ヘッダが
ない場合、あるいは曖昧なbase64データが含まれる場合は、ペイロードはそのまま
(デコードされずに) 返されます。
もしメッセージが multipart で decode フラグが True の場合は
None が返されます。decode のデフォルト値は False です。
| payload[, charset]) |
バージョン 2.2.2 で 変更 された仕様: charset 引数の追加
| charset) |
None のいずれかが指定できます。
文字列を指定した場合、これは Charset インスタンスに変換されます。
charset が None の場合、charset パラメータは
Content-Type: ヘッダから除去されます。
これ以外のものを文字セットとして指定した場合、
TypeError が発生します。
ここでいうメッセージとは、charset.input_charset でエンコードされた text/* 形式のものを仮定しています。これは、もし必要とあらば プレーンテキスト形式を変換するさいに charset.output_charset の エンコードに変換されます。MIME ヘッダ (MIME-Version:, Content-Type:, Content-Transfer-Encoding:) は必要に応じて追加されます。
バージョン 2.2.2 で 新たに追加 された仕様です。
| ) |
以下のメソッドは、メッセージの RFC 2822 ヘッダにアクセスするための マップ (辞書) 形式のインタフェイスを実装したものです。 これらのメソッドと、通常のマップ (辞書) 型はまったく同じ意味をもつわけでは ないことに注意してください。たとえば辞書型では、同じキーが複数あることは 許されていませんが、ここでは同じメッセージヘッダが複数ある場合があります。 また、辞書型では keys() で返されるキーの順序は保証されていませんが、 Message オブジェクト内のヘッダはつねに元のメッセージ中に 現れた順序、あるいはそのあとに追加された順序で返されます。削除され、その後 ふたたび追加されたヘッダはリストの一番最後に現れます。
こういった意味のちがいは意図的なもので、最大の利便性をもつようにつくられています。
注意: どんな場合も、メッセージ中のエンベロープヘッダは このマップ形式のインタフェイスには含まれません。
| ) |
| name) |
in 演算子で使われます:
if 'message-id' in myMessage:
print 'Message-ID:', myMessage['message-id']
| name) |
None が返され、KeyError 例外は発生しません。
注意: 指定された名前のフィールドがメッセージのヘッダに 2回以上現れている場合、 どちらの値が返されるかは未定義です。ヘッダに存在するフィールドの値をすべて 取り出したい場合は get_all() メソッドを使ってください。
| name, val) |
メッセージヘッダに name という名前の val という値をもつ フィールドをあらたに追加します。このフィールドは現在メッセージに 存在するフィールドのいちばん後に追加されます。
注意: このメソッドでは、すでに同一の名前で存在するフィールドは 上書きされません。もしメッセージが名前 name をもつ フィールドをひとつしか持たないようにしたければ、最初にそれを除去してください。 たとえば:
del msg['subject'] msg['subject'] = 'PythonPythonPython!'
| name) |
| name) |
| ) |
| ) |
| ) |
| name[, failobj]) |
None) を返すことをのぞけば、__getitem__() と同じです。
役に立つメソッドをいくつか紹介します:
| name[, failobj]) |
None) が返されます。
| _name, _value, **_params) |
キーワード引数辞書 _params の各項目ごとに、
そのキーがパラメータ名として扱われ、キー名にふくまれる
アンダースコアはハイフンに置換されます (なぜならハイフンは
通常の Python 識別子としては使えないからです)。ふつう、
パラメータの値が None 以外のときは、key="value" の
形で追加されます。パラメータの値が None のときはキーのみが追加されます。
例を示しましょう:
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
こうするとヘッダには以下のように追加されます。
Content-Disposition: attachment; filename="bud.gif"
| _name, _value) |
バージョン 2.2.2 で 新たに追加 された仕様です。
| ) |
RFC 2045 はメッセージのデフォルト content-type を、 それが multipart/digest コンテナに現れているとき以外は text/plain に規定しています。あるメッセージが multipart/digest コンテナ中にある場合、その content-type は message/rfc822 になります。 もし Content-Type: ヘッダが適切でない content-type 書式だった場合、 RFC 2045 はそれのデフォルトを text/plain として扱うよう 定めています。
バージョン 2.2.2 で 新たに追加 された仕様です。
| ) |
バージョン 2.2.2 で 新たに追加 された仕様です。
| ) |
バージョン 2.2.2 で 新たに追加 された仕様です。
| ) |
バージョン 2.2.2 で 新たに追加 された仕様です。
| ctype) |
バージョン 2.2.2 で 新たに追加 された仕様です。
| [failobj[, header[, unquote]]]) |
True (デフォルト) である場合、この値は unquote されます。
オプション引数 failobj は、Content-Type: ヘッダが 存在しなかった場合に返すオブジェクトです。オプション引数 header には Content-Type: のかわりに検索すべきヘッダを指定します。
バージョン 2.2.2 で 変更 された仕様: unquote が追加されました
| param[, failobj[, header[, unquote]]]) |
None) が返されます。
オプション引数 header が与えられた場合、 Content-Type: のかわりにそのヘッダが使用されます。
パラメータのキー比較は常に大文字小文字を区別しません。
返り値は文字列か 3 要素のタプルで、タプルになるのはパラメータが RFC 2231
エンコードされている場合です。3 要素タプルの場合、各要素の値は
(CHARSET, LANGUAGE, VALUE) の形式になっています。
CHARSET と LAGUAGE は None になることがあり、その場合
VALUE は us-ascii 文字セットでエンコードされているとみなさねば
ならないので注意してください。普段は LANGUAGE を無視できます。
この関数を使うアプリケーションが、パラメータが RFC 2231 形式で エンコードされているかどうかを気にしないのであれば、email.Utils.collapse_rfc2231_value() に get_param() の返り値を渡して呼び出すことで、このパラメータをひとつにまとめることができます。 この値がタプルならばこの関数は適切にデコードされた Unicode 文字列を返し、 そうでない場合は unquote された元の文字列を返します。たとえば:
rawparam = msg.get_param('foo')
param = email.Utils.collapse_rfc2231_value(rawparam)
いずれの場合もパラメータの値は (文字列であれ 3要素タプルの
VALUE 項目であれ) つねに unquote されます。
ただし、unquote が False に指定されている場合は
unquote されません。
バージョン 2.2.2 で 変更 された仕様: unquote 引数の追加、3要素タプルが返り値になる可能性あり
| param, value[, header[, requote[, charset[, language]]]]) |
Content-Type: ヘッダ中のパラメータを設定します。 指定されたパラメータがヘッダ中にすでに存在する場合、その値は value に置き換えられます。Content-Type: ヘッダがまだ このメッセージ中に存在していない場合、RFC 2045 にしたがいこの値には text/plain が設定され、新しいパラメータ値が末尾に追加されます。
オプション引数 header が与えられた場合、
Content-Type: のかわりにそのヘッダが使用されます。
オプション引数 unquote が False でない限り、
この値は unquote されます (デフォルトは True)。
オプション引数 charset が与えられると、 そのパラメータは RFC 2231 に従ってエンコードされます。 オプション引数 language は RFC 2231 の言語を指定しますが、 デフォルトではこれは空文字列となります。 charset と language はどちらも文字列である必要があります。
バージョン 2.2.2 で 新たに追加 された仕様です。
| param[, header[, requote]]) |
False でない限り (デフォルトでは True です)、
すべての値は必要に応じて quote されます。オプション変数 header が与えられた場合、
Content-Type: のかわりにそのヘッダが使用されます。
バージョン 2.2.2 で 新たに追加 された仕様です。
| type[, header][, requote]) |
このメソッドは Content-Type: ヘッダを置き換えますが、
すべてのパラメータはそのままにします。requote が False の場合、
これはすでに存在するヘッダを quote せず放置しますが、そうでない場合は
自動的に quote します (デフォルト動作)。
オプション変数 header が与えられた場合、 Content-Type: のかわりにそのヘッダが使用されます。 Content-Type: ヘッダが設定される場合には、 MIME-Version: ヘッダも同時に付加されます。
バージョン 2.2.2 で 新たに追加 された仕様です。
| [failobj]) |
filename パラメータの値を返します。目的のヘッダに
filename パラメータがない場合には nameパラメータを探しま
す。それも無い場合またはヘッダが無い場合には failobj が返されます。
返される文字列はつねに Utils.unquote() によって unquote されます。
| [failobj]) |
boundary パラメータの値を返します。目的のヘッダが欠けていたり、
boundary パラメータがない場合には failobj が返されます。
返される文字列はつねに Utils.unquote() によって unquote されます。
| boundary) |
boundary パラメータに値を設定します。set_boundary() は
必要に応じて boundary を quote します。そのメッセージが
Content-Type: ヘッダを含んでいない場合、
HeaderParseError が発生します。
注意: このメソッドを使うのは、古い Content-Type: ヘッダを 削除して新しい boundary をもったヘッダを add_header() で 足すのとは少し違います。set_boundary() は 一連のヘッダ中での Content-Type: ヘッダの位置を保つからです。 しかし、これは元の Content-Type: ヘッダ中に存在していた 連続する行の順番までは 保ちません。
| [failobj]) |
charset パラメータの値を返します。値はすべて小文字に変換されます。
メッセージ中に Content-Type: がなかったり、このヘッダ中に
boundary パラメータがない場合には failobj が返されます。
注意: これは get_charset() メソッドとは異なります。 こちらのほうは文字列のかわりに、そのメッセージボディのデフォルト エンコーディングの Charset インスタンスを返します。
バージョン 2.2.2 で 新たに追加 された仕様です。
| [failobj]) |
リスト中の各要素は文字列であり、これは対応する subpart 中の
それぞれの Content-Type: ヘッダにある charset の値です。
しかし、その subpart が Content-Type: をもってないか、
charset がないか、あるいは MIME maintype が text でない
いずれかの場合には、リストの要素として failobj が返されます。
| ) |
for ループ中でのイテレータとして
使うことでしょう。ループを一回まわるごとに、次の subpart が返されるのです。
以下の例は、 multipart メッセージのすべての part において、 その 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 範囲外テキストを含んでいます。 Parser があるテキストをヘッダ以降に発見したが、 それはまだ最初の MIME 境界文字列が現れる前だった場合、 パーザはそのテキストをメッセージの preamble 属性に格納します。 Generator がある MIME メッセージからプレーンテキスト形式を 生成するとき、これはそのテキストをヘッダと最初の MIME 境界の間に挿入します。 詳細は email.parser および email.Generator を 参照してください。
注意: そのメッセージに preamble がない場合、
preamble 属性には None が格納されます。
バージョン 2.5 で 変更 された仕様: Generatorでファイル終端に改行を出力するため、 epilogue に空文字列を設定する必要はなくなりました。
バージョン 2.4 で 新たに追加 された仕様です。
|
|
|
Python ライブラリリファレンス | |
|
|