# `mailbox` --- Manipulate mailboxes in various formats

ソースコード: 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` 例外を送出します。

    バージョン 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_file(key)

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

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

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

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

    Return an `Message` instance whose headers are the message's visible headers and whose body is empty.

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