7.3.1 Mailbox オブジェクト

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

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 サブクラスによっては何もしないこともあります。

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