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