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_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
实例是不正确的。備註
与字典不同,关键字参数是不受支持的。
-
lock
()¶ 在邮箱上获取一个独占式咨询锁以使其他进程知道不能修改它。 如果锁无法被获取则会引发
ExternalClashError
。 所使用的具体锁机制取决于邮箱的格式。 在对邮箱内容进行任何修改之前你应当 总是 锁定它。
-
unlock
()¶ 释放邮箱上的锁,如果存在的话。
-
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
异常。
-
remove_folder
(folder)¶ 删除名称为 folder 的文件夹。 如果文件夹包含任何消息,则将引发
NotEmptyError
异常且该文件夹将不会被删除。
-
clean
()¶ 从邮箱中删除最近 36 小时内未被访问过的临时文件。 Maildir 规范要求邮件阅读程序应当时常进行此操作。
Maildir
所实现的某些Mailbox
方法值得进行特别的说明:-
add
(message)¶ -
__setitem__
(key, message)¶ -
update
(arg)¶ 警告
这些方法会基于当前进程 ID 来生成唯一文件名。 当使用多线程时,可能发生未被检测到的名称冲突并导致邮箱损坏,除非是对线程进行协调以避免使用这些方法同时操作同一个邮箱。
-
flush
()¶ 对 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 "。
也參考
- tin 上的 mbox 指南页面
该格式的规格说明,包括有关锁的详情。
- 在 Unix 上配置 Netscape Mail: 为何 Content-Length 格式是不好的
使用原始 mbox 格式而非其变种的一些理由。
- "mbox" 是由多个彼此不兼容的邮箱格式构成的家族
有关 mbox 变种的历史。
MH
¶
-
class
mailbox.
MH
(path, factory=None, create=True)¶ Mailbox
的子类,用于 MH 格式的邮箱。 形参 factory 是一个可调用对象,它接受一个文件类消息表示形式(其行为相当于以二进制模式打开)并返回一个自定义的表示形式。 如果 factory 为None
,则会使用MHMessage
作为默认的消息表示形式。 如果 create 为True
,则当邮箱不存在时会创建它。MH 是一种基于目录的邮箱格式,它是针对 MH Message Handling System 电子邮件用户代理而发明的。 在 MH 邮箱的每条消息都放在单独文件中。 MH 邮箱中除了邮件消息还可以包含其他 MH 邮箱 (称为 文件夹)。 文件夹可以无限嵌套。 MH 邮箱还支持 序列,这是一种命名列表,用来对消息进行逻辑分组而不必将其移入子文件夹。 序列是在每个文件夹中名为
.mh_sequences
的文件内定义的。MH
类可以操作 MH 邮箱,但它并不试图模拟 mh 的所有行为。 特别地,它并不会修改context
或.mh_profile
文件也不会受其影响,这两个文件是 mh 用来存储状态和配置数据的。-
list_folders
()¶ 返回所有文件夹名称的列表。
-
get_folder
(folder)¶ 返回表示名称为 folder 的文件夹的
MH
实例。 如果文件夹不存在则会引发NoSuchMailboxError
异常。
-
remove_folder
(folder)¶ 删除名称为 folder 的文件夹。 如果文件夹包含任何消息,则将引发
NotEmptyError
异常且该文件夹将不会被删除。
-
get_sequences
()¶ 返回映射到键列表的序列名称字典。 如果不存在任何序列,则返回空字典。
-
set_sequences
(sequences)¶ 根据由映射到键列表的名称组成的字典 sequences 来重新定义邮箱中的序列,该字典与
get_sequences()
返回值的形式一样。
-
pack
()¶ 根据需要重命名邮箱中的消息以消除序号中的空缺。 序列列表中的条目会做相应的修改。
備註
Already-issued keys are invalidated by this operation and should not be subsequently used.
Some
Mailbox
methods implemented byMH
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()
andlockf()
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.
-
也參考
- 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 isNone
,BabylMessage
is used as the default message representation. If create isTrue
, 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 ofMailbox
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 byBabyl
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.
-
也參考
- 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 isNone
,MMDFMessage
is used as the default message representation. If create isTrue
, 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 byMMDF
deserve special remarks:
也參考
- 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'sMessage
. Subclasses ofmailbox.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 aMessage
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 usingMailbox
instances. In some situations, the time and memory required to generateMessage
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 aMailbox
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 thecur
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 incur
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 innew
.) 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 thecur
subdirectory).備註
A message is typically moved from
new
tocur
after its mailbox has been accessed, whether or not the message is has been read. A messagemsg
has been read if"S" in msg.get_flags()
isTrue
.
-
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:
结果状态 |
|
---|---|
"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:
结果状态 |
|
---|---|
"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:
结果状态 |
|
---|---|
"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 totime.strftime()
, orTrue
(to usetime.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:
结果状态 |
|
---|---|
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:
结果状态 |
|
---|---|
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:
结果状态 |
|
---|---|
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:
结果状态 |
|
---|---|
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:
结果状态 |
|
---|---|
"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:
结果状态 |
|
---|---|
"unseen" 序列 |
非 R 标记 |
"replied" 序列 |
A 标记 |
"flagged" 序列 |
F 标记 |
When an MHMessage
instance is created based upon a
BabylMessage
instance, the following conversions take place:
结果状态 |
|
---|---|
"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, anemail.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:
结果状态 |
|
---|---|
"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:
结果状态 |
|
---|---|
"unseen" 标签 |
非 R 标记 |
"deleted" 标签 |
D 标记 |
"answered" 标签 |
A 标记 |
When a BabylMessage
instance is created based upon an
MHMessage
instance, the following conversions take place:
结果状态 |
|
---|---|
"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 bymboxMessage
:-
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 totime.strftime()
, orTrue
(to usetime.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:
结果状态 |
|
---|---|
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:
结果状态 |
|
---|---|
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:
结果状态 |
|
---|---|
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:
结果状态 |
|
---|---|
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 toFalse
), 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.
示例¶
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()