"mailbox" — 様々な形式のメールボックス操作
******************************************

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

参考:

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


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

class 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* を追加し、それに割り当てられたキーを
      返します。

      Parameter *message* may be a "Message" instance, an
      "email.message.Message" instance, a string, or a file-like
      object (which should be open in text mode). If *message* is an
      instance of the appropriate format-specific "Message" subclass
      (e.g., if it’s an "mboxMessage" instance and this is an "mbox"
      instance), its format-specific information is used. Otherwise,
      reasonable defaults for format-specific information are used.

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

      メールボックスから *key* に対応するメッセージを削除します。

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

   __setitem__(key, message)

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

      As with "add()", parameter *message* may be a "Message"
      instance, an "email.message.Message" instance, a string, or a
      file-like object (which should be open in text mode). If
      *message* is an instance of the appropriate format-specific
      "Message" subclass (e.g., if it’s an "mboxMessage" instance and
      this is an "mbox" instance), its format-specific information is
      used. Otherwise, the format-specific information of the message
      that currently corresponds to *key* is left unchanged.

   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)

      Return a string representation of the message corresponding to
      *key*, or raise a "KeyError" exception if no such message
      exists.

   get_file(key)

      Return a file-like representation of the message corresponding
      to *key*, or raise a "KeyError" exception if no such message
      exists. The file-like object behaves as if open in binary mode.
      This file should be closed once it is no longer needed.

      注釈: Unlike other representations of messages, file-like
        representations are not necessarily independent of the
        "Mailbox" instance that created them or of the underlying
        mailbox. More specific documentation is provided by each
        subclass.

   has_key(key)
   __contains__(key)

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

   __len__()

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

   clear()

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

   pop(key[, default])

      Return a representation of the message corresponding to *key*
      and delete the message. If no such message exists, return
      *default* if it was supplied or else raise a "KeyError"
      exception. The message is represented as an instance of the
      appropriate format-specific "Message" subclass unless a custom
      message factory was specified when the "Mailbox" instance was
      initialized.

   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=rfc822.Message, create=True)

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

   It is for historical reasons that *factory* defaults to
   "rfc822.Message" and that *dirname* is named as such rather than
   *path*. For a "Maildir" instance that behaves like instances of
   other "Mailbox" subclasses, set *factory* to "None".

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

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

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

   注釈: 本来の 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)

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

参考:

  qmail の maildir マニュアルページ
     Maildir 形式のオリジナルの仕様。

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

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


"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_file(key)

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

   lock()
   unlock()

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

参考:

  qmail の mbox マニュアルページ
     mbox 形式の仕様および種々のバリエーション。

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

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

  「mbox」 is a family of several mutually incompatible mailbox
  formats
     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()

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

   set_sequences(sequences)

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

   pack()

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

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

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

   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)

      In Babyl mailboxes, the headers of a message are not stored
      contiguously with the body of the message. To generate a file-
      like representation, the headers and body are copied together
      into a "StringIO" instance (from the "StringIO" module), which
      has an API identical to that of a file. As a result, the file-
      like object is truly independent of the underlying mailbox but
      does not save memory compared to a string representation.

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

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

   lock()
   unlock()

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

参考:

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

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


"Message" objects
=================

class mailbox.Message([message])

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

   If *message* is omitted, the new instance is created in a default,
   empty state. If *message* is an "email.message.Message" instance,
   its contents are copied; furthermore, any format-specific
   information is converted insofar as possible if *message* is a
   "Message" instance. If *message* is a string or a file, it should
   contain an **RFC 2822**-compliant message, which is read and
   parsed.

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

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


"MaildirMessage"
----------------

class mailbox.MaildirMessage([message])

   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" サブディレクトリに保存され
      るべき場合)のどちらかを返します。

      注釈: メッセージは通常メールボックスがアクセスされた後、メッセ
        ージが 読まれたかどうかに関わらず "new" から "cur" に移動され
        ます。メ ッセージ "msg" は ""S" in msg.get_flags()" が "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」 サブディレクトリおよび  | 「unseen」 シーケンス無し  |
| S フラグ                        |                            |
+---------------------------------+----------------------------+
| F フラグ                        | 「flagged」 シーケンス     |
+---------------------------------+----------------------------+
| R フラグ                        | 「replied」 シーケンス     |
+---------------------------------+----------------------------+

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

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


"mboxMessage"
-------------

class mailbox.mboxMessage([message])

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

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

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

   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" ファイルを読もうと試みた場合などに送出されま
   す。


Deprecated classes and methods
==============================

バージョン 2.6 で撤廃.

Older versions of the "mailbox" module do not support modification of
mailboxes, such as adding or removing message, and do not provide
classes to represent format-specific message properties. For backward
compatibility, the older mailbox classes are still available, but the
newer classes should be used in preference to them.  The old classes
have been removed in Python 3.

Older mailbox objects support only iteration and provide a single
public method:

oldmailbox.next()

   Return the next message in the mailbox, created with the optional
   *factory* argument passed into the mailbox object’s constructor. By
   default this is an "rfc822.Message" object (see the "rfc822"
   module).  Depending on the mailbox implementation the *fp*
   attribute of this object may be a true file object or a class
   instance simulating a file object, taking care of things like
   message boundaries if multiple mail messages are contained in a
   single file, etc.  If no more messages are available, this method
   returns "None".

Most of the older mailbox classes have names that differ from the
current mailbox class names, except for "Maildir". For this reason,
the new "Maildir" class defines a "next()" method and its constructor
differs slightly from those of the other new mailbox classes.

The older mailbox classes whose names are not the same as their newer
counterparts are as follows:

class mailbox.UnixMailbox(fp[, factory])

   Access to a classic Unix-style mailbox, where all messages are
   contained in a single file and separated by "From" (a.k.a. "From_")
   lines.  The file object *fp* points to the mailbox file.  The
   optional *factory* parameter is a callable that should create new
   message objects.  *factory* is called with one argument, *fp* by
   the "next()" method of the mailbox object.  The default is the
   "rfc822.Message" class (see the "rfc822" module – and the note
   below).

   注釈: For reasons of this module’s internal implementation, you
     will probably want to open the *fp* object in binary mode.  This
     is especially important on Windows.

   For maximum portability, messages in a Unix-style mailbox are
   separated by any line that begins exactly with the string "'From '"
   (note the trailing space) if preceded by exactly two newlines.
   Because of the wide-range of variations in practice, nothing else
   on the "From_" line should be considered.  However, the current
   implementation doesn’t check for the leading two newlines.  This is
   usually fine for most applications.

   The "UnixMailbox" class implements a more strict version of "From_"
   line checking, using a regular expression that usually correctly
   matched "From_" delimiters.  It considers delimiter line to be
   separated by "From name time" lines.  For maximum portability, use
   the "PortableUnixMailbox" class instead.  This class is identical
   to "UnixMailbox" except that individual messages are separated by
   only "From" lines.

class mailbox.PortableUnixMailbox(fp[, factory])

   A less-strict version of "UnixMailbox", which considers only the
   "From" at the beginning of the line separating messages.  The 「
   *name* *time*」 portion of the From line is ignored, to protect
   against some variations that are observed in practice.  This works
   since lines in the message which begin with "'From '" are quoted by
   mail handling software at delivery-time.

class mailbox.MmdfMailbox(fp[, factory])

   Access an MMDF-style mailbox, where all messages are contained in a
   single file and separated by lines consisting of 4 control-A
   characters.  The file object *fp* points to the mailbox file.
   Optional *factory* is as with the "UnixMailbox" class.

class mailbox.MHMailbox(dirname[, factory])

   Access an MH mailbox, a directory with each message in a separate
   file with a numeric name. The name of the mailbox directory is
   passed in *dirname*. *factory* is as with the "UnixMailbox" class.

class mailbox.BabylMailbox(fp[, factory])

   Access a Babyl mailbox, which is similar to an MMDF mailbox.  In
   Babyl format, each message has two sets of headers, the *original*
   headers and the *visible* headers.  The original headers appear
   before a line containing only "'*** EOOH ***'" (End-Of-Original-
   Headers) and the visible headers appear after the "EOOH" line.
   Babyl-compliant mail readers will show you only the visible
   headers, and "BabylMailbox" objects will return messages containing
   only the visible headers.  You’ll have to do your own parsing of
   the mailbox file to get at the original headers.  Mail messages
   start with the EOOH line and end with a line containing only
   "'\037\014'".  *factory* is as with the "UnixMailbox" class.

If you wish to use the older mailbox classes with the "email" module
rather than the deprecated "rfc822" module, you can do so as follows:

   import email
   import email.Errors
   import mailbox

   def msgfactory(fp):
       try:
           return email.message_from_file(fp)
       except email.Errors.MessageParseError:
           # Don't return None since that will
           # stop the mailbox iterator
           return ''

   mbox = mailbox.UnixMailbox(fp, msgfactory)

Alternatively, if you know your mailbox contains only well-formed MIME
messages, you can simplify this to:

   import email
   import mailbox

   mbox = mailbox.UnixMailbox(fp, email.message_from_file)


使用例
======

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

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