"mailbox" --- 様々な形式のメールボックスを操作する
**************************************************

**ソースコード:** Lib/mailbox.py

======================================================================

このモジュールでは二つのクラス "Mailbox" および "Message" をディスク上
のメールボックスとそこに収められたメッセージへのアクセスと操作のために
定義しています。 "Mailbox" は辞書のようなキーからメッセージへの対応付
けを提供しています。 "Message" は "email.message" モジュールの
"Message" を拡張して形式ごとの状態と振る舞いを追加しています。サポート
されるメールボックスの形式は Maildir, mbox, MH, Babyl, MMDF です。

参考:

  "email" モジュール
     メッセージの表現と操作。


"Mailbox" オブジェクト
======================

class mailbox.Mailbox

   メールボックス。内容を確認したり変更したりできます。

   "Mailbox" クラスはインターフェースを定義するもので、インスタンス化
   されることは想定していません。代わりに、"Mailbox" から継承した形式
   ごとのサブクラスを作り、コードでは特定のサブクラスをインスタンス化
   するべきです。

   "Mailbox" のインターフェースは辞書風で、小さなキーがメッセージに対
   応します。キーは対象となる "Mailbox" インスタンスが発行するもので、
   その "Mailbox" インスタンスに対してのみ意味を持ちます。一つのキーは
   一つのメッセージにひも付けられ、その対応はメッセージが他のメッセー
   ジで置き換えられるような更新をされたあとも続きます。

   メッセージを "Mailbox" インスタンスに追加するには集合風のメソッド
   "add()" を使います。また削除は "del" 文または集合風の "remove()" や
   "discard()" を使って行ないます。

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

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

   警告:

     十分な注意を、何か他のプロセスによっても同時に変更される可能性の
     あるメールボックスを更新する時は、払わなければなりません。そのよ
     うなタスクをこなすのに最も安全なメールボックス形式は "Maildir" で
     、 "mbox" のような単一ファイルの形式を並行した書き込みに利用する
     のは避けるように努力しましょう。メールボックスを更新する場面では
     、 *必ず* "lock()" と "unlock()" メソッドを、ファイル内のメッセー
     ジを読んだり書き込んだり削除したりといった操作をする *前* に、呼
     び出してロックします。メールボックスをロックし損なうと、メッセー
     ジを失ったりメールボックス全体をぐちゃぐちゃにしたりする羽目に陥
     ります。

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

   add(message)

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

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

      バージョン 3.2 で変更: バイナリ入力のサポートが追加されました。

   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()

      Return an *iterator* over all keys

   keys()

      The same as "iterkeys()", except that a "list" is returned
      rather than an *iterator*

   itervalues()
   __iter__()

      全てのメッセージの表現についての *イテレータ* を返します。メッセ
      ージは適切な形式ごとの "Message" サブクラスのインスタンスとして
      表現されるのが普通ですが、 "Mailbox" インスタンスが初期化される
      ときに指定すればお好みのメッセージファクトリを使うこともできます
      。

      注釈:

        "__iter__()" は辞書のそれのようにキーについてのイテレータでは
        ありません。

   values()

      The same as "itervalues()", except that a "list" is returned
      rather than an *iterator*

   iteritems()

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

   items()

      The same as "iteritems()", except that a "list" of pairs is
      returned rather than an *iterator* of pairs.

   get(key, default=None)
   __getitem__(key)

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

   get_message(key)

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

   get_bytes(key)

      *key* に対応するメッセージのバイト列を返すか、そのようなメッセー
      ジが存在しない場合は "KeyError" 例外を送出します。

      Added in version 3.2.

   get_string(key)

      *key* に対応するメッセージの文字列表現を返すか、そのようなメッセ
      ージが存在しない場合は "KeyError" 例外を送出します。このメッセー
      ジは "email.message.Message" を通して処理されて7ビットクリーンな
      表現へ変換されます。

   get_file(key)

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

      バージョン 3.2 で変更: ファイルオブジェクトは実際は *バイナリフ
      ァイル* です; 以前は誤ってテキストモードで返されていました。 ま
      た、現在 *ファイル風オブジェクト* は *コンテキストマネージャ* プ
      ロトコルをサポートしています: "with" 文を用いることで自動的にフ
      ァイルを閉じることができます。

      注釈:

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

   __contains__(key)

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

   __len__()

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

   clear()

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

   pop(key, default=None)

      *key* に対応するメッセージの表現を返します。メッセージは適切な形
      式ごとの "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"
      のサブクラスによっては変更はいつも直ちにファイルに書き込まれ
      "flush()" は何もしないということもありますが、それでもこのメソッ
      ドを呼ぶように習慣付けておきましょう。

   lock()

      メールボックスの排他的アドバイザリロックを取得し、他のプロセスが
      変更しないようにします。ロックが取得できない場合
      "ExternalClashError" が送出されます。ロック機構はメールボックス
      形式によって変わります。メールボックスの内容に変更を加えるときは
      *いつも* ロックを掛けるべきです。

   unlock()

      メールボックスのロックが存在する場合は解放します。

   close()

      メールボックスをフラッシュし、必要ならばアンロックし、開いている
      ファイルを閉じます。 "Mailbox" サブクラスによっては何もしないこ
      ともあります。


"Maildir" オブジェクト
----------------------

class mailbox.Maildir(dirname, factory=None, create=True)

   Maildir 形式のメールボックスのための "Mailbox" のサブクラス。パラメ
   ータ *factory* は呼び出し可能オブジェクトで (バイナリモードで開かれ
   ているかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの
   表現を返すものです。 *factory* が "None" ならば、 "MaildirMessage"
   がデフォルトのメッセージ表現として使われます。 *create* が "True"
   ならばメールボックスが存在しないときには作成します。

   *create* が "True" で、パス *dirname* が存在する場合、ディレクトリ
   レイアウトを検証せずに既存の maildir として扱います。

   *path* ではなく *dirname* と命名される歴史的な理由のためです。

   Maildir はディレクトリ型のメールボックス形式でメール転送エージェン
   ト qmail 用に発明され、現在では多くの他のプログラムでもサポートされ
   ているものです。Maildir メールボックス中のメッセージは共通のディレ
   クトリ構造の下で個別のファイルに保存されます。このデザインにより、
   Maildir メールボックスは複数の無関係のプログラムからデータを失うこ
   となくアクセスしたり変更したりできます。そのためロックは不要です。

   Maildir メールボックスには三つのサブディレクトリ "tmp", "new",
   "cur" があります。メッセージはまず "tmp" サブディレクトリに瞬間的に
   作られた後、 "new" サブディレクトリに移動されて配送を完了します。メ
   ールユーザエージェントが引き続いて "cur" サブディレクトリにメッセー
   ジを移動しメッセージの状態についての情報をファイル名に追加される特
   別な "info" セクションに保存することができます。

   Courier メール転送エージェントによって導入されたスタイルのフォルダ
   もサポートされます。主たるメールボックスのサブディレクトリは "'.'"
   がファイル名の先頭であればフォルダと見なされます。フォルダ名は
   "Maildir" によって先頭の "'.'" を除いて表現されます。各フォルダはま
   た Maildir メールボックスですがさらにフォルダを含むことはできません
   。その代わり、論理的包含関係は例えば "Archived.2005.07" のような
   "'.'" を使ったレベル分けで表わされます。

   colon

      本来の Maildir 仕様ではある種のメッセージのファイル名にコロン
      ("':'") を使う必要があります。しかしながら、オペレーティングシス
      テムによってはこの文字をファイル名に含めることができないことがあ
      ります。そういった環境で Maildir のような形式を使いたい場合、代
      わりに使われる文字を指定する必要があります。感嘆符 ("'!'") を使
      うのが一般的な選択です。以下の例を見てください:

         import mailbox
         mailbox.Maildir.colon = '!'

      "colon" 属性はインスタンスごとにセットしても構いません。

   "Maildir" インスタンスには "Mailbox" の全てのメソッドに加え以下のメ
   ソッドもあります:

   list_folders()

      全てのフォルダ名のリストを返します。

   get_folder(folder)

      名前が *folder* であるフォルダを表わす "Maildir" インスタンスを
      返します。そのようなフォルダが存在しなければ
      "NoSuchMailboxError" 例外が送出されます。

   add_folder(folder)

      名前が *folder* であるフォルダを作り、それを表わす "Maildir" イ
      ンスタンスを返します。

   remove_folder(folder)

      名前が *folder* であるフォルダを削除します。もしフォルダに一つで
      もメッセージが含まれていれば "NotEmptyError" 例外が送出されフォ
      ルダは削除されません。

   clean()

      過去36時間以内にアクセスされなかったメールボックス内の一時ファイ
      ルを削除します。Maildir 仕様はメールを読むプログラムはときどきこ
      の作業をすべきだとしています。

   "Maildir" で実装された "Mailbox" のいくつかのメソッドには特別な注意
   が必要です:

   add(message)
   __setitem__(key, message)
   update(arg)

      警告:

        これらのメソッドは一意的なファイル名をプロセスIDに基づいて生成
        します。複数のスレッドを使う場合は、同じメールボックスを同時に
        操作しないようにスレッド間で調整しておかないと検知されない名前
        の衝突が起こりメールボックスを壊すかもしれません。

   flush()

      Maildir メールボックスへの変更は即時に適用されるので、このメソッ
      ドは何もしません。

   lock()
   unlock()

      Maildir メールボックスはロックをサポート(または要求)しないので、
      このメソッドは何もしません。

   close()

      "Maildir" インスタンスは開いたファイルを保持しませんしメールボッ
      クスはロックをサポートしませんので、このメソッドは何もしません。

   get_file(key)

      ホストのプラットフォームによっては、返されたファイルが開いている
      間、元になったメッセージを変更したり削除したりできない場合があり
      ます。

参考:

  Courier の maildir マニュアルページ
     Maildir 形式の仕様。フォルダをサポートする一般的な拡張について記
     述されています。

  Using maildir format
     Maildir 形式の発明者による注意書き。更新された名前生成規則と
     "info" の解釈についても含まれます。


"mbox" オブジェクト
-------------------

class mailbox.mbox(path, factory=None, create=True)

   mbox 形式のメールボックスのための "Mailbox" のサブクラス。パラメー
   タ *factory* は呼び出し可能オブジェクトで (バイナリモードで開かれて
   いるかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表
   現を返すものです。 *factory* が "None" ならば、 "mboxMessage" がデ
   フォルトのメッセージ表現として使われます。 *create* が "True" なら
   ばメールボックスが存在しないときには作成します。

   mbox 形式は Unixシステム上でメールを保存する古くからある形式です。
   mbox メールボックスでは全てのメッセージが一つのファイルに保存されて
   おりそれぞれのメッセージは "From " という5文字で始まる行を先頭に付
   けられています。

   mbox 形式には幾つかのバリエーションがあり、それぞれオリジナルの形式
   にあった欠点を克服すると主張しています。互換性のために、 "mbox" は
   オリジナルの(時に *mboxo* と呼ばれる) 形式を実装しています。すなわ
   ち、 *Content-Length* ヘッダはもしあっても無視され、メッセージのボ
   ディにある行頭の "From " はメッセージを保存する際に ">From " に変換
   されますが、この ">From " は読み出し時にも "From " に変換されません
   。

   "mbox" で実装された "Mailbox" のいくつかのメソッドには特別な注意が
   必要です:

   get_bytes(key, from_=False)

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   get_file(key, from_=False)

      "mbox" インスタンスに対し "flush()" や meth:*~Mailbox.close* を
      呼び出した後でファイルを使用すると予期しない結果を引き起こしたり
      例外が送出されたりすることがあります。

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   get_string(key, from_=False)

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   lock()
   unlock()

      3種類のロック機構が使われます --- ドットロッキングと、もし使用可
      能ならば "flock()" と "lockf()" システムコールです。

参考:

  tin の mbox マニュアルページ
     mbox 形式の仕様でロックについての詳細を含む。

  Configuring Netscape Mail on Unix: Why The Content-Length Format is
  Bad
     バリエーションの一つではなくオリジナルの mbox を使う理由。

  "mbox" は相互に互換性を持たないいくつかのメールボックスフォーマット
  の集まりです
     mbox バリエーションの歴史。


"MH" オブジェクト
-----------------

class mailbox.MH(path, factory=None, create=True)

   MH 形式のメールボックスのための "Mailbox" のサブクラス。パラメータ
   *factory* は呼び出し可能オブジェクトで (バイナリモードで開かれてい
   るかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表現
   を返すものです。 *factory* が "None" ならば、 "MHMessage" がデフォ
   ルトのメッセージ表現として使われます。 *create* が "True" ならばメ
   ールボックスが存在しないときには作成します。

   MH はディレクトリに基づいたメールボックス形式で MH Message Handling
   System というメールユーザエージェントのために発明されました。 MH メ
   ールボックス中のそれぞれのメッセージは一つのファイルとして収められ
   ています。 MH メールボックスにはメッセージの他に別の MH メールボッ
   クス (*フォルダ* と呼ばれます)を含んでもかまいません。フォルダは無
   限にネストできます。 MH メールボックスにはもう一つ *シーケンス* と
   いう名前付きのリストでメッセージをサブフォルダに移動することなく論
   理的に分類するものがサポートされています。シーケンスは各フォルダの
   ".mh_sequences" というファイルで定義されます。

   "MH" クラスは MH メールボックスを操作しますが、 **mh** の動作の全て
   を模倣しようとはしていません。特に、 **mh** が状態と設定を保存する
   "context" や ".mh_profile" といったファイルは書き換えませんし影響も
   受けません。

   "MH" インスタンスには "Mailbox" の全てのメソッドの他に次のメソッド
   があります:

   list_folders()

      全てのフォルダ名のリストを返します。

   get_folder(folder)

      *folder* という名前のフォルダを表わす "MH" インスタンスを返しま
      す。もしフォルダが存在しなければ "NoSuchMailboxError" 例外が送出
      されます。

   add_folder(folder)

      *folder* という名前のフォルダを作成し、それを表わす "MH" インス
      タンスを返します。

   remove_folder(folder)

      名前が *folder* であるフォルダを削除します。もしフォルダに一つで
      もメッセージが含まれていれば "NotEmptyError" 例外が送出されフォ
      ルダは削除されません。

   get_sequences()

      シーケンス名をキーのリストに対応付ける辞書を返します。シーケンス
      が一つもなければ空の辞書を返します。

   set_sequences(sequences)

      メールボックス中のシーケンスを "get_sequences()" で返されるよう
      な名前とキーのリストを対応付ける辞書 *sequences* に基づいて再定
      義します。

   pack()

      番号付けの間隔を詰める必要に応じてメールボックス中のメッセージの
      名前を付け替えます。シーケンスのリストのエントリもそれに応じて更
      新されます。

      注釈:

        既に発行されたキーはこの操作によって無効になるのでそれ以降使っ
        てはなりません。

   "MH" で実装された "Mailbox" のいくつかのメソッドには特別な注意が必
   要です:

   remove(key)
   __delitem__(key)
   discard(key)

      これらのメソッドはメッセージを直ちに削除します。名前の前にコンマ
      を付加してメッセージに削除の印を付けるという MH の規約は使いませ
      ん。

   lock()
   unlock()

      3種類のロック機構が使われます --- ドットロッキングと、もし使用可
      能ならば "flock()" と "lockf()" システムコールです。 MH メールボ
      ックスに対するロックとは ".mh_sequences" のロックと、それが影響
      を与える操作中だけの個々のメッセージファイルに対するロックを意味
      します。

   get_file(key)

      ホストプラットフォームにより、ファイルが開かれたままの場合はメッ
      セージを削除することができない場合があります。

   flush()

      MH メールボックスへの変更は即時に適用されますのでこのメソッドは
      何もしません。

   close()

      "MH" インスタンスは開いたファイルを保持しませんのでこのメソッド
      は "unlock()" と同じです。

参考:

  nmh - Message Handling System
     **mh** の改良版である **nmh** のホームページ。

  MH & nmh: Email for Users & Programmers
     GPLライセンスの **mh** および **nmh** の本で、このメールボックス
     形式についての情報があります。


"Babyl" オブジェクト
--------------------

class mailbox.Babyl(path, factory=None, create=True)

   Babyl 形式のメールボックスのための "Mailbox" のサブクラス。パラメー
   タ *factory* は呼び出し可能オブジェクトで (バイナリモードで開かれて
   いるかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表
   現を返すものです。 *factory* が "None" ならば、 "BabylMessage" がデ
   フォルトのメッセージ表現として使われます。 *create* が "True" なら
   ばメールボックスが存在しないときには作成します。

   Babyl は単一ファイルのメールボックス形式で Emacs に付属している
   Rmail メールユーザエージェントで使われているものです。メッセージの
   開始は Control-Underscore ("'\037'") および Control-L ("'\014'") の
   二文字を含む行で示されます。メッセージの終了は次のメッセージの開始
   または最後のメッセージの場合には Control-Underscore を含む行で示さ
   れます。

   Babyl メールボックス中のメッセージには二つのヘッダのセット、オリジ
   ナルヘッダといわゆる可視ヘッダ、があります。可視ヘッダは典型的には
   オリジナルヘッダの一部を分り易いように再整形したり短くしたりしたも
   のです。 Babyl メールボックス中のそれぞれのメッセージには *ラベル*
   というそのメッセージについての追加情報を記録する短い文字列のリスト
   を伴い、メールボックス中に見出されるユーザが定義した全てのラベルの
   リストは Babyl オプションセクションに保持されます。

   "Babyl" インスタンスには "Mailbox" の全てのメソッドの他に次のメソッ
   ドがあります:

   get_labels()

      メールボックスで使われているユーザが定義した全てのラベルのリスト
      を返します。

      注釈:

        メールボックスにどのようなラベルが存在するかを決めるのに、
        Babyl オプションセクションのリストを参考にせず、実際のメッセー
        ジを捜索しますが、Babyl セクションもメールボックスが変更された
        ときにはいつでも更新されます。

   "Babyl" で実装された "Mailbox" のいくつかのメソッドには特別な注意が
   必要です:

   get_file(key)

      Babyl メールボックスにおいて、メッセージのヘッダはボディと繋がっ
      て格納されていません。ファイル風の表現を生成するために、ヘッダと
      ボディがファイルと同じ API を持つ "io.BytesIO" インスタンスに一
      緒にコピーされます。その結果、ファイル風オブジェクトは元にしてい
      るメールボックスとは真に独立していますが、文字列表現と比べてメモ
      リーを節約することにはなりません。

   lock()
   unlock()

      3種類のロック機構が使われます --- ドットロッキングと、もし使用可
      能ならば "flock()" と "lockf()" システムコールです。

参考:

  Format of Version 5 Babyl Files
     Babyl 形式の仕様。

  Reading Mail with Rmail
     Rmail のマニュアルで Babyl のセマンティクスについての情報も少しあ
     る。


"MMDF" オブジェクト
-------------------

class mailbox.MMDF(path, factory=None, create=True)

   MMDF 形式のメールボックスのための "Mailbox" のサブクラス。パラメー
   タ *factory* は呼び出し可能オブジェクトで (バイナリモードで開かれて
   いるかのように振る舞う)ファイル風メッセージ表現を受け付けて好みの表
   現を返すものです。 *factory* が "None" ならば、 "MMDFMessage" がデ
   フォルトのメッセージ表現として使われます。 *create* が "True" なら
   ばメールボックスが存在しないときには作成します。

   MMDF は単一ファイルのメールボックス形式で Multichannel Memorandum
   Distribution Facility というメール転送エージェント用に発明されたも
   のです。各メッセージは mbox と同様の形式で収められますが、前後を4つ
   の Control-A ("'\001'") を含む行で挟んであります。mbox 形式と同じよ
   うにそれぞれのメッセージの開始は "From " の5文字を含む行で示されま
   すが、それ以外の場所での "From " は格納の際 ">From " には変えられま
   せん。それは追加されたメッセージ区切りによって新たなメッセージの開
   始と見間違うことが避けられるからです。

   "MMDF" で実装された "Mailbox" のいくつかのメソッドには特別な注意が
   必要です:

   get_bytes(key, from_=False)

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   get_file(key, from_=False)

      "MMDF" インスタンスに対し "flush()" や meth:*~Mailbox.close* を
      呼び出した後でファイルを使用すると予期しない結果を引き起こしたり
      例外が送出されたりすることがあります。

      Note: This method has an extra parameter (*from_*) compared with
      other classes. The first line of an mbox file entry is the Unix
      "From " line. If *from_* is False, the first line of the file is
      dropped.

   lock()
   unlock()

      3種類のロック機構が使われます --- ドットロッキングと、もし使用可
      能ならば "flock()" と "lockf()" システムコールです。

参考:

  mmdf man page from tin
     ニュースリーダ tin のドキュメント中の MMDF 形式仕様。

  MMDF
     Multichannel Memorandum Distribution Facility についてのウィキペ
     ディアの記事。


"Message" オブジェクト
======================

class mailbox.Message(message=None)

   "email.message" モジュールの "Message" のサブクラス。
   "mailbox.Message" のサブクラスはメールボックス形式ごとの状態と動作
   を追加します。

   *message* が省略された場合、新しいインスタンスはデフォルトの空の状
   態で生成されます。 *message* が "email.message.Message" インスタン
   スならばその内容がコピーされます。さらに、 *message* が "Message"
   インスタンスならば、形式固有の情報も可能な限り変換されます。
   *message* が文字列かバイト列またはファイルならば、読まれ解析される
   べき **RFC 2822** 準拠のメッセージを含んでいなければなりません。フ
   ァイルはバイナリモードで開かれているべきですが、後方互換性のためテ
   キストモードファイルも受け付けます。

   サブクラスにより提供される形式ごとの状態と動作は様々ですが、一般に
   或るメールボックスに固有のものでないプロパティだけがサポートされま
   す(おそらくプロパティのセットはメールボックス形式ごとに固有でしょう
   が)。例えば、単一ファイルメールボックス形式におけるファイルオフセッ
   トやディレクトリ式メールボックス形式におけるファイル名は保持されま
   せん、というのもそれらは元々のメールボックスにしか適用できないから
   です。しかし、メッセージがユーザに読まれたかどうかあるいは重要だと
   マークされたかどうかという状態は保持されます、というのはそれらはメ
   ッセージ自体に適用されるからです。

   "Mailbox" インスタンスを使って取得したメッセージを表現するのに
   "Message" インスタンスが使われなければいけないとは要求していません
   。ある種の状況では "Message" による表現を生成するのに必要な時間やメ
   モリーが受け入れられないこともあります。そういった状況では
   "Mailbox" インスタンスは文字列やファイル風オブジェクトの表現も提供
   できますし、 "Mailbox" インスタンスを初期化する際にメッセージファク
   トリーを指定することもできます。


"MaildirMessage" オブジェクト
-----------------------------

class mailbox.MaildirMessage(message=None)

   Maildir 固有の動作をするメッセージ。引数 *message* は "Message" の
   コンストラクタと同じ意味を持ちます。

   通常、メールユーザエージェントは "new" サブディレクトリにある全ての
   メッセージをユーザが最初にメールボックスを開くか閉じるかした後で
   "cur" サブディレクトリに移動し、メッセージが実際に読まれたかどうか
   を記録します。 "cur" にある各メッセージには状態情報を保存するファイ
   ル名に付け加えられた "info" セクションがあります。(メールリーダの中
   には "info" セクションを "new" にあるメッセージに付けることもありま
   す。) "info" セクションには二つの形式があります。一つは "2," の後に
   標準化されたフラグのリストを付けたもの (たとえば "2,FR")、もう一つ
   は "1," の後にいわゆる実験的情報を付け加えるものです。 Maildir の標
   準的なフラグは以下の通りです:

   +--------+-----------+----------------------------------+
   | Flag   | 意味      | 説明                             |
   |========|===========|==================================|
   | D      | ドラフト  | 作成中                           |
   |        | (Draft)   |                                  |
   +--------+-----------+----------------------------------+
   | F      | フラグ付  | 重要とされたもの                 |
   |        | き        |                                  |
   |        | (Flagged) |                                  |
   +--------+-----------+----------------------------------+
   | P      | 通過      | 転送、再送またはバウンス         |
   |        | (Passed)  |                                  |
   +--------+-----------+----------------------------------+
   | R      | 返答済み  | 返答されたもの                   |
   |        | (Replied) |                                  |
   +--------+-----------+----------------------------------+
   | S      | 既読      | 読んだもの                       |
   |        | (Seen)    |                                  |
   +--------+-----------+----------------------------------+
   | T      | ごみ      | 削除予定とされたもの             |
   |        | (Trashed) |                                  |
   +--------+-----------+----------------------------------+

   "MaildirMessage" インスタンスは以下のメソッドを提供します:

   get_subdir()

      "new" (メッセージが "new" サブディレクトリに保存されるべき場合)
      または "cur" (メッセージが "cur" サブディレクトリに保存されるべ
      き場合)のどちらかを返します。

      注釈:

        A message is typically moved from "new" to "cur" after its
        mailbox has been accessed, whether or not the message is has
        been read. A message "msg" has been read if ""S" in
        msg.get_flags()" is "True".

   set_subdir(subdir)

      メッセージが保存されるべきサブディレクトリをセットします。パラメ
      ータ *subdir* は "new" または "cur" のいずれかでなければなりませ
      ん。

   get_flags()

      現在セットされているフラグを特定する文字列を返します。メッセージ
      が標準 Maildir 形式に準拠しているならば、結果はアルファベット順
      に並べられたゼロまたは1回の "'D'"、"'F'"、"'P'"、"'R'"、"'S'"、
      "'T'" をつなげたものです。空文字列が返されるのはフラグが一つもな
      い場合、または "info" が実験的セマンティクスを使っている場合です
      。

   set_flags(flags)

      *flags* で指定されたフラグをセットし、他のフラグは下ろします。

   add_flag(flag)

      *flag* で指定されたフラグをセットしますが他のフラグは変えません
      。一度に二つ以上のフラグをセットすることは、*flag* に2文字以上の
      文字列を指定すればできます。現在の "info" はフラグの代わりに実験
      的情報を使っていても上書きされます。

   remove_flag(flag)

      *flag* で指定されたフラグを下ろしますが他のフラグは変えません。
      一度に二つ以上のフラグを取り除くことは、*flag* に2文字以上の文字
      列を指定すればできます。"info" がフラグの代わりに実験的情報を使
      っている場合は現在の "info" は書き換えられません。

   get_date()

      メッセージの配送日時をエポックからの秒数を表わす浮動小数点数で返
      します。

   set_date(date)

      メッセージの配送日時を *date* にセットします。*date* はエポック
      からの秒数を表わす浮動小数点数です。

   get_info()

      メッセージの "info" を含む文字列を返します。このメソッドは実験的
      (即ちフラグのリストでない) "info" にアクセスし、また変更するのに
      役立ちます。

   set_info(info)

      "info" に文字列 *info* をセットします。

"MaildirMessage" インスタンスが "mboxMessage" や "MMDFMessage" のイン
スタンスに基づいて生成されるとき、 *Status* および *X-Status* ヘッダは
省かれ以下の変換が行われます:

+----------------------+------------------------------------------------+
| 結果の状態           | "mboxMessage" または "MMDFMessage" の状態      |
|======================|================================================|
| "cur" サブディレクト | O フラグ                                       |
| リ                   |                                                |
+----------------------+------------------------------------------------+
| F フラグ             | F フラグ                                       |
+----------------------+------------------------------------------------+
| R フラグ             | A フラグ                                       |
+----------------------+------------------------------------------------+
| S フラグ             | R フラグ                                       |
+----------------------+------------------------------------------------+
| T フラグ             | D フラグ                                       |
+----------------------+------------------------------------------------+

"MaildirMessage" インスタンスが "MHMessage" インスタンスに基づいて生成
されるとき、以下の変換が行われます:

+---------------------------------+----------------------------+
| 結果の状態                      | "MHMessage" の状態         |
|=================================|============================|
| "cur" サブディレクトリ          | "unseen" シーケンス        |
+---------------------------------+----------------------------+
| "cur" サブディレクトリおよび S  | "unseen" シーケンス無し    |
| フラグ                          |                            |
+---------------------------------+----------------------------+
| F フラグ                        | "flagged" シーケンス       |
+---------------------------------+----------------------------+
| R フラグ                        | "replied" シーケンス       |
+---------------------------------+----------------------------+

"MaildirMessage" インスタンスが "BabylMessage" インスタンスに基づいて
生成されるとき、以下の変換が行われます:

+---------------------------------+---------------------------------+
| 結果の状態                      | "BabylMessage" の状態           |
|=================================|=================================|
| "cur" サブディレクトリ          | "unseen" ラベル                 |
+---------------------------------+---------------------------------+
| "cur" サブディレクトリおよび S  | "unseen" ラベル無し             |
| フラグ                          |                                 |
+---------------------------------+---------------------------------+
| P フラグ                        | "forwarded" または "resent" ラ  |
|                                 | ベル                            |
+---------------------------------+---------------------------------+
| R フラグ                        | "answered" ラベル               |
+---------------------------------+---------------------------------+
| T フラグ                        | "deleted" ラベル                |
+---------------------------------+---------------------------------+


"mboxMessage" オブジェクト
--------------------------

class mailbox.mboxMessage(message=None)

   mbox 固有の動作をするメッセージ。引数 *message* は "Message" のコン
   ストラクタと同じ意味を持ちます。

   mbox メールボックス中のメッセージは単一ファイルにまとめて格納されて
   います。送り主のエンベロープアドレスおよび配送日時は通常メッセージ
   の開始を示す "From " から始まる行に記録されますが、正確なフォーマッ
   トに関しては mbox の実装ごとに大きな違いがあります。メッセージの状
   態を示すフラグ、たとえば読んだかどうかあるいは重要だとマークを付け
   られているかどうかといったようなもの、は典型的には *Status* および
   *X-Status* に収められます。

   規定されている mbox メッセージのフラグは以下の通りです:

   +--------+------------+----------------------------------+
   | Flag   | 意味       | 説明                             |
   |========|============|==================================|
   | R      | 読んだもの | 読んだもの                       |
   +--------+------------+----------------------------------+
   | O      | 古い(Old)  | 以前に MUA に発見された          |
   +--------+------------+----------------------------------+
   | D      | 削除       | 削除予定とされたもの             |
   |        | (Deleted)  |                                  |
   +--------+------------+----------------------------------+
   | F      | フラグ付き | 重要とされたもの                 |
   |        | (Flagged)  |                                  |
   +--------+------------+----------------------------------+
   | A      | 返答済み   | 返答されたもの                   |
   |        | (Answered) |                                  |
   +--------+------------+----------------------------------+

   "R" および "O" フラグは *Status* ヘッダに記録され、 "D"、"F"、"A"
   フラグは *X-Status* ヘッダに記録されます。フラグとヘッダは通常記述
   された順番に出現します。

   "mboxMessage" インスタンスは以下のメソッドを提供します:

   get_from()

      mbox メールボックスのメッセージの開始を示す "From " 行を表わす文
      字列を返します。先頭の "From " および末尾の改行は含まれません。

   set_from(from_, time_=None)

      "From " 行を *from_* にセットします。 *from_* は先頭の "From "
      や末尾の改行を含まない形で指定しなければなりません。利便性のため
      に、 *time_* を指定して適切に整形して *from_* に追加させることが
      できます。 *time_* を指定する場合、それは "time.struct_time" イ
      ンスタンス、 "time.strftime()" に渡すのに適したタプル、または
      "True" (この場合 "time.gmtime()" を使います) のいずれかでなけれ
      ばなりません。

   get_flags()

      現在セットされているフラグを特定する文字列を返します。メッセージ
      が規定された形式に準拠しているならば、結果は次の順に並べられた 0
      回か1回の "'R'"、"'O'"、"'D'"、"'F'"、"'A'" です。

   set_flags(flags)

      *flags* で指定されたフラグをセットして、他のフラグは下ろします。
      *flags* は並べられたゼロまたは1回の "'R'"、"'O'"、"'D'"、"'F'"、
      "'A'" です。

   add_flag(flag)

      *flag* で指定されたフラグをセットしますが他のフラグは変えません
      。一度に二つ以上のフラグをセットすることは、*flag* に2文字以上の
      文字列を指定すればできます。

   remove_flag(flag)

      *flag* で指定されたフラグを下ろしますが他のフラグは変えません。
      一二つ以上のフラグを取り除くことは、*flag* に2文字以上の文字列を
      指定すればできます。

"mboxMessage" インスタンスが "MaildirMessage" インスタンスに基づいて生
成されるとき、 "MaildirMessage" インスタンスの配送日時に基づいて "From
" 行が作り出され、次の変換が行われます:

+-------------------+---------------------------------+
| 結果の状態        | "MaildirMessage" の状態         |
|===================|=================================|
| R フラグ          | S フラグ                        |
+-------------------+---------------------------------+
| O フラグ          | "cur" サブディレクトリ          |
+-------------------+---------------------------------+
| D フラグ          | T フラグ                        |
+-------------------+---------------------------------+
| F フラグ          | F フラグ                        |
+-------------------+---------------------------------+
| A フラグ          | R フラグ                        |
+-------------------+---------------------------------+

"mboxMessage" インスタンスが "MHMessage" インスタンスに基づいて生成さ
れるとき、以下の変換が行われます:

+---------------------+----------------------------+
| 結果の状態          | "MHMessage" の状態         |
|=====================|============================|
| R フラグおよび O フ | "unseen" シーケンス無し    |
| ラグ                |                            |
+---------------------+----------------------------+
| O フラグ            | "unseen" シーケンス        |
+---------------------+----------------------------+
| F フラグ            | "flagged" シーケンス       |
+---------------------+----------------------------+
| A フラグ            | "replied" シーケンス       |
+---------------------+----------------------------+

"mboxMessage" インスタンスが "BabylMessage" インスタンスに基づいて生成
されるとき、以下の変換が行われます:

+---------------------+-------------------------------+
| 結果の状態          | "BabylMessage" の状態         |
|=====================|===============================|
| R フラグおよび O フ | "unseen" ラベル無し           |
| ラグ                |                               |
+---------------------+-------------------------------+
| O フラグ            | "unseen" ラベル               |
+---------------------+-------------------------------+
| D フラグ            | "deleted" ラベル              |
+---------------------+-------------------------------+
| A フラグ            | "answered" ラベル             |
+---------------------+-------------------------------+

"mboxMessage" インスタンスが "MMDFMessage" インスタンスに基づいて生成
されるとき、"From " 行はコピーされ全てのフラグは直接対応します:

+-------------------+------------------------------+
| 結果の状態        | "MMDFMessage" の状態         |
|===================|==============================|
| R フラグ          | R フラグ                     |
+-------------------+------------------------------+
| O フラグ          | O フラグ                     |
+-------------------+------------------------------+
| D フラグ          | D フラグ                     |
+-------------------+------------------------------+
| F フラグ          | F フラグ                     |
+-------------------+------------------------------+
| A フラグ          | A フラグ                     |
+-------------------+------------------------------+


"MHMessage" オブジェクト
------------------------

class mailbox.MHMessage(message=None)

   MH 固有の動作をするメッセージ。引数 *message* は "Message" のコンス
   トラクタと同じ意味を持ちます。

   MH メッセージは伝統的な意味あいにおいてマークやフラグをサポートしま
   せん。しかし、MH メッセージにはシーケンスがあり任意のメッセージを論
   理的にグループ分けできます。いくつかのメールソフト(標準の **mh** や
   **nmh** はそうではありませんが) は他の形式におけるフラグとほぼ同じ
   ようにシーケンスを使います:

   +------------+--------------------------------------------+
   | シーケンス | 説明                                       |
   |============|============================================|
   | unseen     | 読んではいないが既にMUAに見つけられている  |
   +------------+--------------------------------------------+
   | replied    | 返答されたもの                             |
   +------------+--------------------------------------------+
   | flagged    | 重要とされたもの                           |
   +------------+--------------------------------------------+

   "MHMessage" インスタンスは以下のメソッドを提供します:

   get_sequences()

      このメッセージを含むシーケンスの名前のリストを返す。

   set_sequences(sequences)

      このメッセージを含むシーケンスのリストをセットする。

   add_sequence(sequence)

      *sequence* をこのメッセージを含むシーケンスのリストに追加する。

   remove_sequence(sequence)

      *sequence* をこのメッセージを含むシーケンスのリストから除く。

"MHMessage" インスタンスが "MaildirMessage" インスタンスに基づいて生成
されるとき、以下の変換が行われます:

+----------------------+---------------------------------+
| 結果の状態           | "MaildirMessage" の状態         |
|======================|=================================|
| "unseen" シーケンス  | S フラグ無し                    |
+----------------------+---------------------------------+
| "replied" シーケンス | R フラグ                        |
+----------------------+---------------------------------+
| "flagged" シーケンス | F フラグ                        |
+----------------------+---------------------------------+

"MHMessage" インスタンスが "mboxMessage" や "MMDFMessage" のインスタン
スに基づいて生成されるとき、 *Status* および *X-Status* ヘッダは省かれ
以下の変換が行われます:

+----------------------+------------------------------------------------+
| 結果の状態           | "mboxMessage" または "MMDFMessage" の状態      |
|======================|================================================|
| "unseen" シーケンス  | R フラグ無し                                   |
+----------------------+------------------------------------------------+
| "replied" シーケンス | A フラグ                                       |
+----------------------+------------------------------------------------+
| "flagged" シーケンス | F フラグ                                       |
+----------------------+------------------------------------------------+

"MHMessage" インスタンスが "BabylMessage" インスタンスに基づいて生成さ
れるとき、以下の変換が行われます:

+----------------------+-------------------------------+
| 結果の状態           | "BabylMessage" の状態         |
|======================|===============================|
| "unseen" シーケンス  | "unseen" ラベル               |
+----------------------+-------------------------------+
| "replied" シーケンス | "answered" ラベル             |
+----------------------+-------------------------------+


"BabylMessage" オブジェクト
---------------------------

class mailbox.BabylMessage(message=None)

   Babyl 固有の動作をするメッセージ。引数 *message* は "Message" のコ
   ンストラクタと同じ意味を持ちます。

   ある種のメッセージラベルは *アトリビュート* と呼ばれ、規約により特
   別な意味が与えられています。アトリビュートは以下の通りです:

   +-------------+--------------------------------------------+
   | ラベル      | 説明                                       |
   |=============|============================================|
   | unseen      | 読んではいないが既にMUAに見つけられている  |
   +-------------+--------------------------------------------+
   | deleted     | 削除予定とされたもの                       |
   +-------------+--------------------------------------------+
   | filed       | 他のファイルまたはメールボックスにコピーさ |
   |             | れた                                       |
   +-------------+--------------------------------------------+
   | answered    | 返答されたもの                             |
   +-------------+--------------------------------------------+
   | forwarded   | 転送された                                 |
   +-------------+--------------------------------------------+
   | edited      | ユーザによって変更された                   |
   +-------------+--------------------------------------------+
   | resent      | 再送された                                 |
   +-------------+--------------------------------------------+

   デフォルトでは Rmail は可視ヘッダのみ表示します。 "BabylMessage" ク
   ラスはしかし、オリジナルヘッダをより完全だという理由で使います。可
   視ヘッダは望むならそのように指示してアクセスすることができます。

   "BabylMessage" インスタンスは以下のメソッドを提供します:

   get_labels()

      メッセージに付いているラベルのリストを返します。

   set_labels(labels)

      メッセージに付いているラベルのリストを *labels* にセットします。

   add_label(label)

      メッセージに付いているラベルのリストに *label* を追加します。

   remove_label(label)

      メッセージに付いているラベルのリストから *label* を削除します。

   get_visible()

      ヘッダがメッセージの可視ヘッダでありボディが空であるような
      "Message" インスタンスを返します。

   set_visible(visible)

      メッセージの可視ヘッダを *visible* のヘッダと同じにセットします
      。引数 *visible* は "Message" インスタンスまたは
      "email.message.Message" インスタンス、文字列、ファイル風オブジェ
      クト(テキストモードで開かれてなければなりません)のいずれかです。

   update_visible()

      "BabylMessage" インスタンスのオリジナルヘッダが変更されたとき、
      可視ヘッダは自動的に対応して変更されるわけではありません。このメ
      ソッドは可視ヘッダを以下のように更新します。対応するオリジナルヘ
      ッダのある可視ヘッダはオリジナルヘッダの値がセットされます。対応
      するオリジナルヘッダの無い可視ヘッダは除去されます。そして、オリ
      ジナルヘッダにあって可視ヘッダに無い *Date* 、 *From* 、 *Reply-
      To* 、 *To* 、 *CC* 、 *Subject* は可視ヘッダに追加されます。

"BabylMessage" インスタンスが "MaildirMessage" インスタンスに基づいて
生成されるとき、以下の変換が行われます:

+---------------------+---------------------------------+
| 結果の状態          | "MaildirMessage" の状態         |
|=====================|=================================|
| "unseen" ラベル     | S フラグ無し                    |
+---------------------+---------------------------------+
| "deleted" ラベル    | T フラグ                        |
+---------------------+---------------------------------+
| "answered" ラベル   | R フラグ                        |
+---------------------+---------------------------------+
| "forwarded" ラベル  | P フラグ                        |
+---------------------+---------------------------------+

"BabylMessage" インスタンスが "mboxMessage" や "MMDFMessage" のインス
タンスに基づいて生成されるとき、 *Status* および *X-Status* ヘッダは省
かれ以下の変換が行われます:

+--------------------+------------------------------------------------+
| 結果の状態         | "mboxMessage" または "MMDFMessage" の状態      |
|====================|================================================|
| "unseen" ラベル    | R フラグ無し                                   |
+--------------------+------------------------------------------------+
| "deleted" ラベル   | D フラグ                                       |
+--------------------+------------------------------------------------+
| "answered" ラベル  | A フラグ                                       |
+--------------------+------------------------------------------------+

"BabylMessage" インスタンスが "MHMessage" インスタンスに基づいて生成さ
れるとき、以下の変換が行われます:

+--------------------+----------------------------+
| 結果の状態         | "MHMessage" の状態         |
|====================|============================|
| "unseen" ラベル    | "unseen" シーケンス        |
+--------------------+----------------------------+
| "answered" ラベル  | "replied" シーケンス       |
+--------------------+----------------------------+


"MMDFMessage" オブジェクト
--------------------------

class mailbox.MMDFMessage(message=None)

   MMDF 固有の動作をするメッセージ。引数 *message* は "Message" のコン
   ストラクタと同じ意味を持ちます。

   mbox メールボックスのメッセージと同様に、MMDF メッセージは送り主の
   アドレスと配送日時が最初の "From " で始まる行に記録されています。同
   様に、メッセージの状態を示すフラグは通常 *Status* および *X-Status*
   ヘッダに収められています。

   よく使われる MMDF メッセージのフラグは mbox メッセージのものと同一
   で以下の通りです:

   +--------+------------+----------------------------------+
   | Flag   | 意味       | 説明                             |
   |========|============|==================================|
   | R      | 読んだもの | 読んだもの                       |
   +--------+------------+----------------------------------+
   | O      | 古い(Old)  | 以前に MUA に発見された          |
   +--------+------------+----------------------------------+
   | D      | 削除       | 削除予定とされたもの             |
   |        | (Deleted)  |                                  |
   +--------+------------+----------------------------------+
   | F      | フラグ付き | 重要とされたもの                 |
   |        | (Flagged)  |                                  |
   +--------+------------+----------------------------------+
   | A      | 返答済み   | 返答されたもの                   |
   |        | (Answered) |                                  |
   +--------+------------+----------------------------------+

   "R" および "O" フラグは *Status* ヘッダに記録され、 "D"、"F"、"A"
   フラグは *X-Status* ヘッダに記録されます。フラグとヘッダは通常記述
   された順番に出現します。

   "MMDFMessage" インスタンスは "mboxMessage" インスタンスと同一の以下
   のメソッドを提供します:

   get_from()

      mbox メールボックスのメッセージの開始を示す "From " 行を表わす文
      字列を返します。先頭の "From " および末尾の改行は含まれません。

   set_from(from_, time_=None)

      "From " 行を *from_* にセットします。 *from_* は先頭の "From "
      や末尾の改行を含まない形で指定しなければなりません。利便性のため
      に、 *time_* を指定して適切に整形して *from_* に追加させることが
      できます。 *time_* を指定する場合、それは "time.struct_time" イ
      ンスタンス、 "time.strftime()" に渡すのに適したタプル、または
      "True" (この場合 "time.gmtime()" を使います) のいずれかでなけれ
      ばなりません。

   get_flags()

      現在セットされているフラグを特定する文字列を返します。メッセージ
      が規定された形式に準拠しているならば、結果は次の順に並べられた 0
      回か1回の "'R'"、"'O'"、"'D'"、"'F'"、"'A'" です。

   set_flags(flags)

      *flags* で指定されたフラグをセットして、他のフラグは下ろします。
      *flags* は並べられたゼロまたは1回の "'R'"、"'O'"、"'D'"、"'F'"、
      "'A'" です。

   add_flag(flag)

      *flag* で指定されたフラグをセットしますが他のフラグは変えません
      。一度に二つ以上のフラグをセットすることは、*flag* に2文字以上の
      文字列を指定すればできます。

   remove_flag(flag)

      *flag* で指定されたフラグを下ろしますが他のフラグは変えません。
      一二つ以上のフラグを取り除くことは、*flag* に2文字以上の文字列を
      指定すればできます。

"MMDFMessage" インスタンスが "MaildirMessage" インスタンスに基づいて生
成されるとき、"From"行が "MaildirMessage" インスタンスの配信日をもとに
生成され、以下の変換が行われます:

+-------------------+---------------------------------+
| 結果の状態        | "MaildirMessage" の状態         |
|===================|=================================|
| R フラグ          | S フラグ                        |
+-------------------+---------------------------------+
| O フラグ          | "cur" サブディレクトリ          |
+-------------------+---------------------------------+
| D フラグ          | T フラグ                        |
+-------------------+---------------------------------+
| F フラグ          | F フラグ                        |
+-------------------+---------------------------------+
| A フラグ          | R フラグ                        |
+-------------------+---------------------------------+

 "MMDFMessage" インスタンスが "MHMessage" インスタンスに基づいて生成さ
れるとき、以下の変換が行われます:

+---------------------+----------------------------+
| 結果の状態          | "MHMessage" の状態         |
|=====================|============================|
| R フラグおよび O フ | "unseen" シーケンス無し    |
| ラグ                |                            |
+---------------------+----------------------------+
| O フラグ            | "unseen" シーケンス        |
+---------------------+----------------------------+
| F フラグ            | "flagged" シーケンス       |
+---------------------+----------------------------+
| A フラグ            | "replied" シーケンス       |
+---------------------+----------------------------+

"MMDFMessage" インスタンスが "BabylMessage" インスタンスに基づいて生成
されるとき、以下の変換が行われます:

+---------------------+-------------------------------+
| 結果の状態          | "BabylMessage" の状態         |
|=====================|===============================|
| R フラグおよび O フ | "unseen" ラベル無し           |
| ラグ                |                               |
+---------------------+-------------------------------+
| O フラグ            | "unseen" ラベル               |
+---------------------+-------------------------------+
| D フラグ            | "deleted" ラベル              |
+---------------------+-------------------------------+
| A フラグ            | "answered" ラベル             |
+---------------------+-------------------------------+

"MMDFMessage" インスタンスが "mboxMessage" インスタンスに基づいて生成
されるとき、"From"行がコピーされ、全てのフラグが直接対応します:

+-------------------+------------------------------+
| 結果の状態        | "mboxMessage" の状態         |
|===================|==============================|
| R フラグ          | R フラグ                     |
+-------------------+------------------------------+
| O フラグ          | O フラグ                     |
+-------------------+------------------------------+
| D フラグ          | D フラグ                     |
+-------------------+------------------------------+
| F フラグ          | F フラグ                     |
+-------------------+------------------------------+
| A フラグ          | A フラグ                     |
+-------------------+------------------------------+


例外
====

"mailbox" モジュールでは以下の例外クラスが定義されています:

exception mailbox.Error

   他の全てのモジュール固有の例外の基底クラス。

exception mailbox.NoSuchMailboxError

   メールボックスがあると思っていたが見つからなかった場合に送出されま
   す。これはたとえば "Mailbox" のサブクラスを存在しないパスでインスタ
   ンス化しようとしたとき(かつ *create* パラメータは "False" であった
   場合)、あるいは存在しないフォルダを開こうとした時などに発生します。

exception mailbox.NotEmptyError

   メールボックスが空であることを期待されているときに空でない場合、た
   とえばメッセージの残っているフォルダを削除しようとした時などに送出
   されます。

exception mailbox.ExternalClashError

   メールボックスに関係したある条件がプログラムの制御を外れてそれ以上
   作業を続けられなくなった場合、たとえば他のプログラムが既に保持して
   いるロックを取得しようとして失敗したとき、あるいは一意的に生成され
   たファイル名が既に存在していた場合などに送出されます。

exception mailbox.FormatError

   ファイル中のデータが解析できない場合、たとえば "MH" インスタンスが
   壊れた ".mh_sequences" ファイルを読もうと試みた場合などに送出されま
   す。


使用例
======

メールボックス中の面白そうなメッセージのサブジェクトを全て印字する簡単
な例:

   import mailbox
   for message in mailbox.mbox('~/mbox'):
       subject = message['subject']       # Could possibly be None.
       if subject and 'python' in subject.lower():
           print(subject)

Babyl メールボックスから MH メールボックスへ全てのメールをコピーし、変
換可能な全ての形式固有の情報を変換する:

   import mailbox
   destination = mailbox.MH('~/Mail')
   destination.lock()
   for message in mailbox.Babyl('~/RMAIL'):
       destination.add(mailbox.MHMessage(message))
   destination.flush()
   destination.unlock()

この例は幾つかのメーリングリストのメールをソートするものです。他のプロ
グラムと平行して変更を加えることでメールが破損したり、プログラムを中断
することでメールを失ったり、はたまた半端なメッセージがメールボックス中
にあることで途中で終了してしまう、といったことを避けるように注意深く扱
っています:

   import mailbox
   import email.errors

   list_names = ('python-list', 'python-dev', 'python-bugs')

   boxes = {name: mailbox.mbox('~/email/%s' % name) for name in list_names}
   inbox = mailbox.Maildir('~/Maildir', factory=None)

   for key in inbox.iterkeys():
       try:
           message = inbox[key]
       except email.errors.MessageParseError:
           continue                # The message is malformed. Just leave it.

       for name in list_names:
           list_id = message['list-id']
           if list_id and name in list_id:
               # Get mailbox to use
               box = boxes[name]

               # Write copy to disk before removing original.
               # If there's a crash, you might duplicate a message, but
               # that's better than losing a message completely.
               box.lock()
               box.add(message)
               box.flush()
               box.unlock()

               # Remove original message
               inbox.lock()
               inbox.discard(key)
               inbox.flush()
               inbox.unlock()
               break               # Found destination, so stop looking.

   for box in boxes.itervalues():
       box.close()
