7.3.1 Mailbox オブジェクト

class Mailbox
メールボックス。中を見られたり変更されたりします。

Mailbox のインタフェースは辞書風で、小さなキーがメッセージに対応します。 キーは対象となる Mailbox インスタンスが発行するもので、そのインスタンスに対して のみ意味を持ちます。一つのキーは一つのメッセージにひも付けられ、その対応はメッセージが 他のメッセージで置き換えられるような更新をされたあとも続きます。メッセージを Mailbox インスタンスに追加するには集合風のメソッド add() を使います。 また削除は del 文または集合風の remove()discard() を使って行ないます。

Mailbox インタフェースのセマンティクスと辞書のそれとは注意すべき違いが あります。メッセージは、要求されるたびに新しい表現(典型的には Message インスタンス)が現在のメールボックスの状態に基づいて生成されます。同様に、メッセージが Mailbox インスタンスに追加される時も、渡されたメッセージ表現の内容が コピーされます。どちらの場合も Makebox インスタンスにメッセージ表現 への参照は保たれません。

デフォルトの Mailbox イテレータはメッセージ表現ごとに繰り返すもので、 辞書のイテレータのようにキーごとの繰り返しではありません。さらに、繰り返し中の メールボックスを変更することは安全であり整合的に定義されています。イテレータが 作られた後にメールボックスに追加されたメッセージはそのイテレータからは見えません。 そのイテレータが yield するまえにメールボックスから削除されたメッセージは 黙ってスキップされますが、イテレータからのキーを使ったときにはそのキーに対応する メッセージが削除されているならば KeyError を受け取ることに なります。

Mailbox 自体はインタフェースを定義し形式ごとのサブクラスに継承される ように意図されたもので、インスタンス化されることは想定されていません。インスタンス化 したいならばサブクラスを代わりに使うべきです。

Mailbox インスタンスには次のメソッドがあります。

add( message)
メールボックスに message を追加し、それに割り当てられたキーを返します。

引数 messageMessage インスタンス、 email.Message.Message インスタンス、文字列、ファイル風オブジェクト (テキストモードで開かれていなければなりませんが)を使えます。 message が適切な形式に特化した Message サブクラスのインスタンス (例えばメールボックスが mbox インスタンスのときの mboxMessage インスタンス)であれば、形式ごとの情報が利用されます。そうでなければ、形式ごとに 必要な情報は適当なデフォルトが使われます。

remove( key)
__delitem__( key)
discard( key)
メールボックスから key に対応するメッセージを削除します。

対応するメッセージが無い場合、メソッドが remove() または __delitem__() として呼び出されている時は KeyError 例外が 送出されます。しかし、discard() として呼び出されている場合は例外は発生 しません。基づいているメールボックス形式が別のプロセスからの平行した変更をサポート しているならば、この discard() の振る舞いの方が好まれるかもしれません。

__setitem__( key, message)
key に対応するメッセージを message で置き換えます。 key に対応しているメッセージが既に無くなっている場合 KeyError 例外 が送出されます。

add() と同様に、引数の message には Message イン スタンス、email.Message.Message インスタンス、文字列、ファイル 風オブジェクト(テキストモードで開かれていなければなりませんが)を使えま す。message が適切な形式に特化した Message サブクラスのイ ンスタンス(例えばメールボックスが mbox インスタンスのとき の mboxMessage インスタンス)であれば、形式ごとの情報が利用され ます。そうでなければ、現在 key に対応するメッセージの形式ごとの情報が 変更されずに残ります。

iterkeys( )
keys( )
iterkeys() として呼び出されると全てのキーについてのイテレータを返しますが、 keys() として呼び出されるとキーのリストを返します。

itervalues( )
__iter__( )
values( )
itervalues() または __iter__() として呼び出されると 全てのメッセージの表現についてのイテレータを返しますが、 values() として呼び出されるとその表現のリストを返します。 メッセージは適切な形式ごとの Message サブクラスのインスタンスとして表現される のが普通ですが、Mailbox インスタンスが初期化されるときに指定すればお好みの メッセージファクトリを使うこともできます。注意: __iter__() は 辞書のそれのようにキーについてのイテレータではありません。

iteritems( )
items( )
(key, message) ペア、ただし key はキーで message は メッセージ表現、のイテレータ(iteritems() として呼び出された場合)、または リスト(items() として呼び出された場合)を返します。メッセージは適切な 形式ごとの Message サブクラスのインスタンスとして表現される のが普通ですが、Mailbox インスタンスが初期化されるときに指定すればお好みの メッセージファクトリを使うこともできます。

get( key[, default=None])
__getitem__( key)
key に対応するメッセージの表現を返します。 対応するメッセージが存在しない場合、get() として呼び出されたなら default を返しますが、__getitem__() として呼び出されたなら KeyError 例外 が送出されます。メッセージは適切な 形式ごとの Message サブクラスのインスタンスとして表現される のが普通ですが、Mailbox インスタンスが初期化されるときに指定すればお好みの メッセージファクトリを使うこともできます。

get_message( key)
key に対応するメッセージの表現を形式ごとの Message サブクラスの インスタンスとして返します。もし対応するメッセージが存在しなければ KeyError 例外が送出されます。

get_string( key)
key に対応するメッセージの表現を文字列として返します。もし対応するメッセージが 存在しなければKeyError 例外が送出されます。

get_file( key)
key に対応するメッセージの表現をファイル風表現として返します。 もし対応するメッセージが存在しなければKeyError 例外が送出 されます。ファイル風オブジェクトはバイナリモードで開かれているように 振る舞います。このファイルは必要がなくなったら閉じなければなりません。

注意: 他の表現方法とは違い、ファイル風オブジェクトはそれを作り出した Mailbox インスタンスやそれが基づいているメールボックスと独立である必要がありません。 より詳細な説明は各サブクラスごとにあります。

has_key( key)
__contains__( key)
key がメッセージに対応していれば True を、そうでなければ False を返します。

__len__( )
メールボックス中のメッセージ数を返します。

clear( )
メールボックスから全てのメッセージを削除します。

pop( key[, default])
key に対応するメッセージの表現を返します。もし対応するメッセージが存在しなければ default が供給されていればその値を返し、そうでなければ KeyError 例外を送出します。メッセージは適切な 形式ごとの Message サブクラスのインスタンスとして表現される のが普通ですが、Mailbox インスタンスが初期化されるときに指定すればお好みの メッセージファクトリを使うこともできます。

popitem( )
任意に選んだ (key, message) ペアを返します。 ただしここで key はキーで message はメッセージ表現です。 もしメールボックスが空ならば、KeyError 例外を送出します。メッセージは適切な 形式ごとの Message サブクラスのインスタンスとして表現される のが普通ですが、Mailbox インスタンスが初期化されるときに指定すればお好みの メッセージファクトリを使うこともできます。

update( arg)
引数 argkey から message へのマッピングまたは (key, message) ペアのイテレート可能オブジェクトでなければなりません。 メールボックスは、各 keymessage のペアについて __setitem__() を使ったかのように key に対応するメッセージが message になるように更新されます。 __setitem__() と同様に、key は既存のメールボックス中のメッセージ に対応しているものでなければならず、そうでなければ KeyError が送出されます。 ですから、一般的には argMailbox インスタンスを渡すのは間違いです。 注意: 辞書と違い、キーワオード引数はサポートされていません。

flush( )
保留されている変更をファイルシステムに書き込みます。Mailbox のサブクラス によっては変更はいつも直ちにファイルに書き込まれこのメソッドは何もしないという こともあります。

lock( )
メールボックスの排他的アドバイザリロックを取得し、他のプロセスが変更しないようにします。 ロックが取得できない場合 ExternalClashError が送出されます。 ロック機構はメールボックス形式によって変わります。

unlock( )
メールボックスのロックを、もしあれば、解放します。

close( )
+Flush the mailbox, unlock it if necessary, and close any open files. For some +Mailbox subclasses, this method does nothing. メールボックスをフラッシュし、必要ならばアンロックし、開いているファイルを閉じます。 Mailbox サブクラスによっては何もしないこともあります。



ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。