email.message: 表示一封電子郵件信息?

源代碼: Lib/email/message.py

位于 email 包的中心的類(lèi)就是 EmailMessage 類(lèi)。這個(gè)類(lèi)導(dǎo)入自 email.message 模塊。它是 email 對(duì)象模型的基類(lèi)。EmailMessage 為設(shè)置和查詢(xún)頭字段內(nèi)容、訪問(wèn)信息體的內(nèi)容、以及創(chuàng)建和修改結(jié)構(gòu)化信息提供了核心功能。

一份電子郵件信息由 標(biāo)頭 和 載荷 （又被稱(chēng)為 內(nèi)容 ）組成。 標(biāo)頭遵循 RFC 5322 或者 RFC 6532 風(fēng)格的字段名和值，字段名和字段值之間由一個(gè)冒號(hào)隔開(kāi)。 這個(gè)冒號(hào)既不屬于字段名，也不屬于字段值。信息的載荷可能是一段簡(jiǎn)單的文字消息，也可能是一個(gè)二進(jìn)制的對(duì)象，更可能是由多個(gè)擁有各自標(biāo)頭和載荷的子信息組成的結(jié)構(gòu)化子信息序列。 對(duì)于后者類(lèi)型的載荷，信息的 MIME 類(lèi)型將會(huì)被指明為諸如 multipart/* 或 message/rfc822 的類(lèi)型。

EmailMessage 對(duì)象所提供的抽象概念模型是一個(gè)頭字段組成的有序字典加一個(gè)代表 RFC 5322 標(biāo)準(zhǔn)的信息體的 載荷 。 載荷有可能是一系列子 EmailMessage 對(duì)象的列表。你除了可以通過(guò)一般的字典方法來(lái)訪問(wèn)頭字段名和值，還可以使用特制方法來(lái)訪問(wèn)頭的特定字段（比如說(shuō) MIME 內(nèi)容類(lèi)型字段）、操縱載荷、生成信息的序列化版本、遞歸遍歷對(duì)象樹(shù)。

EmailMessage 的類(lèi)字典接口的字典索引是頭字段名，頭字段名必須是ASCII值。字典值是帶有一些附加方法的字符串。雖然頭字段的存儲(chǔ)和獲取都是保留其原始大小寫(xiě)的，但是字段名的匹配是大小寫(xiě)不敏感的。與真正的字典不同，鍵與鍵之間不但存在順序關(guān)系，還可以重復(fù)。我們提供了額外的方法來(lái)處理含有重復(fù)鍵的頭。

載荷 是多樣的。對(duì)于簡(jiǎn)單的信息對(duì)象，它是字符串或字節(jié)對(duì)象；對(duì)于諸如 multipart/* 和 message/rfc822 信息對(duì)象的 MIME 容器文檔，它是一個(gè) EmailMessage 對(duì)象列表。

class email.message.EmailMessage(policy=default)?

如果指定了 policy ，消息將由這個(gè) policy 所指定的規(guī)則來(lái)更新和序列化信息的表達(dá)。如果沒(méi)有指定 policy ，其將默認(rèn)使用 default 策略。這個(gè)策略遵循電子郵件的RFC標(biāo)準(zhǔn)，除了行終止符號(hào)（RFC要求使用 \r\n ，此策略使用Python標(biāo)準(zhǔn)的 \n 行終止符）。請(qǐng)前往 policy 的文檔獲取更多信息。

as_string(unixfrom=False, maxheaderlen=None, policy=None)?

以一段字符串的形式返回整個(gè)消息對(duì)象。 若可選的 unixform 參數(shù)為真，返回的字符串會(huì)包含信封頭。 unixform 的默認(rèn)值是 False。 為了保持與基類(lèi) Message 的兼容性，maxheaderlen 是被接受的，但是其默認(rèn)值是 None。 這個(gè)默認(rèn)值表示行長(zhǎng)度由策略的 max_line_length 屬性所控制。從信息實(shí)例所獲取到的策略可以通過(guò) policy 參數(shù)重寫(xiě)。 這樣可以對(duì)該方法所產(chǎn)生的輸出進(jìn)行略微的控制，因?yàn)橹付ǖ?policy 會(huì)被傳遞到 Generator 當(dāng)中。

扁平化信息可能會(huì)對(duì) EmailMessage 做出修改。這是因?yàn)闉榱送瓿上蜃址霓D(zhuǎn)換，一些內(nèi)容需要使用默認(rèn)值填入（舉個(gè)例子，MIME 邊界字段可能會(huì)被生成或被修改）。

請(qǐng)注意，這個(gè)方法是為了便利而提供，不一定是適合你的應(yīng)用程序的最理想的序列化信息的方法。這在你處理多封信息的時(shí)候尤甚。如果你需要使用更加靈活的API來(lái)序列化信息，請(qǐng)參見(jiàn) email.generator.Generator 。同時(shí)請(qǐng)注意，當(dāng) utf8 屬性為其默認(rèn)值 False 的時(shí)候，本方法將限制其行為為生成以“7 bit clean”方式序列化的信息。

在 3.6 版更改: maxheaderlen 沒(méi)有被指定時(shí)的默認(rèn)行為從默認(rèn)為0修改為默認(rèn)為策略的 max_line_length 值。

__str__()?

與 as_string(policy=self.policy.clone(utf8=True)) 等價(jià)。這將讓 str(msg) 產(chǎn)生的字符串包含人類(lèi)可讀的的序列化信息內(nèi)容。

在 3.4 版更改: 本方法開(kāi)始使用 utf8=True ，而非 as_string() 的直接替身。使用 utf8=True 會(huì)產(chǎn)生類(lèi)似于 RFC 6531 的信息表達(dá)。

as_bytes(unixfrom=False, policy=None)?

以字節(jié)串對(duì)象的形式返回整個(gè)扁平化后的消息。 當(dāng)可選的 unixfrom 為真值時(shí)，返回的字符串會(huì)包含信封標(biāo)頭。 unixfrom 的默認(rèn)值為 False。 policy 參數(shù)可被用于重載從消息實(shí)例獲取的默認(rèn) policy。 這可被用來(lái)控制該方法所產(chǎn)生的部分格式效果，因?yàn)橹付ǖ?policy 將被傳遞給 BytesGenerator。

扁平化信息可能會(huì)對(duì) EmailMessage 做出修改。這是因?yàn)闉榱送瓿上蜃址霓D(zhuǎn)換，一些內(nèi)容需要使用默認(rèn)值填入（舉個(gè)例子，MIME 邊界字段可能會(huì)被生成或被修改）。

請(qǐng)注意，這個(gè)方法是為了便利而提供，不一定是適合你的應(yīng)用程序的最理想的序列化信息的方法。這在你處理多封信息的時(shí)候尤甚。如果你需要使用更加靈活的API來(lái)序列化信息，請(qǐng)參見(jiàn) email.generator.BytesGenerator 。

__bytes__()?

與 as_bytes() 等價(jià)。這將讓 bytes(msg) 產(chǎn)生一個(gè)包含序列化信息內(nèi)容的字節(jié)序列對(duì)象。

is_multipart()?

如果該信息的載荷是一個(gè)子 EmailMessage 對(duì)象列表，返回 True ；否則返回 False 。在 is_multipart() 返回 True 的場(chǎng)合下，載荷應(yīng)當(dāng)是一個(gè)字符串對(duì)象（有可能是一個(gè)使用了內(nèi)容傳輸編碼進(jìn)行編碼的二進(jìn)制載荷）。請(qǐng)注意， is_multipart() 返回 True 不意味著 msg.get_content_maintype() == 'multipart' 也會(huì)返回 True 。舉個(gè)例子， is_multipart 在 EmailMessage 是 message/rfc822 類(lèi)型的信息的情況下，其返回值也是 True 。

set_unixfrom(unixfrom)?

將信息的信封頭設(shè)置為 unixform ，這應(yīng)當(dāng)是一個(gè)字符串。（在 mboxMessage 中有關(guān)于這個(gè)頭的一段簡(jiǎn)短介紹。）

get_unixfrom()?

返回消息的信封頭。如果信封頭從未被設(shè)置過(guò)，默認(rèn)返回 None 。

以下方法實(shí)現(xiàn)了對(duì)信息的頭字段進(jìn)行訪問(wèn)的類(lèi)映射接口。請(qǐng)留意，只是類(lèi)映射接口，這與平常的映射接口（比如說(shuō)字典映射）有一些語(yǔ)義上的不同。舉個(gè)例子，在一個(gè)字典當(dāng)中，鍵之間不可重復(fù)，但是信息頭字段是可以重復(fù)的。不光如此，在字典當(dāng)中調(diào)用 keys() 方法返回的結(jié)果，其順序沒(méi)有保證；但是在一個(gè) EmailMessage 對(duì)象當(dāng)中，返回的頭字段永遠(yuǎn)以其在原信息當(dāng)中出現(xiàn)的順序，或以其加入信息的順序?yàn)樾?。任何刪了后又重新加回去的頭字段總是添加在當(dāng)時(shí)列表的末尾。

這些語(yǔ)義上的不同是刻意而為之的，是出于在絕大多數(shù)常見(jiàn)使用情景中都方便的初衷下設(shè)計(jì)的。

請(qǐng)注意在任何情況下，消息當(dāng)中的任何封包標(biāo)頭都不會(huì)包含在映射接口當(dāng)中。

__len__()?

返回標(biāo)頭的總數(shù)，包括重復(fù)項(xiàng)。

__contains__(name)?

如果消息對(duì)象中有一個(gè)名為 name 的字段，其返回值為 True 。匹配無(wú)視大小寫(xiě)差異， name 也不包含末尾的的冒號(hào)。 in 操作符的實(shí)現(xiàn)中用到了這個(gè)方法，比如說(shuō)：

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)?

返回頭字段名對(duì)應(yīng)的字段值。 name 不含冒號(hào)分隔符。如果字段未找到，返回 None 。 KeyError 異常永不拋出。

請(qǐng)注意，如果對(duì)應(yīng)名字的字段找到了多個(gè)，具體返回哪個(gè)字段值是未定義的。請(qǐng)使用 get_all() 方法獲取當(dāng)前匹配字段名的所有字段值。

使用標(biāo)準(zhǔn)策略（非 compat32）時(shí)，返回值是 email.headerregistry.BaseHeader 的某個(gè)子類(lèi)的一個(gè)實(shí)例。

__setitem__(name, val)?

在信息頭中添加名為 name 值為 val 的字段。這個(gè)字段會(huì)被添加在已有字段列表的結(jié)尾處。

請(qǐng)注意，這個(gè)方法 既不會(huì) 覆蓋 也不會(huì) 刪除任何字段名重名的已有字段。如果你確實(shí)想保證新字段是整個(gè)信息頭當(dāng)中唯一擁有 name 字段名的字段，你需要先把舊字段刪除。例如：

del msg['subject']
msg['subject'] = 'Python roolz!'

如果 policy 明確要求某些字段是唯一的（至少標(biāo)準(zhǔn)策略就有這么做），對(duì)這些字段在已有同名字段的情況下仍然調(diào)用此方法嘗試為字段名賦值會(huì)引發(fā) ValueError 異常。這是為了一致性而刻意設(shè)計(jì)出的行為，不過(guò)我們隨時(shí)可能會(huì)突然覺(jué)得“還是在這種情況下自動(dòng)把舊字段刪除比較好吧”而把這個(gè)行為改掉，所以不要以為這是特性而依賴(lài)這個(gè)行為。

__delitem__(name)?

刪除信息頭當(dāng)中字段名匹配 name 的所有字段。如果匹配指定名稱(chēng)的字段沒(méi)有找到，也不會(huì)拋出任何異常。

keys()?

以列表形式返回消息頭中所有的字段名。

values()?

以列表形式返回消息頭中所有的字段值。

items()?

以二元元組的列表形式返回消息頭中所有的字段名和字段值。

get(name, failobj=None)?

返回對(duì)應(yīng)字段名的字段值。這個(gè)方法與 __getitem__() 是一樣的，只不過(guò)如果對(duì)應(yīng)字段名的字段沒(méi)有找到，該方法會(huì)返回 failobj 。這個(gè)參數(shù)是可選的（默認(rèn)值為 None ）。

以下是一些與頭有關(guān)的更多有用方法：

get_all(name, failobj=None)?

返回字段名為 name 的所有字段值的列表。如果信息內(nèi)不存在匹配的字段，返回 failobj （其默認(rèn)值為 None ）。

add_header(_name, _value, **_params)?

高級(jí)頭字段設(shè)定。這個(gè)方法與 __setitem__() 類(lèi)似，不過(guò)你可以使用關(guān)鍵字參數(shù)為字段提供附加參數(shù)。 _name 是字段名， _value 是字段 主 值。

對(duì)于關(guān)鍵字參數(shù)字典 _params 的每個(gè)鍵值對(duì)而言，它的鍵被用作參數(shù)的名字，其中下劃線被替換為短橫杠（畢竟短橫杠不是合法的Python標(biāo)識(shí)符）。一般來(lái)講，參數(shù)以 鍵="值" 的方式添加，除非值是 None 。要真的是這樣的話，只有鍵會(huì)被添加。

如果值含有非ASCII字符，你可以將值寫(xiě)成 (CHARSET, LANGUAGE, VALUE) 形式的三元組，這樣你可以人為控制字符的字符集和語(yǔ)言。 CHARSET 是一個(gè)字符串，它為你的值的編碼命名； LANGUAGE 一般可以直接設(shè)為 None ，也可以直接設(shè)為空字符串（其他可能取值參見(jiàn) :rfc`2231` ）； VALUE 是一個(gè)字符串值，其包含非ASCII的碼點(diǎn)。如果你沒(méi)有使用三元組，你的字符串又含有非ASCII字符，那么它就會(huì)使用 RFC 2231 中， CHARSET 為 utf-8 ， LANGUAGE 為 None 的格式編碼。

例如：

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

會(huì)添加一個(gè)形如下文的頭字段：

Content-Disposition: attachment; filename="bud.gif"

帶有非ASCII字符的拓展接口：

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fu?baller.ppt'))

replace_header(_name, _value)?

替換頭字段。只會(huì)替換掉信息內(nèi)找到的第一個(gè)字段名匹配 _name 的字段值。字段的順序不變，原字段名的大小寫(xiě)也不變。如果沒(méi)有找到匹配的字段，拋出 KeyError 異常。

get_content_type()?

返回信息的內(nèi)容類(lèi)型，其形如 maintype/subtype ，強(qiáng)制全小寫(xiě)。如果信息的 Content-Type 頭字段不存在則返回 get_default_type() 的返回值；如果信息的 Content-Type 頭字段無(wú)效則返回 text/plain 。

（根據(jù) RFC 2045 所述，信息永遠(yuǎn)都有一個(gè)默認(rèn)類(lèi)型，所以 get_content_type() 一定會(huì)返回一個(gè)值。 RFC 2045 定義信息的默認(rèn)類(lèi)型為 text/plain 或 message/rfc822 ，其中后者僅出現(xiàn)在消息頭位于一個(gè) multipart/digest 容器中的場(chǎng)合中。如果消息頭的 Content-Type 字段所指定的類(lèi)型是無(wú)效的， RFC 2045 令其默認(rèn)類(lèi)型為 text/plain 。）

get_content_maintype()?

返回信息的主要內(nèi)容類(lèi)型。準(zhǔn)確來(lái)說(shuō)，此方法返回的是 get_content_type() 方法所返回的形如 maintype/subtype 的字符串當(dāng)中的 maintype 部分。

get_content_subtype()?

返回信息的子內(nèi)容類(lèi)型。準(zhǔn)確來(lái)說(shuō)，此方法返回的是 get_content_type() 方法所返回的形如 maintype/subtype 的字符串當(dāng)中的 subtype 部分。

get_default_type()?

返回默認(rèn)的內(nèi)容類(lèi)型。絕大多數(shù)的信息，其默認(rèn)內(nèi)容類(lèi)型都是 text/plain 。作為 multipart/digest 容器內(nèi)子部分的信息除外，它們的默認(rèn)內(nèi)容類(lèi)型是 message/rfc822 。

set_default_type(ctype)?

設(shè)置默認(rèn)的內(nèi)容類(lèi)型。 盡管并非強(qiáng)制，但是 ctype 仍應(yīng)當(dāng)是 text/plain 或 message/rfc822 二者取一。默認(rèn)內(nèi)容類(lèi)型并不存儲(chǔ)在 Content-Type 頭字段當(dāng)中，所以設(shè)置此項(xiàng)的唯一作用就是決定當(dāng) Content-Type 頭字段在信息中不存在時(shí)，get_content_type 方法的返回值。

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)?

在 Content-Type 頭字段當(dāng)中設(shè)置一個(gè)參數(shù)。如果該參數(shù)已于字段中存在，將其舊值替換為 value 。如果 header 是 Content-Type （默認(rèn)值），并且該頭字段于信息中尚未存在，則會(huì)先添加該字段，將其值設(shè)置為 text/plain ，并附加參數(shù)值?？蛇x的 header 可以讓你指定 Content-Type 之外的另一個(gè)頭字段。

如果值包含非ASCII字符，其字符集和語(yǔ)言可以通過(guò)可選參數(shù) charset 和 language 顯式指定?？蛇x參數(shù) language 指定 RFC 2231 當(dāng)中的語(yǔ)言，其默認(rèn)值是空字符串。 charset 和 language 都應(yīng)當(dāng)字符串。默認(rèn)使用的是 utf8 charset ，language 為 None 。

如果 replace 為 False （默認(rèn)值），該頭字段會(huì)被移動(dòng)到所有頭字段列表的末尾。如果 replace 為 True ，字段會(huì)被原地更新。

于 EmailMessage 對(duì)象而言， requote 參數(shù)已被棄用。

請(qǐng)注意，頭字段已有的參數(shù)值可以通過(guò)頭字段的 params 屬性來(lái)訪問(wèn)（舉例： msg['Content-Type'].params['charset'] ）。

在 3.4 版更改: 添加了 replace 關(guān)鍵字。

del_param(param, header='content-type', requote=True)?

從 Content-Type 頭字段中完全移去給定的參數(shù)。頭字段會(huì)被原地重寫(xiě)，重寫(xiě)后的字段不含參數(shù)和值。可選的 header 可以讓你指定 Content-Type 之外的另一個(gè)字段。

于 EmailMessage 對(duì)象而言， requote 參數(shù)已被棄用。

get_filename(failobj=None)?

返回信息頭當(dāng)中 Content-Disposition 字段當(dāng)中名為 filename 的參數(shù)值。如果該字段當(dāng)中沒(méi)有此參數(shù)，該方法會(huì)退而尋找 Content-Type 字段當(dāng)中的 name 參數(shù)值。如果這個(gè)也沒(méi)有找到，或者這些個(gè)字段壓根就不存在，返回 failobj 。返回的字符串永遠(yuǎn)按照 email.utils.unquote() 方法去除引號(hào)。

get_boundary(failobj=None)?

返回信息頭當(dāng)中 Content-Type 字段當(dāng)中名為 boundary 的參數(shù)值。如果字段當(dāng)中沒(méi)有此參數(shù)，或者這些個(gè)字段壓根就不存在，返回 failobj 。返回的字符串永遠(yuǎn)按照 email.utils.unquote() 方法去除引號(hào)。

set_boundary(boundary)?

將 Content-Type 頭字段的 boundary 參數(shù)設(shè)置為 boundary 。 set_boundary() 方法永遠(yuǎn)都會(huì)在必要的時(shí)候?yàn)?boundary 添加引號(hào)。如果信息對(duì)象中沒(méi)有 Content-Type 頭字段，拋出 HeaderParseError 異常。

請(qǐng)注意使用這個(gè)方法與直接刪除舊的 Content-Type 頭字段然后使用 add_header() 方法添加一個(gè)帶有新邊界值參數(shù)的 Content-Type 頭字段有細(xì)微差距。 set_boundary() 方法會(huì)保留 Content-Type 頭字段在原信息頭當(dāng)中的位置。

get_content_charset(failobj=None)?

返回 Content-Type 頭字段中的 charset 參數(shù)，強(qiáng)制小寫(xiě)。如果字段當(dāng)中沒(méi)有此參數(shù)，或者這個(gè)字段壓根不存在，返回 failobj 。

get_charsets(failobj=None)?

返回一個(gè)包含了信息內(nèi)所有字符集名字的列表。 如果信息是 multipart 類(lèi)型的，那么列表當(dāng)中的每一項(xiàng)都對(duì)應(yīng)其載荷的子部分的字符集名字。 否則，該列表是一個(gè)長(zhǎng)度為 1 的列表。

列表當(dāng)中的每一項(xiàng)都是一個(gè)字符串，其值為對(duì)應(yīng)子部分的 Content-Type 頭字段的 charset 參數(shù)值。如果該子部分沒(méi)有此頭字段，或者沒(méi)有此參數(shù)，或者其主要 MIME 類(lèi)型并非 text ，那么列表中的那一項(xiàng)即為 failobj 。

is_attachment()?

如果信息頭當(dāng)中存在一個(gè)名為 Content-Disposition 的字段，且該字段的值為 attachment （大小寫(xiě)無(wú)關(guān)），返回 True 。否則，返回 False 。

在 3.4.2 版更改: 為了與 is_multipart() 方法一致，is_attachment 現(xiàn)在是一個(gè)方法，不再是屬性了。

get_content_disposition()?

如果信息的 Content-Disposition 頭字段存在，返回其字段值；否則返回 None 。返回的值均為小寫(xiě)，不包含參數(shù)。如果信息遵循 RFC 2183 標(biāo)準(zhǔn)，則此方法的返回值只可能在 inline 、 attachment 和 None 之間選擇。

3.5 新版功能.

下列方法與信息內(nèi)容（載荷）之訪問(wèn)與操控有關(guān)。

walk()?

walk() 方法是一個(gè)多功能生成器。它可以被用來(lái)以深度優(yōu)先順序遍歷信息對(duì)象樹(shù)的所有部分和子部分。一般而言， walk() 會(huì)被用作 for 循環(huán)的迭代器，每一次迭代都返回其下一個(gè)子部分。

以下例子會(huì)打印出一封具有多部分結(jié)構(gòu)之信息的每個(gè)部分的 MIME 類(lèi)型。

>>>

>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain

walk 會(huì)遍歷所有 is_multipart() 方法返回 True 的部分之子部分，哪怕 msg.get_content_maintype() == 'multipart' 返回的是 False 。使用 _structure 除錯(cuò)幫助函數(shù)可以幫助我們?cè)谙旅孢@個(gè)例子當(dāng)中看清楚這一點(diǎn)：

>>>

>>> from email.iterators import _structure
>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart',
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
    message/delivery-status
        text/plain
        text/plain
    message/rfc822
        text/plain

在這里， message 的部分并非 multiparts ，但是它們真的包含子部分！ is_multipart() 返回 True ， walk 也深入進(jìn)這些子部分中。

get_body(preferencelist=('related', 'html', 'plain'))?

返回信息的 MIME 部分。這個(gè)部分是最可能成為信息體的部分。

preferencelist 必須是一個(gè)字符串序列，其內(nèi)容從 related 、 html 和 plain 這三者組成的集合中選取。這個(gè)序列代表著返回的部分的內(nèi)容類(lèi)型之偏好。

在 get_body 方法被調(diào)用的對(duì)象上尋找匹配的候選者。

如果 related 未包括在 preferencelist 中，可考慮將所遇到的任意相關(guān)的根部分（或根部分的子部分）在該（子）部分與一個(gè)首選項(xiàng)相匹配時(shí)作為候選項(xiàng)。

當(dāng)遇到一個(gè) multipart/related 時(shí)，將檢查 start 形參并且如果找到了一個(gè)匹配 Content-ID 的部分，在查找候選匹配時(shí)只考慮它。 在其他情況下則只考慮 multipart/related 的第一個(gè)（默認(rèn)的根）部分。

如果一個(gè)部分具有 Content-Disposition 標(biāo)頭，則當(dāng)標(biāo)頭值為 inline 時(shí)將只考慮將該部分作為候選匹配。

如果沒(méi)有任何候選部分匹配 preferencelist 中的任何首選項(xiàng)，則返回 None。

注: (1) 對(duì)于大多數(shù)應(yīng)用來(lái)說(shuō)有意義的 preferencelist 組合僅有 ('plain',), ('html', 'plain') 以及默認(rèn)的 ('related', 'html', 'plain')。 (2) 由于匹配是從調(diào)用 get_body 的對(duì)象開(kāi)始的，因此在 multipart/related 上調(diào)用 get_body 將返回對(duì)象本身，除非 preferencelist 具有非默認(rèn)值。 (3) 未指定 Content-Type 或者 Content-Type 標(biāo)頭無(wú)效的消息（或消息部分）將被當(dāng)作具有 text/plain 類(lèi)型來(lái)處理，這有時(shí)可能導(dǎo)致 get_body 返回非預(yù)期的結(jié)果。

iter_attachments()?

返回包含所有不是候選 "body" 部分的消息的直接子部分的迭代器。 也就是說(shuō)，跳過(guò)首次出現(xiàn)的每個(gè) text/plain, text/html, multipart/related 或 multipart/alternative (除非通過(guò) Content-Disposition: attachment 將它們顯式地標(biāo)記為附件)，并返回所有的其余部分。 當(dāng)直接應(yīng)用于 multipart/related 時(shí)，將返回包含除根部分之外所有相關(guān)部分的迭代器（即由 start 形參所指向的部分，或者當(dāng)沒(méi)有 start 形參或 start 形參不能匹配任何部分的 Content-ID 時(shí)則為第一部分）。 當(dāng)直接應(yīng)用于 multipart/alternative 或非 multipart 時(shí)，將返回一個(gè)空迭代器。

iter_parts()?

返回包含消息的所有直接子部分的迭代器，對(duì)于非 multipart 將為空對(duì)象。 （另請(qǐng)參閱 walk()。）

get_content(*args, content_manager=None, **kw)?

調(diào)用 content_manager 的 get_content() 方法，將自身作為消息對(duì)象傳入，并將其他參數(shù)或關(guān)鍵字作為額外參數(shù)傳入。 如果未指定 content_manager，則會(huì)使用當(dāng)前 policy 所指定的 content_manager。

set_content(*args, content_manager=None, **kw)?

調(diào)用 content_manager 的 set_content() 方法，將自身作為消息傳入，并將其他參數(shù)或關(guān)鍵字作為額外參數(shù)傳入。 如果未指定 content_manager，則會(huì)使用當(dāng)前 policy 所指定的 content_manager。

make_related(boundary=None)?

將非 multipart 消息轉(zhuǎn)換為 multipart/related 消息，將任何現(xiàn)有的 Content- 標(biāo)頭和載荷移入 multipart 的（新加）首部分。 如果指定了 boundary，會(huì)用它作為 multipart 中的分界字符串，否則會(huì)在必要時(shí)自動(dòng)創(chuàng)建分界（例如當(dāng)消息被序列化時(shí)）。

make_alternative(boundary=None)?

將非 multipart 或 multipart/related 轉(zhuǎn)換為 multipart/alternative，將任何現(xiàn)有的 Content- 標(biāo)頭和載荷移入 multipart 的（新加）首部分。 如果指定了 boundary，會(huì)用它作為 multipart 中的分界字符串，否則會(huì)在必要時(shí)自動(dòng)創(chuàng)建分界（例如當(dāng)消息被序列化時(shí)）。

make_mixed(boundary=None)?

將非 multipart, multipart/related 或 multipart-alternative 轉(zhuǎn)換為 multipart/mixed，將任何現(xiàn)有的 Content- 標(biāo)頭和載荷移入 multipart 的（新加）首部分。 如果指定了 boundary，會(huì)用它作為 multipart 中的分界字符串，否則會(huì)在必要時(shí)自動(dòng)創(chuàng)建分界（例如當(dāng)消息被序列化時(shí)）。

add_related(*args, content_manager=None, **kw)?

如果消息為 multipart/related，則創(chuàng)建一個(gè)新的消息對(duì)象，將所有參數(shù)傳給其 set_content() 方法，并將其 attach() 到 multipart。 如果消息為非 multipart，則先調(diào)用 make_related() 然后再繼續(xù)上述步驟。 如果消息為任何其他類(lèi)型的 multipart，則會(huì)引發(fā) TypeError。 如果未指定 content_manager，則使用當(dāng)前 policy 所指定的 content_manager。 如果添加的部分沒(méi)有 Content-Disposition 標(biāo)頭，則會(huì)添加一個(gè)值為 inline 的標(biāo)頭。

add_alternative(*args, content_manager=None, **kw)?

如果消息為 multipart/alternative，則創(chuàng)建一個(gè)新的消息對(duì)象，將所有參數(shù)傳給其 set_content() 方法，并將其 attach() 到 multipart。 如果消息為非 multipart 或 multipart/related，則先調(diào)用 make_alternative() 然后再繼續(xù)上述步驟。 如果消息為任何其他類(lèi)型的 multipart，則會(huì)引發(fā) TypeError。 如果未指定 content_manager，則會(huì)使用當(dāng)前 policy 所指定的 content_manager。

add_attachment(*args, content_manager=None, **kw)?

如果消息為 multipart/mixed，則創(chuàng)建一個(gè)新的消息對(duì)象，將所有參數(shù)傳給其 set_content() 方法，并將其 attach() 到 multipart。 如果消息為非 multipart, multipart/related 或 multipart/alternative，則先調(diào)用 make_mixed() 然后再繼續(xù)上述步驟。 如果未指定 content_manager，則使用當(dāng)前 policy 所指定的 content_manager。 如果添加的部分沒(méi)有 Content-Disposition 標(biāo)頭，則會(huì)添加一個(gè)值為 attachment 的標(biāo)頭。 此方法對(duì)于顯式附件 (Content-Disposition: attachment) 和 inline 附件 (Content-Disposition: inline) 均可使用，只須向 content_manager 傳入適當(dāng)?shù)倪x項(xiàng)即可。

clear()?

移除所有載荷和所有標(biāo)頭。

clear_content()?

移除載荷以及所有 Content- 標(biāo)頭，其他標(biāo)頭不加改變并且保持其原有順序。

EmailMessage 對(duì)象具有下列實(shí)例屬性:

preamble?

MIME 文檔格式在標(biāo)頭之后的空白行以及第一個(gè)多部分的分界字符串之間允許添加一些文本， 通常，此文本在支持 MIME 的郵件閱讀器中永遠(yuǎn)不可見(jiàn)，因?yàn)樗幵跇?biāo)準(zhǔn) MIME 保護(hù)范圍之外。 但是，當(dāng)查看消息的原始文本，或當(dāng)在不支持 MIME 的閱讀器中查看消息時(shí)，此文本會(huì)變得可見(jiàn)。

preamble 屬性包含 MIME 文檔開(kāi)頭部分的這些處于保護(hù)范圍之外的文本。 當(dāng) Parser 在標(biāo)頭之后及第一個(gè)分界字符串之前發(fā)現(xiàn)一些文本時(shí)，它會(huì)將這些文本賦值給消息的 preamble 屬性。 當(dāng) Generator 寫(xiě)出 MIME 消息的純文本表示形式時(shí)，如果它發(fā)現(xiàn)消息具有 preamble 屬性，它將在標(biāo)頭及第一個(gè)分界之間區(qū)域?qū)懗鲞@些文本。 請(qǐng)參閱 email.parser 和 email.generator 了解更多細(xì)節(jié)。

請(qǐng)注意如果消息對(duì)象沒(méi)有前導(dǎo)文本，則 preamble 屬性將為 None。

epilogue?

epilogue 屬性的作用方式與 preamble 相同，區(qū)別在于它包含在最后一個(gè)分界及消息結(jié)尾之間出現(xiàn)的文本。 與 preamble 類(lèi)似，如果沒(méi)有附加文本，則此屬性將為 None。

defects?

defects 屬性包含在解析消息時(shí)發(fā)現(xiàn)的所有問(wèn)題的列表。 請(qǐng)參閱 email.errors 了解可能的解析缺陷的詳細(xì)描述。

class email.message.MIMEPart(policy=default)?

這個(gè)類(lèi)代表 MIME 消息的子部分。 它與 EmailMessage 相似，不同之處在于當(dāng) set_content() 被調(diào)用時(shí)不會(huì)添加 MIME-Version 標(biāo)頭，因?yàn)樽硬糠植恍枰兴鼈冏约旱?MIME-Version 標(biāo)頭。

備注

1

原先在3.4版本中以 provisional module 添加。過(guò)時(shí)的文檔被移動(dòng)至 email.message.Message: 使用 compat32 API 來(lái)表示電子郵件消息 。