"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" 实例有
   意义。 键会持续标识一条消息，即使对应的消息已被修改，例如被另一条消
   息所替代。

   可以使用 set 型方法 "add()" 将消息添加到 "Mailbox" 并可以使用 "del"
   语句或 set 型方法 "remove()" 和 "discard()" 将其移除。

   "Mailbox" 接口语义在某些值得注意的方面与字典语义有所不同。 每次请求
   消息时，都会基于邮箱的当前状态生成一个新的表示形式（通常为
   "Message" 实例）。 类似地，当向 "Mailbox" 实例添加消息时，所提供的
   消息表示形式的内容将被复制。 无论在哪种情况下 "Mailbox" 实例都不会
   保留对消息表示形式的引用。

   默认的 "Mailbox" 迭代器会迭代消息表示形式，而不像默认的字典迭代器那
   样迭代键。 此外，在迭代期间修改邮箱是安全且有明确定义的。 在创建迭
   代器之后被添加到邮箱的消息将对该迭代不可见。 在迭代器产出消息之前被
   从邮箱移除的消息将被静默地跳过，但是使用来自迭代器的键也有可能导致
   "KeyError" 异常，如果对应的消息后来被移除的话。

   警告:

     在修改可能同时被其他某个进程修改的邮箱时要非常小心。 用于此种任务
     的最安全邮箱格式是 Maildir；请尽量避免使用 mbox 之类的单文件格式
     进行并发写入。 如果你正在修改一个邮箱，你 *必须* 在读取文件中的任
     何消息或者执行添加或删除消息等修改操作 *之前* 通过调用 "lock()"
     以及 "unlock()" 方法来锁定它。 如果未锁定邮箱则将导致丢失消息或损
     坏整个邮箱的风险。

   "Mailbox" 实例具有下列方法:

   add(message)

      将 *message* 添加到邮箱并返回分配给它的键。

      形参 *message* 可以是 "Message" 实例、"email.message.Message" 实
      例、字符串、字节串或文件类对象（应当以二进制模式打开）。 如果
      *message* 是适当的格式专属 "Message" 子类的实例（举例来说，如果
      它是一个 "mboxMessage" 实例而这是一个 "mbox" 实例），将使用其格
      式专属的信息。 在其他情况下，则会使用合理的默认值作为格式专属的
      信息。

      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" 子
      类的实例（举例来说，如果它是一个 "mboxMessage" 实例而这是一个
      "mbox" 实例），将使用其格式专属的信息。 在其他情况下，当前与
      *key* 所对应的消息的格式专属信息则会保持不变。

   iterkeys()
   keys()

      如果通过 "iterkeys()" 调用则返回一个迭代所有键的迭代器，或者如果
      通过 "keys()" 调用则返回一个键列表。

   itervalues()
   __iter__()
   values()

      如果通过 "itervalues()" 或 "__iter__()" 调用则返回一个迭代所有消
      息的表示形式的迭代器，或者如果通过 "values()" 调用则返回一个由这
      些表示形式组成的列表。 消息会被表示为适当的格式专属 "Message" 子
      类的实例，除非当 "Mailbox" 实例被初始化时指定了自定义的消息工厂
      函数。

      備註:

        "__iter__()" 的行为与字典不同，后者是对键进行迭代。

   iteritems()
   items()

      如果通过 "iteritems()" 调用则返回一个迭代 (*key*, *message*) 对
      的迭代器，其中 *key* 为键而 *message* 为消息的表示形式，或者如果
      通过 "items()" 调用则返回一个由这种键值对组成的列表。 消息会被表
      示为适当的格式专属 "Message" 子类的实例，除非当 "Mailbox" 实例被
      初始化时指定了自定义的消息工厂函数。

   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"
      处理来将其转换为纯 7bit 表示形式的。

   get_file(key)

      返回对应于 *key* 的消息的文件类表示形式，或者如果对应的消息不存
      在则会引发 "KeyError" 异常。 文件类对象的行为相当于以二进制模式
      打开。 当不再需要此文件时应当将其关闭。

      3.2 版更變: 此文件对象实际上是二进制文件；之前它被不正确地以文本
      模式返回。 并且，此文件类对象现在还支持上下文管理协议：你可以使
      用 "with" 语句来自动关闭它。

      備註:

        不同于其他消息表示形式，文件类表示形式并不一定独立于创建它们的
        "Mailbox" 实例或下层的邮箱。 每个子类都会提供更具体的文档。

   __contains__(key)

      如果 *key* 有对应的消息则返回 "True"，否则返回 "False"。

   __len__()

      返回邮箱中消息的数量。

   clear()

      从邮箱中删除所有消息。

   pop(key, default=None)

      返回对应于 *key* 的消息的表示形式并删除该消息。 如果对应的消息不
      存在则返回 *default*。 消息会被表示为适当的格式专属 "Message" 子
      类的实例，除非当 "Mailbox" 实例被初始化时指定了自定义的消息工厂
      函数。

   popitem()

      返回一个任意的 (*key*, *message*) 对，其中 *key* 为键而
      *message* 为消息的表示形式，并删除对应的消息。 如果邮箱为空，则
      会引发 "KeyError" 异常。 消息会被表示为适当的格式专属 "Message"
      子类的实例，除非当 "Mailbox" 实例被初始化时指定了自定义的消息工
      厂函数。

   update(arg)

      形参 *arg* 应当是 *key* 到 *message* 的映射或 (*key*, *message*)
      对的可迭代对象。 用来更新邮箱以使得对于每个给定的 *key* 和
      *message*，与 *key* 相对应的消息会被设为 *message*，就像通过使用
      "__setitem__()" 一样。 类似于 "__setitem__()"，每个 *key* 都必须
      在邮箱中有一个对应的消息否则将会引发 "KeyError" 异常，因此在通常
      情况下将 *arg* 设为 "Mailbox" 实例是不正确的。

      備註:

        与字典不同，关键字参数是不受支持的。

   flush()

      将所有待定的更改写入到文件系统。 对于某些 "Mailbox" 子类来说，更
      改总是被立即写入因而 "flush()" 并不会做任何事，但您仍然应当养成
      调用此方法的习惯。

   lock()

      在邮箱上获取一个独占式咨询锁以使其他进程知道不能修改它。 如果锁
      无法被获取则会引发 "ExternalClashError"。 所使用的具体锁机制取决
      于邮箱的格式。 在对邮箱内容进行任何修改之前你应当 *总是* 锁定它
      。

   unlock()

      释放邮箱上的锁，如果存在的话。

   close()

      刷新邮箱，如果必要则将其解锁。 并关闭所有打开的文件。 对于某些
      "Mailbox" 子类来说，此方法并不会做任何事。


"Maildir"
---------

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

   "Mailbox" 的一个子类，用于 Maildir 格式的邮箱。 形参 *factory* 是一
   个可调用对象，它接受一个文件类消息表示形式（其行为相当于以二进制模
   式打开）并返回一个自定义的表示形式。 如果 *factory* 为 "None"，则会
   使用 "MaildirMessage" 作为默认的消息表示形式。 如果 *create* 为
   "True"，则当邮箱不存在时会创建它。

   如果 *create* 为 "True" 且 *dirname* 路径存在，它将被视为已有的
   maildir 而无需尝试验证其目录布局。

   使用 *dirname* 这个名称而不使用 *path* 是出于历史原因。

   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)

      根据主机平台的不同，当返回的文件保持打开状态时可能无法修改或移除
      下层的消息。

也參考:

  Courier 上的 maildir 指南页面
     该格式的规格说明。 描述了用于支持文件夹的通用扩展。

  使用 maildir 格式
     Maildir 发明者对它的说明。 包括已更新的名称创建方案和 "info" 语义
     的相关细节。


"mbox"
------

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

   "Mailbox" 的子类，用于 mbox 格式的邮箱。 形参 *factory* 是一个可调
   用对象，它接受一个文件类消息表示形式（其行为相当于以二进制模式打开
   ）并返回一个自定义的表示形式。 如果 *factory* 为 "None"，则会使用
   "mboxMessage" 作为默认的消息表示形式。 如果 *create* 为 "True"，则
   当邮箱不存在时会创建它。

   mbox 格式是在 Unix 系统上存储电子邮件的经典格式。 mbox 邮箱中的所有
   消息都存储在一个单独文件中，每条消息的开头由前五个字符为 "From " 的
   行来指明。

   Several variations of the mbox format exist to address perceived
   shortcomings in the original. In the interest of compatibility,
   "mbox" implements the original format, which is sometimes referred
   to as *mboxo*. This means that the *Content-Length* header, if
   present, is ignored and that any occurrences of "From " at the
   beginning of a line in a message body are transformed to ">From "
   when storing the message, although occurrences of ">From " are not
   transformed to "From " when reading the message.

   Some "Mailbox" methods implemented by "mbox" deserve special
   remarks:

   get_file(key)

      Using the file after calling "flush()" or "close()" on the
      "mbox" instance may yield unpredictable results or raise an
      exception.

   lock()
   unlock()

      Three locking mechanisms are used---dot locking and, if
      available, the "flock()" and "lockf()" system calls.

也參考:

  mbox man page from tin
     A specification of the format, with details on locking.

  Configuring Netscape Mail on Unix: Why The Content-Length Format is
  Bad
     An argument for using the original mbox format rather than a
     variation.

  "mbox" is a family of several mutually incompatible mailbox formats
     A history of mbox variations.


"MH"
----

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

   A subclass of "Mailbox" for mailboxes in MH format. Parameter
   *factory* is a callable object that accepts a file-like message
   representation (which behaves as if opened in binary mode) and
   returns a custom representation. If *factory* is "None",
   "MHMessage" is used as the default message representation. If
   *create* is "True", the mailbox is created if it does not exist.

   MH is a directory-based mailbox format invented for the MH Message
   Handling System, a mail user agent. Each message in an MH mailbox
   resides in its own file. An MH mailbox may contain other MH
   mailboxes (called *folders*) in addition to messages. Folders may
   be nested indefinitely. MH mailboxes also support *sequences*,
   which are named lists used to logically group messages without
   moving them to sub-folders. Sequences are defined in a file called
   ".mh_sequences" in each folder.

   The "MH" class manipulates MH mailboxes, but it does not attempt to
   emulate all of **mh**'s behaviors. In particular, it does not
   modify and is not affected by the "context" or ".mh_profile" files
   that are used by **mh** to store its state and configuration.

   "MH" instances have all of the methods of "Mailbox" in addition to
   the following:

   list_folders()

      返回所有文件夹名称的列表。

   get_folder(folder)

      Return an "MH" instance representing the folder whose name is
      *folder*. A "NoSuchMailboxError" exception is raised if the
      folder does not exist.

   add_folder(folder)

      Create a folder whose name is *folder* and return an "MH"
      instance representing it.

   remove_folder(folder)

      删除名称为 *folder* 的文件夹。 如果文件夹包含任何消息，则将引发
      "NotEmptyError" 异常且该文件夹将不会被删除。

   get_sequences()

      Return a dictionary of sequence names mapped to key lists. If
      there are no sequences, the empty dictionary is returned.

   set_sequences(sequences)

      Re-define the sequences that exist in the mailbox based upon
      *sequences*, a dictionary of names mapped to key lists, like
      returned by "get_sequences()".

   pack()

      Rename messages in the mailbox as necessary to eliminate gaps in
      numbering.  Entries in the sequences list are updated
      correspondingly.

      備註:

        Already-issued keys are invalidated by this operation and
        should not be subsequently used.

   Some "Mailbox" methods implemented by "MH" deserve special remarks:

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

      These methods immediately delete the message. The MH convention
      of marking a message for deletion by prepending a comma to its
      name is not used.

   lock()
   unlock()

      Three locking mechanisms are used---dot locking and, if
      available, the "flock()" and "lockf()" system calls. For MH
      mailboxes, locking the mailbox means locking the ".mh_sequences"
      file and, only for the duration of any operations that affect
      them, locking individual message files.

   get_file(key)

      Depending upon the host platform, it may not be possible to
      remove the underlying message while the returned file remains
      open.

   flush()

      All changes to MH mailboxes are immediately applied, so this
      method does nothing.

   close()

      "MH" instances do not keep any open files, so this method is
      equivalent to "unlock()".

也參考:

  nmh - Message Handling System
     Home page of **nmh**, an updated version of the original **mh**.

  MH & nmh: Email for Users & Programmers
     A GPL-licensed book on **mh** and **nmh**, with some information
     on the mailbox format.


"Babyl"
-------

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

   A subclass of "Mailbox" for mailboxes in Babyl format. Parameter
   *factory* is a callable object that accepts a file-like message
   representation (which behaves as if opened in binary mode) and
   returns a custom representation. If *factory* is "None",
   "BabylMessage" is used as the default message representation. If
   *create* is "True", the mailbox is created if it does not exist.

   Babyl is a single-file mailbox format used by the Rmail mail user
   agent included with Emacs. The beginning of a message is indicated
   by a line containing the two characters Control-Underscore
   ("'\037'") and Control-L ("'\014'"). The end of a message is
   indicated by the start of the next message or, in the case of the
   last message, a line containing a Control-Underscore ("'\037'")
   character.

   Messages in a Babyl mailbox have two sets of headers, original
   headers and so-called visible headers. Visible headers are
   typically a subset of the original headers that have been
   reformatted or abridged to be more attractive. Each message in a
   Babyl mailbox also has an accompanying list of *labels*, or short
   strings that record extra information about the message, and a list
   of all user-defined labels found in the mailbox is kept in the
   Babyl options section.

   "Babyl" instances have all of the methods of "Mailbox" in addition
   to the following:

   get_labels()

      Return a list of the names of all user-defined labels used in
      the mailbox.

      備註:

        The actual messages are inspected to determine which labels
        exist in the mailbox rather than consulting the list of labels
        in the Babyl options section, but the Babyl section is updated
        whenever the mailbox is modified.

   Some "Mailbox" methods implemented by "Babyl" deserve special
   remarks:

   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 an "io.BytesIO" instance, 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()

      Three locking mechanisms are used---dot locking and, if
      available, the "flock()" and "lockf()" system calls.

也參考:

  Format of Version 5 Babyl Files
     A specification of the Babyl format.

  Reading Mail with Rmail
     The Rmail manual, with some information on Babyl semantics.


"MMDF"
------

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

   A subclass of "Mailbox" for mailboxes in MMDF format. Parameter
   *factory* is a callable object that accepts a file-like message
   representation (which behaves as if opened in binary mode) and
   returns a custom representation. If *factory* is "None",
   "MMDFMessage" is used as the default message representation. If
   *create* is "True", the mailbox is created if it does not exist.

   MMDF is a single-file mailbox format invented for the Multichannel
   Memorandum Distribution Facility, a mail transfer agent. Each
   message is in the same form as an mbox message but is bracketed
   before and after by lines containing four Control-A ("'\001'")
   characters. As with the mbox format, the beginning of each message
   is indicated by a line whose first five characters are "From ", but
   additional occurrences of "From " are not transformed to ">From "
   when storing messages because the extra message separator lines
   prevent mistaking such occurrences for the starts of subsequent
   messages.

   Some "Mailbox" methods implemented by "MMDF" deserve special
   remarks:

   get_file(key)

      Using the file after calling "flush()" or "close()" on the
      "MMDF" instance may yield unpredictable results or raise an
      exception.

   lock()
   unlock()

      Three locking mechanisms are used---dot locking and, if
      available, the "flock()" and "lockf()" system calls.

也參考:

  mmdf man page from tin
     A specification of MMDF format from the documentation of tin, a
     newsreader.

  MMDF
     A Wikipedia article describing the Multichannel Memorandum
     Distribution Facility.


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

class mailbox.Message(message=None)

   A subclass of the "email.message" module's "Message". Subclasses of
   "mailbox.Message" add mailbox-format-specific state and behavior.

   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, a byte string, or a
   file, it should contain an **RFC 2822**-compliant message, which is
   read and parsed.  Files should be open in binary mode, but text
   mode files are accepted for backward compatibility.

   The format-specific state and behaviors offered by subclasses vary,
   but in general it is only the properties that are not specific to a
   particular mailbox that are supported (although presumably the
   properties are specific to a particular mailbox format). For
   example, file offsets for single-file mailbox formats and file
   names for directory-based mailbox formats are not retained, because
   they are only applicable to the original mailbox. But state such as
   whether a message has been read by the user or marked as important
   is retained, because it applies to the message itself.

   There is no requirement that "Message" instances be used to
   represent messages retrieved using "Mailbox" instances. In some
   situations, the time and memory required to generate "Message"
   representations might not be acceptable. For such situations,
   "Mailbox" instances also offer string and file-like
   representations, and a custom message factory may be specified when
   a "Mailbox" instance is initialized.


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

class mailbox.MaildirMessage(message=None)

   A message with Maildir-specific behaviors. Parameter *message* has
   the same meaning as with the "Message" constructor.

   Typically, a mail user agent application moves all of the messages
   in the "new" subdirectory to the "cur" subdirectory after the first
   time the user opens and closes the mailbox, recording that the
   messages are old whether or not they've actually been read. Each
   message in "cur" has an "info" section added to its file name to
   store information about its state. (Some mail readers may also add
   an "info" section to messages in "new".)  The "info" section may
   take one of two forms: it may contain "2," followed by a list of
   standardized flags (e.g., "2,FR") or it may contain "1," followed
   by so-called experimental information. Standard flags for Maildir
   messages are as follows:

   +--------+-----------+----------------------------------+
   | 标记   | 意义      | 解释                             |
   |========|===========|==================================|
   | D      | 草稿      | Under composition                |
   +--------+-----------+----------------------------------+
   | F      | 已标记    | 标记为重要                       |
   +--------+-----------+----------------------------------+
   | P      | 已读      | 转发，重新发送或退回             |
   +--------+-----------+----------------------------------+
   | R      | 已回复    | 回复给                           |
   +--------+-----------+----------------------------------+
   | S      | 查看      | 读取                             |
   +--------+-----------+----------------------------------+
   | T      | 已删除    | 标记为以后删除                   |
   +--------+-----------+----------------------------------+

   "MaildirMessage" 实例提供以下方法：

   get_subdir()

      Return either "new" (if the message should be stored in the
      "new" subdirectory) or "cur" (if the message should be stored in
      the "cur" subdirectory).

      備註:

        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)

      Set the subdirectory the message should be stored in. Parameter
      *subdir* must be either "new" or "cur".

   get_flags()

      Return a string specifying the flags that are currently set. If
      the message complies with the standard Maildir format, the
      result is the concatenation in alphabetical order of zero or one
      occurrence of each of "'D'", "'F'", "'P'", "'R'", "'S'", and
      "'T'". The empty string is returned if no flags are set or if
      "info" contains experimental semantics.

   set_flags(flags)

      Set the flags specified by *flags* and unset all others.

   add_flag(flag)

      Set the flag(s) specified by *flag* without changing other
      flags. To add more than one flag at a time, *flag* may be a
      string of more than one character. The current "info" is
      overwritten whether or not it contains experimental information
      rather than flags.

   remove_flag(flag)

      Unset the flag(s) specified by *flag* without changing other
      flags. To remove more than one flag at a time, *flag* maybe a
      string of more than one character.  If "info" contains
      experimental information rather than flags, the current "info"
      is not modified.

   get_date()

      Return the delivery date of the message as a floating-point
      number representing seconds since the epoch.

   set_date(date)

      Set the delivery date of the message to *date*, a floating-point
      number representing seconds since the epoch.

   get_info()

      Return a string containing the "info" for a message. This is
      useful for accessing and modifying "info" that is experimental
      (i.e., not a list of flags).

   set_info(info)

      Set "info" to *info*, which should be a string.

When a "MaildirMessage" instance is created based upon an
"mboxMessage" or "MMDFMessage" instance, the *Status* and *X-Status*
headers are omitted and the following conversions take place:

+----------------------+------------------------------------------------+
| 结果状态             | "mboxMessage" 或 "MMDFMessage" 状态            |
|======================|================================================|
| "cur" 子目录         | O 标记                                         |
+----------------------+------------------------------------------------+
| F 标记               | F 标记                                         |
+----------------------+------------------------------------------------+
| R 标记               | A 标记                                         |
+----------------------+------------------------------------------------+
| S 标记               | R 标记                                         |
+----------------------+------------------------------------------------+
| T 标记               | D 标记                                         |
+----------------------+------------------------------------------------+

When a "MaildirMessage" instance is created based upon an "MHMessage"
instance, the following conversions take place:

+---------------------------------+----------------------------+
| 结果状态                        | "MHMessage" 状态           |
|=================================|============================|
| "cur" 子目录                    | "unseen" 序列              |
+---------------------------------+----------------------------+
| "cur" subdirectory and S flag   | 非 "unseen" 序列           |
+---------------------------------+----------------------------+
| F 标记                          | "flagged" 序列             |
+---------------------------------+----------------------------+
| R 标记                          | "replied" 序列             |
+---------------------------------+----------------------------+

When a "MaildirMessage" instance is created based upon a
"BabylMessage" instance, the following conversions take place:

+---------------------------------+---------------------------------+
| 结果状态                        | "BabylMessage" 状态             |
|=================================|=================================|
| "cur" 子目录                    | "unseen" 标签                   |
+---------------------------------+---------------------------------+
| "cur" subdirectory and S flag   | 非 "unseen" 标签                |
+---------------------------------+---------------------------------+
| P 标记                          | "forwarded" 或 "resent" 标签    |
+---------------------------------+---------------------------------+
| R 标记                          | "answered" 标签                 |
+---------------------------------+---------------------------------+
| T 标记                          | "deleted" 标签                  |
+---------------------------------+---------------------------------+


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

class mailbox.mboxMessage(message=None)

   A message with mbox-specific behaviors. Parameter *message* has the
   same meaning as with the "Message" constructor.

   Messages in an mbox mailbox are stored together in a single file.
   The sender's envelope address and the time of delivery are
   typically stored in a line beginning with "From " that is used to
   indicate the start of a message, though there is considerable
   variation in the exact format of this data among mbox
   implementations. Flags that indicate the state of the message, such
   as whether it has been read or marked as important, are typically
   stored in *Status* and *X-Status* headers.

   Conventional flags for mbox messages are as follows:

   +--------+------------+----------------------------------+
   | 标记   | 意义       | 解释                             |
   |========|============|==================================|
   | R      | 读取       | 读取                             |
   +--------+------------+----------------------------------+
   | O      | Old        | 以前由MUA检测                    |
   +--------+------------+----------------------------------+
   | D      | 已删除     | 标记为以后删除                   |
   +--------+------------+----------------------------------+
   | F      | 已标记     | 标记为重要                       |
   +--------+------------+----------------------------------+
   | A      | 已回复     | 回复给                           |
   +--------+------------+----------------------------------+

   The "R" and "O" flags are stored in the *Status* header, and the
   "D", "F", and "A" flags are stored in the *X-Status* header. The
   flags and headers typically appear in the order mentioned.

   "mboxMessage" instances offer the following methods:

   get_from()

      Return a string representing the "From " line that marks the
      start of the message in an mbox mailbox. The leading "From " and
      the trailing newline are excluded.

   set_from(from_, time_=None)

      Set the "From " line to *from_*, which should be specified
      without a leading "From " or trailing newline. For convenience,
      *time_* may be specified and will be formatted appropriately and
      appended to *from_*. If *time_* is specified, it should be a
      "time.struct_time" instance, a tuple suitable for passing to
      "time.strftime()", or "True" (to use "time.gmtime()").

   get_flags()

      Return a string specifying the flags that are currently set. If
      the message complies with the conventional format, the result is
      the concatenation in the following order of zero or one
      occurrence of each of "'R'", "'O'", "'D'", "'F'", and "'A'".

   set_flags(flags)

      Set the flags specified by *flags* and unset all others.
      Parameter *flags* should be the concatenation in any order of
      zero or more occurrences of each of "'R'", "'O'", "'D'", "'F'",
      and "'A'".

   add_flag(flag)

      Set the flag(s) specified by *flag* without changing other
      flags. To add more than one flag at a time, *flag* may be a
      string of more than one character.

   remove_flag(flag)

      Unset the flag(s) specified by *flag* without changing other
      flags. To remove more than one flag at a time, *flag* maybe a
      string of more than one character.

When an "mboxMessage" instance is created based upon a
"MaildirMessage" instance, a "From " line is generated based upon the
"MaildirMessage" instance's delivery date, and the following
conversions take place:

+-------------------+---------------------------------+
| 结果状态          | "MaildirMessage" 状态           |
|===================|=================================|
| R 标记            | S 标记                          |
+-------------------+---------------------------------+
| O 标记            | "cur" 子目录                    |
+-------------------+---------------------------------+
| D 标记            | T 标记                          |
+-------------------+---------------------------------+
| F 标记            | F 标记                          |
+-------------------+---------------------------------+
| A 标记            | R 标记                          |
+-------------------+---------------------------------+

When an "mboxMessage" instance is created based upon an "MHMessage"
instance, the following conversions take place:

+---------------------+----------------------------+
| 结果状态            | "MHMessage" 状态           |
|=====================|============================|
| R 标记 和 O 标记    | 非 "unseen" 序列           |
+---------------------+----------------------------+
| O 标记              | "unseen" 序列              |
+---------------------+----------------------------+
| F 标记              | "flagged" 序列             |
+---------------------+----------------------------+
| A 标记              | "replied" 序列             |
+---------------------+----------------------------+

When an "mboxMessage" instance is created based upon a "BabylMessage"
instance, the following conversions take place:

+---------------------+-------------------------------+
| 结果状态            | "BabylMessage" 状态           |
|=====================|===============================|
| R 标记 和 O 标记    | 非 "unseen" 标签              |
+---------------------+-------------------------------+
| O 标记              | "unseen" 标签                 |
+---------------------+-------------------------------+
| D 标记              | "deleted" 标签                |
+---------------------+-------------------------------+
| A 标记              | "answered" 标签               |
+---------------------+-------------------------------+

When a "Message" instance is created based upon an "MMDFMessage"
instance, the "From " line is copied and all flags directly
correspond:

+-------------------+------------------------------+
| 结果状态          | "MMDFMessage" 状态           |
|===================|==============================|
| R 标记            | R 标记                       |
+-------------------+------------------------------+
| O 标记            | O 标记                       |
+-------------------+------------------------------+
| D 标记            | D 标记                       |
+-------------------+------------------------------+
| F 标记            | F 标记                       |
+-------------------+------------------------------+
| A 标记            | A 标记                       |
+-------------------+------------------------------+


"MHMessage"
-----------

class mailbox.MHMessage(message=None)

   A message with MH-specific behaviors. Parameter *message* has the
   same meaning as with the "Message" constructor.

   MH messages do not support marks or flags in the traditional sense,
   but they do support sequences, which are logical groupings of
   arbitrary messages. Some mail reading programs (although not the
   standard **mh** and **nmh**) use sequences in much the same way
   flags are used with other formats, as follows:

   +------------+--------------------------------------------+
   | 序列       | 解释                                       |
   |============|============================================|
   | 未读       | 未读取，但先前被MUA检测到                  |
   +------------+--------------------------------------------+
   | 已回复     | 回复给                                     |
   +------------+--------------------------------------------+
   | 已标记     | 标记为重要                                 |
   +------------+--------------------------------------------+

   "MHMessage" instances offer the following methods:

   get_sequences()

      Return a list of the names of sequences that include this
      message.

   set_sequences(sequences)

      Set the list of sequences that include this message.

   add_sequence(sequence)

      Add *sequence* to the list of sequences that include this
      message.

   remove_sequence(sequence)

      Remove *sequence* from the list of sequences that include this
      message.

When an "MHMessage" instance is created based upon a "MaildirMessage"
instance, the following conversions take place:

+----------------------+---------------------------------+
| 结果状态             | "MaildirMessage" 状态           |
|======================|=================================|
| "unseen" 序列        | 非 S 标记                       |
+----------------------+---------------------------------+
| "replied" 序列       | R 标记                          |
+----------------------+---------------------------------+
| "flagged" 序列       | F 标记                          |
+----------------------+---------------------------------+

When an "MHMessage" instance is created based upon an "mboxMessage" or
"MMDFMessage" instance, the *Status* and *X-Status* headers are
omitted and the following conversions take place:

+----------------------+------------------------------------------------+
| 结果状态             | "mboxMessage" 或 "MMDFMessage" 状态            |
|======================|================================================|
| "unseen" 序列        | 非 R 标记                                      |
+----------------------+------------------------------------------------+
| "replied" 序列       | A 标记                                         |
+----------------------+------------------------------------------------+
| "flagged" 序列       | F 标记                                         |
+----------------------+------------------------------------------------+

When an "MHMessage" instance is created based upon a "BabylMessage"
instance, the following conversions take place:

+----------------------+-------------------------------+
| 结果状态             | "BabylMessage" 状态           |
|======================|===============================|
| "unseen" 序列        | "unseen" 标签                 |
+----------------------+-------------------------------+
| "replied" 序列       | "answered" 标签               |
+----------------------+-------------------------------+


"BabylMessage"
--------------

class mailbox.BabylMessage(message=None)

   A message with Babyl-specific behaviors. Parameter *message* has
   the same meaning as with the "Message" constructor.

   Certain message labels, called *attributes*, are defined by
   convention to have special meanings. The attributes are as follows:

   +-------------+--------------------------------------------+
   | 标签        | 解释                                       |
   |=============|============================================|
   | 未读        | 未读取，但先前被MUA检测到                  |
   +-------------+--------------------------------------------+
   | deleted     | 标记为以后删除                             |
   +-------------+--------------------------------------------+
   | filed       | 复制到另一个文件或邮箱                     |
   +-------------+--------------------------------------------+
   | answered    | 回复给                                     |
   +-------------+--------------------------------------------+
   | forwarded   | 已转发                                     |
   +-------------+--------------------------------------------+
   | edited      | 由用户修改                                 |
   +-------------+--------------------------------------------+
   | resent      | 已重发                                     |
   +-------------+--------------------------------------------+

   By default, Rmail displays only visible headers. The "BabylMessage"
   class, though, uses the original headers because they are more
   complete. Visible headers may be accessed explicitly if desired.

   "BabylMessage" instances offer the following methods:

   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)

      Set the message's visible headers to be the same as the headers
      in *message*.  Parameter *visible* should be a "Message"
      instance, an "email.message.Message" instance, a string, or a
      file-like object (which should be open in text mode).

   update_visible()

      When a "BabylMessage" instance's original headers are modified,
      the visible headers are not automatically modified to
      correspond. This method updates the visible headers as follows:
      each visible header with a corresponding original header is set
      to the value of the original header, each visible header without
      a corresponding original header is removed, and any of *Date*,
      *From*, *Reply-To*, *To*, *CC*, and *Subject* that are present
      in the original headers but not the visible headers are added to
      the visible headers.

When a "BabylMessage" instance is created based upon a
"MaildirMessage" instance, the following conversions take place:

+---------------------+---------------------------------+
| 结果状态            | "MaildirMessage" 状态           |
|=====================|=================================|
| "unseen" 标签       | 非 S 标记                       |
+---------------------+---------------------------------+
| "deleted" 标签      | T 标记                          |
+---------------------+---------------------------------+
| "answered" 标签     | R 标记                          |
+---------------------+---------------------------------+
| "forwarded" 标签    | P 标记                          |
+---------------------+---------------------------------+

When a "BabylMessage" instance is created based upon an "mboxMessage"
or "MMDFMessage" instance, the *Status* and *X-Status* headers are
omitted and the following conversions take place:

+--------------------+------------------------------------------------+
| 结果状态           | "mboxMessage" 或 "MMDFMessage" 状态            |
|====================|================================================|
| "unseen" 标签      | 非 R 标记                                      |
+--------------------+------------------------------------------------+
| "deleted" 标签     | D 标记                                         |
+--------------------+------------------------------------------------+
| "answered" 标签    | A 标记                                         |
+--------------------+------------------------------------------------+

When a "BabylMessage" instance is created based upon an "MHMessage"
instance, the following conversions take place:

+--------------------+----------------------------+
| 结果状态           | "MHMessage" 状态           |
|====================|============================|
| "unseen" 标签      | "unseen" 序列              |
+--------------------+----------------------------+
| "answered" 标签    | "replied" 序列             |
+--------------------+----------------------------+


"MMDFMessage"
-------------

class mailbox.MMDFMessage(message=None)

   A message with MMDF-specific behaviors. Parameter *message* has the
   same meaning as with the "Message" constructor.

   As with message in an mbox mailbox, MMDF messages are stored with
   the sender's address and the delivery date in an initial line
   beginning with "From ".  Likewise, flags that indicate the state of
   the message are typically stored in *Status* and *X-Status*
   headers.

   Conventional flags for MMDF messages are identical to those of mbox
   message and are as follows:

   +--------+------------+----------------------------------+
   | 标记   | 意义       | 解释                             |
   |========|============|==================================|
   | R      | 读取       | 读取                             |
   +--------+------------+----------------------------------+
   | O      | Old        | 以前由MUA检测                    |
   +--------+------------+----------------------------------+
   | D      | 已删除     | 标记为以后删除                   |
   +--------+------------+----------------------------------+
   | F      | 已标记     | 标记为重要                       |
   +--------+------------+----------------------------------+
   | A      | 已回复     | 回复给                           |
   +--------+------------+----------------------------------+

   The "R" and "O" flags are stored in the *Status* header, and the
   "D", "F", and "A" flags are stored in the *X-Status* header. The
   flags and headers typically appear in the order mentioned.

   "MMDFMessage" instances offer the following methods, which are
   identical to those offered by "mboxMessage":

   get_from()

      Return a string representing the "From " line that marks the
      start of the message in an mbox mailbox. The leading "From " and
      the trailing newline are excluded.

   set_from(from_, time_=None)

      Set the "From " line to *from_*, which should be specified
      without a leading "From " or trailing newline. For convenience,
      *time_* may be specified and will be formatted appropriately and
      appended to *from_*. If *time_* is specified, it should be a
      "time.struct_time" instance, a tuple suitable for passing to
      "time.strftime()", or "True" (to use "time.gmtime()").

   get_flags()

      Return a string specifying the flags that are currently set. If
      the message complies with the conventional format, the result is
      the concatenation in the following order of zero or one
      occurrence of each of "'R'", "'O'", "'D'", "'F'", and "'A'".

   set_flags(flags)

      Set the flags specified by *flags* and unset all others.
      Parameter *flags* should be the concatenation in any order of
      zero or more occurrences of each of "'R'", "'O'", "'D'", "'F'",
      and "'A'".

   add_flag(flag)

      Set the flag(s) specified by *flag* without changing other
      flags. To add more than one flag at a time, *flag* may be a
      string of more than one character.

   remove_flag(flag)

      Unset the flag(s) specified by *flag* without changing other
      flags. To remove more than one flag at a time, *flag* maybe a
      string of more than one character.

When an "MMDFMessage" instance is created based upon a
"MaildirMessage" instance, a "From " line is generated based upon the
"MaildirMessage" instance's delivery date, and the following
conversions take place:

+-------------------+---------------------------------+
| 结果状态          | "MaildirMessage" 状态           |
|===================|=================================|
| R 标记            | S 标记                          |
+-------------------+---------------------------------+
| O 标记            | "cur" 子目录                    |
+-------------------+---------------------------------+
| D 标记            | T 标记                          |
+-------------------+---------------------------------+
| F 标记            | F 标记                          |
+-------------------+---------------------------------+
| A 标记            | R 标记                          |
+-------------------+---------------------------------+

When an "MMDFMessage" instance is created based upon an "MHMessage"
instance, the following conversions take place:

+---------------------+----------------------------+
| 结果状态            | "MHMessage" 状态           |
|=====================|============================|
| R 标记 和 O 标记    | 非 "unseen" 序列           |
+---------------------+----------------------------+
| O 标记              | "unseen" 序列              |
+---------------------+----------------------------+
| F 标记              | "flagged" 序列             |
+---------------------+----------------------------+
| A 标记              | "replied" 序列             |
+---------------------+----------------------------+

When an "MMDFMessage" instance is created based upon a "BabylMessage"
instance, the following conversions take place:

+---------------------+-------------------------------+
| 结果状态            | "BabylMessage" 状态           |
|=====================|===============================|
| R 标记 和 O 标记    | 非 "unseen" 标签              |
+---------------------+-------------------------------+
| O 标记              | "unseen" 标签                 |
+---------------------+-------------------------------+
| D 标记              | "deleted" 标签                |
+---------------------+-------------------------------+
| A 标记              | "answered" 标签               |
+---------------------+-------------------------------+

When an "MMDFMessage" instance is created based upon an "mboxMessage"
instance, the "From " line is copied and all flags directly
correspond:

+-------------------+------------------------------+
| 结果状态          | "mboxMessage" 状态           |
|===================|==============================|
| R 标记            | R 标记                       |
+-------------------+------------------------------+
| O 标记            | O 标记                       |
+-------------------+------------------------------+
| D 标记            | D 标记                       |
+-------------------+------------------------------+
| F 标记            | F 标记                       |
+-------------------+------------------------------+
| A 标记            | A 标记                       |
+-------------------+------------------------------+


异常
====

The following exception classes are defined in the "mailbox" module:

exception mailbox.Error

   The based class for all other module-specific exceptions.

exception mailbox.NoSuchMailboxError

   Raised when a mailbox is expected but is not found, such as when
   instantiating a "Mailbox" subclass with a path that does not exist
   (and with the *create* parameter set to "False"), or when opening a
   folder that does not exist.

exception mailbox.NotEmptyError

   Raised when a mailbox is not empty but is expected to be, such as
   when deleting a folder that contains messages.

exception mailbox.ExternalClashError

   Raised when some mailbox-related condition beyond the control of
   the program causes it to be unable to proceed, such as when failing
   to acquire a lock that another program already holds a lock, or
   when a uniquely-generated file name already exists.

exception mailbox.FormatError

   Raised when the data in a file cannot be parsed, such as when an
   "MH" instance attempts to read a corrupted ".mh_sequences" file.


示例
====

A simple example of printing the subjects of all messages in a mailbox
that seem interesting:

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

To copy all mail from a Babyl mailbox to an MH mailbox, converting all
of the format-specific information that can be converted:

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

This example sorts mail from several mailing lists into different
mailboxes, being careful to avoid mail corruption due to concurrent
modification by other programs, mail loss due to interruption of the
program, or premature termination due to malformed messages in the
mailbox:

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