email.headerregistry: 自定義標頭對象?
源代碼: Lib/email/headerregistry.py
3.6 新版功能: 1
標頭是由 str 的自定義子類來表示的。 用于表示給定標頭的特定類則由創建標頭時生效的 policy 的 header_factory 確定。 這一節記錄了 email 包為處理兼容 RFC 5322 的電子郵件消息所實現的特定 header_factory，它不僅為各種標頭類型提供了自定義的標頭對象，還為應用程序提供了添加其自定義標頭類型的擴展機制。
當使用派生自 EmailPolicy 的任何策略對象時，所有標頭都通過 HeaderRegistry 產生并且以 BaseHeader 作為其最后一個基類。 每個標頭類都有一個由該標頭類型確定的附加基類。 例如，許多標頭都以 UnstructuredHeader 類作為其另一個基類。 一個標頭專用的第二個類是由標頭名稱使用存儲在 HeaderRegistry 中的查找表來確定的。 所有這些都針對典型應用程序進行透明的管理，但也為修改默認行為提供了接口，以便由更復雜的應用使用。
以下各節首先記錄了標頭基類及其屬性，然后是用于修改 HeaderRegistry 行為的 API，最后是用于表示從結構化標頭解析的數據的支持類。
-
class
email.headerregistry.BaseHeader(name, value)? name 和 value 會從
header_factory調用傳遞給BaseHeader。 任何標頭對象的字符串值都是完成解碼為 unicode 的 value。這個基類定義了下列只讀屬性:
-
name? 標頭的名稱（字段在 ':' 之前的部分）。 這就是 name 的
header_factory調用所傳遞的值；也就是說會保持大小寫形式。
-
defects? 一個包含
HeaderDefect實例的元組，這些實例報告了在解析期間發現的任何 RFC 合規性問題。 email 包會嘗試盡可能地檢測合規性問題。 請參閱errors模塊了解可能被報告的缺陷類型的相關討論。
-
max_count? 此類型標頭可具有相同
name的最大數量。None值表示無限制。 此屬性的BaseHeader值為None；專用的標頭類預期將根據需要重載這個值。
BaseHeader還提供了以下方法，它由 email 庫代碼調用，通常不應當由應用程序來調用。-
fold(*, policy)? 返回一個字符串，其中包含用來根據 policy 正確地折疊標頭的
linesep字符。cte_type為8bit時將被作為7bit來處理，因為標頭不能包含任意二進制數據。 如果utf8為False，則非 ASCII 數據將根據 RFC 2047 來編碼。
BaseHeader本身不能被用于創建標頭對象。 它定義了一個與每個專用標頭相配合的協議以便生成標頭對象。 具體來說，BaseHeader要求專用類提供一個名為parse的classmethod()。 此方法的調用形式如下:parse(string, kwds)
kwds是包含了一個預初始化鍵defects的字典。defects是一個空列表。 parse 方法應當將任何已檢測到的缺陷添加到此列表中。 在返回時，kwds字典 必須 至少包含decoded和defects等鍵的值。decoded應當是標頭的字符串值（即完全解碼為 unicode 的標頭值）。 parse 方法應當假定 string 可能包含 content-transfer-encoded 部分，但也應當正確地處理全部有效的 unicode 字符以便它能解析未經編碼的標頭值。隨后
BaseHeader的__new__會創建標頭實例，并調用其init方法。 專屬類如果想要設置BaseHeader自身所提供的屬性之外的附加屬性，只需提供一個init方法。 這樣的init看起來應該是這樣:def init(self, *args, **kw): self._myattr = kw.pop('myattr') super().init(*args, **kw)
也就是說，專屬類放入
kwds字典的任何額外內容都應當被移除和處理，并且kw(和args) 的剩余內容會被傳遞給BaseHeaderinit方法。-
-
class
email.headerregistry.UnstructuredHeader? "非結構化" 標頭是 RFC 5322 中默認的標頭類型。 任何沒有指定語法的標頭都會被視為是非結構化的。 非結構化標頭的經典例子是 Subject 標頭。
在 RFC 5322 中，非結構化標頭是指一段以 ASCII 字符集表示的任意文本。 但是 RFC 2047 具有一個 RFC 5322 兼容機制用來將標頭值中的非 ASCII 文本編碼為 ASCII 字符。 當包含已編碼字的 value 被傳遞給構造器時，
UnstructuredHeader解析器會按照非結構化文本的 RFC 2047 規則將此類已編碼字轉換為 unicode。 解析器會使用啟發式機制來嘗試解碼一些不合規的已編碼字。 在此種情況下各類缺陷，例如已編碼字或未編碼文本中的無效字符問題等缺陷將會被注冊。此標頭類型未提供附加屬性。
-
class
email.headerregistry.DateHeader? RFC 5322 為電子郵件標頭內的日期指定了非常明確的格式。
DateHeader解析器會識別該日期格式，并且也能識別間或出現的一些“不規范”變種形式。這個標頭類型提供了以下附加屬性。
-
datetime? 如果標頭值能被識別為某一種有效的日期形式，此屬性將包含一個代表該日期的
datetime實例。 如果輸入日期的時區被指定為-0000(表示為 UTC 但不包含源時區的相關信息)，則datetime將為簡單型datetime。 如果找到了特定的時區時差值 (包括 +0000)，則datetime將包含使用datetime.timezone來記錄時區時差時的感知型datetime。
標頭的
decoded值是由按照 RFC 5322 對datetime進行格式化來確定的；也就是說，它會被設為:email.utils.format_datetime(self.datetime)
當創建
DateHeader時，value 可以為datetime實例。 例如這意味著以下代碼是有效的并能實現人們預期的行為:msg['Date'] = datetime(2011, 7, 15, 21)
因為這是個簡單型
datetime它將被解讀為 UTC 時間戳，并且結果值的時區將為-0000。 使用來自utils模塊的localtime()函數會更有用:msg['Date'] = utils.localtime()
這個例子將日期標頭設為使用當前時區時差值的當前時間和日期。
-
-
class
email.headerregistry.AddressHeader? 地址標頭是最復雜的結構化標頭類型之一。
AddressHeader類提供了適合任何地址標頭的泛用型接口。這個標頭類型提供了以下附加屬性。
-
groups? 編碼了在標頭值中找到的地址和分組的
Group對象的元組。 非分組成員的地址在此列表中表示為display_name為None的單地址Groups。
-
addresses? 編碼了來自標頭值的所有單獨地址的
Address對象的元組。 如果標頭值包含任何分組，則來自分組的單個地址將包含在該分組出現在值中的點上列出（也就是說，地址列表會被“展平”為一維列表）。
標頭的
decoded值將為所有已編碼字解碼為 unicode 的結果。idna編碼的域名也將被解碼為 unicode。decoded值是通過對groups屬性的元素的str值使用', '進行join來設置的。可以使用
Address與Group對象的任意組合的列表來設置一個地址標頭的值。display_name為None的Group對象將被解讀為單獨地址，這允許一個地址列表可以附帶通過使用從源標頭的groups屬性獲取的列表而保留原分組。-
-
class
email.headerregistry.SingleAddressHeader? AddressHeader的子類，添加了一個額外的屬性:-
address? 由標頭值編碼的單個地址。 如果標頭值實際上包含一個以上的地址（這在默認
policy下將違反 RFC），則訪問此屬性將導致ValueError。
-
上述類中許多還具有一個 Unique 變體 (例如 UniqueUnstructuredHeader)。 其唯一差別是在 Unique 變體中 max_count 被設為 1。
-
class
email.headerregistry.MIMEVersionHeader? 實際上 MIME-Version 標頭只有一個有效的值，即
1.0。 為了將來的擴展，這個標頭類還支持其他的有效版本號。 如果一個版本號是 RFC 2045 的有效值，則標頭對象的以下屬性將具有不為None的值:-
version? 字符串形式的版本號。 任何空格和/或注釋都會被移除。
-
major? 整數形式的主版本號
-
minor? 整數形式的次版本號
-
-
class
email.headerregistry.ParameterizedMIMEHeader? MIME 標頭都以前綴 'Content-' 打頭。 每個特定標頭都具有特定的值，其描述在該標頭的類之中。 有些也可以接受一個具有通用格式的補充形參形表。 這個類被用作所有接受形參的 MIME 標頭的基類。
-
params? 一個將形參名映射到形參值的字典。
-
-
class
email.headerregistry.ContentTypeHeader? 處理 Content-Type 標頭的
ParameterizedMIMEHeader類。-
content_type? maintype/subtype形式的內容類型字符串。
-
maintype?
-
subtype?
-
-
class
email.headerregistry.ContentDispositionHeader? 處理 Content-Disposition 標頭的
ParameterizedMIMEHeader類。-
content-disposition inline和attachment是僅有的常用有效值。
-
-
class
email.headerregistry.ContentTransferEncoding? 處理 Content-Transfer-Encoding 標頭。
-
class
email.headerregistry.HeaderRegistry(base_class=BaseHeader, default_class=UnstructuredHeader, use_default_map=True)? 這是由
EmailPolicy在默認情況下使用的工廠函數。HeaderRegistry會使用 base_class 和從它所保存的注冊表中獲取的專用類來構建用于動態地創建標頭實例的類。 當給定的標頭名稱未在注冊表中出現時，則會使用由 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
- 從
UniqueAddressHeader
- resent-from
AddressHeader
- reply-to
UniqueAddressHeader
HeaderRegistry具有下列方法:-
map_to_type(self, name, cls)? name 是要映射的標頭名稱。 它將在注冊表中被轉換為小寫形式。 cls 是要與 base_class 一起被用來創建用于實例化與 name 相匹配的標頭的類的專用類。
-
__getitem__(name)? 構造并返回一個類來處理 name 標頭的創建。
-
__call__(name, value)? 從注冊表獲得與 name 相關聯的專用標頭 (如果 name 未在注冊表中出現則使用 default_class) 并將其與 base_class 相組合以產生類，調用被構造類的構造器，傳入相同的參數列表，并最終返回由此創建的類實例。
以下的類是用于表示從結構化標頭解析的數據的類，并且通常會由應用程序使用以構造結構化的值并賦給特定的標頭。
-
class
email.headerregistry.Address(display_name='', username='', domain='', addr_spec=None)? 用于表示電子郵件地址的類。 地址的一般形式為:
[display_name] <username@domain>
或者：
username@domain
其中每個部分都必須符合在 RFC 5322 中闡述的特定語法規則。
為了方便起見可以指定 addr_spec 來替代 username 和 domain，在此情況下 username 和 domain 將從 addr_spec 中解析。 addr_spec 應當是一個正確地引用了 RFC 的字符串；如果它不是
Address則將引發錯誤。 Unicode 字符也允許使用并將在序列化時被正確地編碼。 但是，根據 RFC，地址的 username 部分 不允許 有 unicode。-
display_name? 地址的顯示名稱部分（如果有的話）并去除所有引用項。 如果地址沒有顯示名稱，則此屬性將為空字符串。
-
username? 地址的
username部分，去除所有引用項。
-
domain? 地址的
domain部分。
-
addr_spec? 地址的
username@domain部分，經過正確引用處理以作為純地址使用（上面顯示的第二種形式）。 此屬性不可變。
為了支持 SMTP (RFC 5321)，
Address會處理一種特殊情況：如果username和domain均為空字符串 (或為None)，則Address的字符串值為<>。-
-
class
email.headerregistry.Group(display_name=None, addresses=None)? 用于表示地址組的類。 地址組的一般形式為:
display_name: [address-list];
作為處理由組和單個地址混合構成的列表的便捷方式，
Group也可以通過將 display_name 設為None以用來表示不是某個組的一部分的單個地址并提供單個地址的列表作為 addresses。-
display_name? 組的
display_name。 如果其為None并且恰好有一個Address在addresses中，則Group表示一個不在某個組中的單獨地址。
-
備注