# `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 为消息的表示形式，或者如果通过or return a list of such pairs if called as `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 " 的行来指明。

  还有一些 mbox 格式变种对原始格式中发现的缺点做了改进，`mbox` 只实现原始格式，有时被称为 mboxo。 这意味着当存储消息时 Content-Length 标头如果存在则会被忽略并且消息体中出现于行开头的任何 "From " 会被转换为 ">From "，但是当读取消息时 ">From " 则不会被转换为 "From "。

  `mbox` 所实现的某些 `Mailbox` 方法值得进行特别的说明:

  `get_file`(key)

    在 `mbox` 实例上调用 `flush()` 或 `close()` 之后再使用文件可能产生无法预料的结果或者引发异常。

  `lock`()
  `unlock`()

    使用三种锁机制 --- dot 锁，以及可能情况下的 `flock()` 和 `lockf()` 系统调用。

参见

tin 上的 mbox 指南页面

  该格式的规格说明，包括有关锁的详情。

在 Unix 上配置 Netscape Mail: 为何 Content-Length 格式是不好的

  使用原始 mbox 格式而非其变种的一些理由。

"mbox" 是由多个彼此不兼容的邮箱格式构成的家族

  有关 mbox 变种的历史。

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

    使用三种锁机制 --- dot 锁，以及可能情况下的 `flock()` 和 `lockf()` 系统调用。

参见

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

    使用三种锁机制 --- dot 锁，以及可能情况下的 `flock()` 和 `lockf()` 系统调用。

参见

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:

  Flag | 含义 | 说明
  --- | --- | ---
  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:

  Flag | 含义 | 说明
  --- | --- | ---
  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:

  Flag | 含义 | 说明
  --- | --- | ---
  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()