email.charset：字元集合的表示¶
此模組是舊版 (Compat32) email API的其中一部份，在新版的 API 只有使用別名表。
此章節的其餘內容是模組的原始說明文件
此模組提供一個類別 Charset 來表示電子郵件訊息中的字元集合和字元集合轉換，也包含字元集合登錄檔 (registry) 和其他許多運用此登錄檔的便捷方法。Charset 的實例被 email 套件中其他數個模組所使用。
從 email.charset 模組中引入此類別
- class email.charset.Charset(input_charset=DEFAULT_CHARSET)¶
將字元集合對映到其電子郵件特性 (properties)。
此類別提供有關於電子郵件對特定字元集合的規範資訊。考慮到適用之編解碼器 (codec) 的可用性，它還提供了在字元集合之間進行轉換的便利例行操作 (routine)。給定一個字元集合，它將盡量提供有關如何以符合 RFC (RFC-compliant) 的方式在電子郵件訊息中使用該字元集合的資訊。
在電子郵件標頭 (header) 或內文 (body) 用特定字元集合時必須使用可列印字元編碼 (quoted-printable) 或 base64 來編碼。特定字元集合不允許出現在電子郵件中、必須被徹底轉換。
可選的 input_charset 描述如下；input_charset 會被強制轉換 (coerced) 為小寫。經過別名標準化 (alias normalize) 後，會進到字元集合登錄檔 (registry) 去查詢此字元集合使用的標頭編碼、內文編碼以及輸出轉換編解碼器。舉例來說，如果 input_charset 是
iso-8859-1，標頭跟內文會以可列印字元編碼並且不需要輸出轉換編解碼器。如果 input_charset 是euc-jp，標頭則會被編碼成 base64、內文不會被編碼，但輸出文字則會從euc-jp字元集合被轉換成iso-2022-jp字元集合。Charset實例有以下資料屬性：- input_charset¶
指定的初始字元集合。通用別名會被轉換成它們的官方電子郵件名稱（例如：
latin_1會被轉換成iso-8859-1）。預設為 7 位元us-ascii。
- header_encoding¶
如果字元集合在被用於電子郵件標頭前必須被編碼的話，這個屬性會被設為
charset.QP（表示可列印字元編碼）、charset.BASE64（表示 base64 編碼格式）或是charset.SHORTEST表示最短的 QP 或是 base64 編碼格式。不然這個屬性會是None。
- body_encoding¶
與 header_encoding 相同，但表示郵件訊息內文的編碼，與上述的標頭編碼有可能不同。
charset.SHORTEST是不允許於 body_encoding 使用的。
- output_charset¶
部分的字元集合在用於電子郵件的標頭或內文前必須先被轉換。如果 input_charset 是這些字元集合的其中之一，這個屬性將會包含輸出時轉換成的字元集合名稱。不然這個屬性則為
None。
- input_codec¶
用於將 input_charset 轉換成 Unicode 的 Python 編解碼器的名稱。如果不需要轉換編解碼器，這個屬性為
None。
- output_codec¶
用於將 Unicode 轉換成 output_charset 的 Python 編解碼器名稱。如果不需要轉換編解碼器，這個屬性將會與 input_codec 有相同的值。
Charset實例還有以下方法：- get_body_encoding()¶
回傳用於內文編碼的內容傳輸編碼 (content transfer encoding)。
這可以是字串
quoted-printable或base64，具體取決於所使用的編碼，或者它也可以是一個函式，在這種情況下，你應該使用單個引數呼叫該函式，即正被編碼的 Message 物件。然後函式應將 Content-Transfer-Encoding 標頭本身設定為任何適當的值。如果 body_encoding 為
QP則回傳字串quoted-printable，如果 body_encoding 為BASE64則回傳字串base64，否則回傳字串7bit。
- get_output_charset()¶
回傳輸出字元集合。
如果不為
None則這會是 output_charset 屬性，否則它是 input_charset。
- header_encode(string)¶
對字串 string 進行標頭編碼 (header-encode)。
編碼類型（base64 或可列印字元編碼）將基於 header_encoding 屬性。
- header_encode_lines(string, maxlengths)¶
透過先將 string 轉換為位元組來對它進行標頭編碼。
這與
header_encode()類似，只不過字串不會超過由引數 maxlengths 給定的最大列長度 (maximum line length)，該引數必須是個疊代器：從此疊代器回傳的每個元素將提供下一個最大列長度。
- body_encode(string)¶
對字串 string 進行內文編碼 (body-encode)。
編碼類型（base64 或可列印字元編碼）將基於 body_encoding 屬性。
Charset類別也提供了許多支援標準操作和內建函式的方法。- __str__()¶
回傳強制轉換 input_charset 為小寫後的字串。
__repr__()是__str__()的別名。
email.charset 模組還提供以下函式，用於將項目新增至全域字元集合、別名和編解碼器登錄檔中：
- email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)¶
將字元特性 (properties) 新增至全域登錄檔。
charset 是輸入的字元集合，且必須是字元集合的規範名稱 (canonical name)。
可選的 header_enc 和 body_enc 為
charset.QP（表示可列印字元編碼）、charset.BASE64（表示 base64 編碼）、charset.SHORTEST（表示最短的 base64 或可列印字元編碼）或None（表示無編碼）。SHORTEST僅在用於 header_enc 時有效。預設為None，表示無編碼。可選的 output_charset 是輸出應採用的字元集合。當呼叫
Charset.convert()方法時，將從輸入字元集合轉換為 Unicode，再轉換為輸出字元集合。預設是以與輸入相同的字元集合輸出。input_charset 和 output_charset 都必須在模組的字元集合到編解碼器對映 (character set-to-codec mapping) 中具有 Unicode 編解碼器項目；使用
add_codec()來新增模組未知的編解碼器。有關更多資訊請參閱codecs模組的文件。全域字元集合登錄檔保存在模組全域字典
CHARSETS中。
- email.charset.add_alias(alias, canonical)¶
新增字元集合別名。alias 是別名，例如
latin-1。canonical 是字元集合的規範名稱，例如iso-8859-1。全域字元集合別名登錄檔保存在模組全域字典
ALIASES中。