email.headerregistry: 自定義標頭對象?

源代碼: Lib/email/headerregistry.py

標頭是由 str 的自定義子類來表示的。 用于表示給定標頭的特定類則由創(chuàng)建標頭時生效的 policy 的 header_factory 確定。 這一節(jié)記錄了 email 包為處理兼容 RFC 5322 的電子郵件消息所實現(xiàn)的特定 header_factory，它不僅為各種標頭類型提供了自定義的標頭對象，還為應(yīng)用程序提供了添加其自定義標頭類型的擴展機制。

當使用派生自 EmailPolicy 的任何策略對象時，所有標頭都通過 HeaderRegistry 產(chǎn)生并且以 BaseHeader 作為其最后一個基類。 每個標頭類都有一個由該標頭類型確定的附加基類。 例如，許多標頭都以 UnstructuredHeader 類作為其另一個基類。 一個標頭專用的第二個類是由標頭名稱使用存儲在 HeaderRegistry 中的查找表來確定的。 所有這些都針對典型應(yīng)用程序進行透明的管理，但也為修改默認行為提供了接口，以便由更復(fù)雜的應(yīng)用使用。

以下各節(jié)首先記錄了標頭基類及其屬性，然后是用于修改 HeaderRegistry 行為的 API，最后是用于表示從結(jié)構(gòu)化標頭解析的數(shù)據(jù)的支持類。

class email.headerregistry.BaseHeader(name, value)?

name 和 value 會從 header_factory 調(diào)用傳遞給 BaseHeader。 任何標頭對象的字符串值都是完成解碼為 unicode 的 value。

這個基類定義了下列只讀屬性:

name?

標頭的名稱（字段在 ':' 之前的部分）。 這就是 name 的 header_factory 調(diào)用所傳遞的值；也就是說會保持大小寫形式。

defects?

一個包含 HeaderDefect 實例的元組，這些實例報告了在解析期間發(fā)現(xiàn)的任何 RFC 合規(guī)性問題。 email 包會嘗試盡可能地檢測合規(guī)性問題。 請參閱 errors 模塊了解可能被報告的缺陷類型的相關(guān)討論。

max_count?

此類型標頭可具有相同 name 的最大數(shù)量。 None 值表示無限制。 此屬性的 BaseHeader 值為 None；專用的標頭類預(yù)期將根據(jù)需要重載這個值。

BaseHeader 還提供了以下方法，它由 email 庫代碼調(diào)用，通常不應(yīng)當由應(yīng)用程序來調(diào)用。

fold(*, policy)?

返回一個字符串，其中包含用來根據(jù) policy 正確地折疊標頭的 linesep 字符。 cte_type 為 8bit 時將被作為 7bit 來處理，因為標頭不能包含任意二進制數(shù)據(jù)。 如果 utf8 為 False，則非 ASCII 數(shù)據(jù)將根據(jù) RFC 2047 來編碼。

BaseHeader 本身不能被用于創(chuàng)建標頭對象。 它定義了一個與每個專用標頭相配合的協(xié)議以便生成標頭對象。 具體來說，BaseHeader 要求專用類提供一個名為 parse 的 classmethod()。 此方法的調(diào)用形式如下:

parse(string, kwds)

kwds 是包含了一個預(yù)初始化鍵 defects 的字典。 defects 是一個空列表。 parse 方法應(yīng)當將任何已檢測到的缺陷添加到此列表中。 在返回時，kwds 字典 必須 至少包含 decoded 和 defects 等鍵的值。 decoded 應(yīng)當是標頭的字符串值（即完全解碼為 unicode 的標頭值）。 parse 方法應(yīng)當假定 string 可能包含 content-transfer-encoded 部分，但也應(yīng)當正確地處理全部有效的 unicode 字符以便它能解析未經(jīng)編碼的標頭值。

隨后 BaseHeader 的 __new__ 會創(chuàng)建標頭實例，并調(diào)用其 init 方法。 專屬類如果想要設(shè)置 BaseHeader 自身所提供的屬性之外的附加屬性，只需提供一個 init 方法。 這樣的 init 看起來應(yīng)該是這樣:

def init(self, /, *args, **kw):
    self._myattr = kw.pop('myattr')
    super().init(*args, **kw)

也就是說，專屬類放入 kwds 字典的任何額外內(nèi)容都應(yīng)當被移除和處理，并且 kw (和 args) 的剩余內(nèi)容會被傳遞給 BaseHeader init 方法。

class email.headerregistry.UnstructuredHeader?

"非結(jié)構(gòu)化" 標頭是 RFC 5322 中默認的標頭類型。 任何沒有指定語法的標頭都會被視為是非結(jié)構(gòu)化的。 非結(jié)構(gòu)化標頭的經(jīng)典例子是 Subject 標頭。

在 RFC 5322 中，非結(jié)構(gòu)化標頭是指一段以 ASCII 字符集表示的任意文本。 但是 RFC 2047 具有一個 RFC 5322 兼容機制用來將標頭值中的非 ASCII 文本編碼為 ASCII 字符。 當包含已編碼字的 value 被傳遞給構(gòu)造器時，UnstructuredHeader 解析器會按照非結(jié)構(gòu)化文本的 RFC 2047 規(guī)則將此類已編碼字轉(zhuǎn)換為 unicode。 解析器會使用啟發(fā)式機制來嘗試解碼一些不合規(guī)的已編碼字。 在此種情況下各類缺陷，例如已編碼字或未編碼文本中的無效字符問題等缺陷將會被注冊。

此標頭類型未提供附加屬性。

class email.headerregistry.DateHeader?

RFC 5322 為電子郵件標頭內(nèi)的日期指定了非常明確的格式。 DateHeader 解析器會識別該日期格式，并且也能識別間或出現(xiàn)的一些“不規(guī)范”變種形式。

這個標頭類型提供了以下附加屬性。

datetime?

如果標頭值能被識別為某一種有效的日期形式，此屬性將包含一個代表該日期的 datetime 實例。 如果輸入日期的時區(qū)被指定為 -0000 (表示為 UTC 但不包含源時區(qū)的相關(guān)信息)，則 datetime 將為簡單型 datetime。 如果找到了特定的時區(qū)時差值 (包括 +0000)，則 datetime 將包含使用 datetime.timezone 來記錄時區(qū)時差時的感知型 datetime。

標頭的 decoded 值是由按照 RFC 5322 對 datetime 進行格式化來確定的；也就是說，它會被設(shè)為:

email.utils.format_datetime(self.datetime)

當創(chuàng)建 DateHeader 時，value 可以為 datetime 實例。 例如這意味著以下代碼是有效的并能實現(xiàn)人們預(yù)期的行為:

msg['Date'] = datetime(2011, 7, 15, 21)

因為這是個簡單型 datetime 它將被解讀為 UTC 時間戳，并且結(jié)果值的時區(qū)將為 -0000。 使用來自 utils 模塊的 localtime() 函數(shù)會更有用:

msg['Date'] = utils.localtime()

這個例子將日期標頭設(shè)為使用當前時區(qū)時差值的當前時間和日期。

class email.headerregistry.AddressHeader?

地址標頭是最復(fù)雜的結(jié)構(gòu)化標頭類型之一。 AddressHeader 類提供了適合任何地址標頭的泛用型接口。

這個標頭類型提供了以下附加屬性。

groups?

編碼了在標頭值中找到的地址和分組的 Group 對象的元組。 非分組成員的地址在此列表中表示為 display_name 為 None 的單地址 Groups。

addresses?

編碼了來自標頭值的所有單獨地址的 Address 對象的元組。 如果標頭值包含任何分組，則來自分組的單個地址將包含在該分組出現(xiàn)在值中的點上列出（也就是說，地址列表會被“展平”為一維列表）。

The decoded value of the header will have all encoded words decoded to unicode. idna encoded domain names are also decoded to unicode. The decoded value is set by joining the str value of the elements of the groups attribute with ', '.

可以使用 Address 與 Group 對象的任意組合的列表來設(shè)置一個地址標頭的值。 display_name 為 None 的 Group 對象將被解讀為單獨地址，這允許一個地址列表可以附帶通過使用從源標頭的 groups 屬性獲取的列表而保留原分組。

class email.headerregistry.SingleAddressHeader?

AddressHeader 的子類，添加了一個額外的屬性:

address?

由標頭值編碼的單個地址。 如果標頭值實際上包含一個以上的地址（這在默認 policy 下將違反 RFC），則訪問此屬性將導(dǎo)致 ValueError。

上述類中許多還具有一個 Unique 變體 (例如 UniqueUnstructuredHeader)。 其唯一差別是在 Unique 變體中 max_count 被設(shè)為 1。

class email.headerregistry.MIMEVersionHeader?

實際上 MIME-Version 標頭只有一個有效的值，即 1.0。 為了將來的擴展，這個標頭類還支持其他的有效版本號。 如果一個版本號是 RFC 2045 的有效值，則標頭對象的以下屬性將具有不為 None 的值:

version?

字符串形式的版本號。 任何空格和/或注釋都會被移除。

major?

整數(shù)形式的主版本號

minor?

整數(shù)形式的次版本號

class email.headerregistry.ParameterizedMIMEHeader?

MIME 標頭都以前綴 'Content-' 打頭。 每個特定標頭都具有特定的值，其描述在該標頭的類之中。 有些也可以接受一個具有通用格式的補充形參形表。 這個類被用作所有接受形參的 MIME 標頭的基類。

params?

一個將形參名映射到形參值的字典。

class email.headerregistry.ContentTypeHeader?

處理 Content-Type 標頭的 ParameterizedMIMEHeader 類。

content_type?

maintype/subtype 形式的內(nèi)容類型字符串。

maintype?

subtype?

class email.headerregistry.ContentDispositionHeader?

處理 Content-Disposition 標頭的 ParameterizedMIMEHeader 類。

content_disposition?

inline 和 attachment 是僅有的常用有效值。

class email.headerregistry.ContentTransferEncoding?

處理 Content-Transfer-Encoding 標頭。

cte?

可用的有效值為 7bit, 8bit, base64 和 quoted-printable。 更多信息請參閱 RFC 2045。

class email.headerregistry.HeaderRegistry(base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)?

這是由 EmailPolicy 在默認情況下使用的工廠函數(shù)。 HeaderRegistry 會使用 base_class 和從它所保存的注冊表中獲取的專用類來構(gòu)建用于動態(tài)地創(chuàng)建標頭實例的類。 當給定的標頭名稱未在注冊表中出現(xiàn)時，則會使用由 default_class 所指定的類作為專用類。 當 use_default_map 為 True (默認值) 時，則會在初始化期間把將標頭名稱與類的標準映射拷貝到注冊表中。 base_class 始終會是所生成類的 __bases__ 列表中的最后一個類。

默認的映射有:

subject

UniqueUnstructuredHeader

date

UniqueDateHeader

resent-date

DateHeader

orig-date

UniqueDateHeader

sender

UniqueSingleAddressHeader

resent-sender

SingleAddressHeader

到

UniqueAddressHeader

resent-to

AddressHeader

cc

UniqueAddressHeader

resent-cc

AddressHeader

bcc

UniqueAddressHeader

resent-bcc

AddressHeader

從

UniqueAddressHeader

resent-from

AddressHeader

reply-to

UniqueAddressHeader

mime-version

MIMEVersionHeader

content-type

ContentTypeHeader

content-disposition

ContentDispositionHeader

content-transfer-encoding

ContentTransferEncodingHeader

message-id

MessageIDHeader

HeaderRegistry 具有下列方法:

map_to_type(self, name, cls)?

name 是要映射的標頭名稱。 它將在注冊表中被轉(zhuǎn)換為小寫形式。 cls 是要與 base_class 一起被用來創(chuàng)建用于實例化與 name 相匹配的標頭的類的專用類。

__getitem__(name)?

構(gòu)造并返回一個類來處理 name 標頭的創(chuàng)建。

__call__(name, value)?

從注冊表獲得與 name 相關(guān)聯(lián)的專用標頭 (如果 name 未在注冊表中出現(xiàn)則使用 default_class) 并將其與 base_class 相組合以產(chǎn)生類，調(diào)用被構(gòu)造類的構(gòu)造器，傳入相同的參數(shù)列表，并最終返回由此創(chuàng)建的類實例。

以下的類是用于表示從結(jié)構(gòu)化標頭解析的數(shù)據(jù)的類，并且通常會由應(yīng)用程序使用以構(gòu)造結(jié)構(gòu)化的值并賦給特定的標頭。

class email.headerregistry.Address(display_name='', username='', domain='', addr_spec=None)?

用于表示電子郵件地址的類。 地址的一般形式為:

[display_name] <username@domain>

或者：

username@domain

其中每個部分都必須符合在 RFC 5322 中闡述的特定語法規(guī)則。

為了方便起見可以指定 addr_spec 來替代 username 和 domain，在此情況下 username 和 domain 將從 addr_spec 中解析。 addr_spec 應(yīng)當是一個正確地引用了 RFC 的字符串；如果它不是 Address 則將引發(fā)錯誤。 Unicode 字符也允許使用并將在序列化時被正確地編碼。 但是，根據(jù) RFC，地址的 username 部分 不允許 有 unicode。

display_name?

地址的顯示名稱部分（如果有的話）并去除所有引用項。 如果地址沒有顯示名稱，則此屬性將為空字符串。

username?

地址的 username 部分，去除所有引用項。

domain?

地址的 domain 部分。

addr_spec?

地址的 username@domain 部分，經(jīng)過正確引用處理以作為純地址使用（上面顯示的第二種形式）。 此屬性不可變。

__str__()?

對象的 str 值是根據(jù) RFC 5322 規(guī)則進行引用處理的地址，但不帶任何非 ASCII 字符的 Content Transfer Encoding。

為了支持 SMTP (RFC 5321)，Address 會處理一種特殊情況：如果 username 和 domain 均為空字符串 (或為 None)，則 Address 的字符串值為 <>。

class email.headerregistry.Group(display_name=None, addresses=None)?

用于表示地址組的類。 地址組的一般形式為:

display_name: [address-list];

作為處理由組和單個地址混合構(gòu)成的列表的便捷方式，Group 也可以通過將 display_name 設(shè)為 None 以用來表示不是某個組的一部分的單獨地址并提供單獨地址的列表作為 addresses。

display_name?

組的 display_name。 如果其為 None 并且恰好有一個 Address 在 addresses 中，則 Group 表示一個不在某個組中的單獨地址。

addresses?

一個可能為空的表示組中地址的包含 Address 對象的元組。

__str__()?

Group 的 str 值會根據(jù) RFC 5322 進行格式化，但不帶任何非 ASCII 字符的 Content Transfer Encoding。 如果 display_name 為空值且只有一個單獨 Address 在 addresses 列表中，則 str 值將與該單獨 Address 的 str 相同。

備注

1

最初在 3.3 中作為 暫定模塊 添加