# `email.charset`：字元集合的表示

原始碼：Lib/email/charset.py

此模組是舊版 (`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__()` 的別名。

  __eq__(other)

    此方法讓你比較兩個 `Charset` 實例的相等性。

  __ne__(other)

    此方法讓你比較兩個 `Charset` 實例的不相等性。

`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` 中。

email.charset.add_codec(charset, codecname)

  新增一個編解碼器，將給定字元集合中的字元與 Unicode 進行對映。

  charset 是字元集合的規範名稱。codecname 是 Python 編解碼器的名稱，適用於 `str` 的 `encode()` 方法的第二個引數。