"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()" 方法的第二個引數。
