"base64" --- Base16、Base32、Base64、Base85 資料編碼
****************************************************

**原始碼：** Lib/base64.py

======================================================================

這個模組提供將二進位資料編碼成可顯示 ASCII 字元以及解碼回原始資料的功
能，包括了 **RFC 4648** 中的 Base16、Base32、Base64 等編碼方式，以及標
準 Ascii85、Base85 編碼等。

**RFC 4648** 編碼適合對二進位資料進行編碼來使得電子郵件、URL 或是 HTTP
POST 內容等傳輸管道安全地傳遞資料。這些編碼演算法與 **uuencode** 並不
相同。

該模組提供了兩個介面。新介面支援將*類位元組物件* 編碼成 ASCII "bytes"
，並將包含 ASCII 的*類位元組物件*或字串解碼為 "bytes"。支援 **RFC
4648** 中定義的兩種 base-64 字母表（常見和 URL 安全 (URL-safe) 及檔案
系統安全 (filesystem-safe) 字母表）。

舊版介面不支援從字串解碼，但它提供對*檔案物件*進行編碼和解碼的函式。它
僅支援 Base64 標準字母表，並且按照 **RFC 2045** 每 76 個字元添加換行字
元。請注意，如果你需要 **RFC 2045** 的支援，你可能會需要 "email" 函式
庫。

在 3.3 版的變更: 新介面的解碼功能現在接受 ASCII-only 的 Unicode 字串。

在 3.4 版的變更: 任何*類位元組物件*現在被該模組中的所有編碼和解碼函式
接受。新增了對 Ascii85/Base85 的支援。

新介面提供：

base64.b64encode(s, altchars=None)

   使用 Base64 對*類位元組物件* *s* 進行編碼並回傳編碼過的 "bytes"。

   可選的 *altchars* 必須是一個長度為 2 的*類位元組物件*，用來指定替代
   的字母表，以替換 "+" 和 "/" 字元。這使得應用程式可以生成對 URL 或檔
   案系統安全的 Base64 字串。預設值為 "None"，即使用標準的 Base64 字母
   表。

   如果 *altchars* 的長度不是 2，可以斷言或引發 "ValueError"。如果
   *altchars* 不是*類位元組物件*，則會引發 "TypeError"。

base64.b64decode(s, altchars=None, validate=False)

   將經過 Base64 編碼的*類位元組物件*或 ASCII 字串 *s* 解碼，並回傳解
   碼後的 "bytes"。

   可選的 *altchars* 必須是長度為 2 的*類位元組物件*或 ASCII 字串，用
   於指定替代字母表，取代 "+" 和 "/" 字元。

   如果 *s* 填充 (pad) 不正確，將引發 "binascii.Error" 例外。

   如果 *validate* 為 "False"（預設值），在 padding check（填充檢查）
   之前，不屬於標準 base-64 字母表和替代字母表的字元將被丟棄。如果
   *validate* 為 "True"，輸入中的這些非字母表字元將導致引發
   "binascii.Error"。

   有關嚴格的 base64 檢查的更多資訊，請參閱 "binascii.a2b_base64()"。

   如果 *altchars* 的長度不是 2，可能會斷言或引發 "ValueError"。

base64.standard_b64encode(s)

   使用標準 Base64 字母表對*類位元組物件* *s* 進行編碼，並回傳編碼後的
   "bytes"。

base64.standard_b64decode(s)

   使用標準 Base64 字母表對*類位元組物件*或 ASCII 字串 *s* 進行解碼，
   並回傳解碼後的 "bytes"。

base64.urlsafe_b64encode(s)

   使用 URL 安全和檔案系統安全的字母表對*類位元組物件* *s* 進行編碼，
   該字母表將標準 Base64 字母表中的 "+" 替換為 "-"，"/" 替換為 "_"，並
   回傳編碼後的 "bytes"。結果仍可能包含 "="。

base64.urlsafe_b64decode(s)

   使用 URL 安全和檔案系統安全字母表對*類位元組物件*或 ASCII 字串 *s*
   進行解碼，該字母表將標準 Base64 字母表中的 "+" 替換為 "-"，"/" 替換
   為 "_"，並回傳解碼後的 "bytes"。

base64.b32encode(s)

   使用 Base32 對*類位元組物件* *s* 進行編碼，並回傳編碼後的 "bytes"。

base64.b32decode(s, casefold=False, map01=None)

   解碼經過 Base32 編碼的*類位元組物件*或 ASCII 字串 *s*，並回傳解碼後
   的 "bytes"。

   可選的 *casefold* 是一個是否接受小寫字母表作為輸入的旗標。出於安全
   性考量，預設值為 "False"。

   **RFC 4648** 允許將數字 0 選擇性地對應對映為字母 O，並且允許將數字
   1 選擇性地對映為字母 I 或字母 L。當可選的引數 *map01* 不為 "None"
   時，指定數字 1 應該對映為哪個字母（當 *map01* 不為 "None" 時，數字
   0 總是對映為字母 O）。出於安全性考量，預設值為 "None"，因此不允許在
   輸入中使用數字 0 和 1。

   如果 *s* 的填充不正確或輸入中存在非字母表字元，將引發
   "binascii.Error"。

base64.b32hexencode(s)

   類似於 "b32encode()"，但使用在 **RFC 4648** 中定義的擴展十六進位字
   母表 (Extended Hex Alphabet)。

   在 3.10 版被加入.

base64.b32hexdecode(s, casefold=False)

   類似於 "b32encode()"，但使用在 **RFC 4648** 中定義的擴展十六進位字
   母表。

   這個版本不允許將數字 0 對映為字母 O ，以及將數字 1 對映為字母 I 或
   字母 L，所有這些字元都包含在擴展十六進位字母表中，並且不能互換使用
   。

   在 3.10 版被加入.

base64.b16encode(s)

   使用 Base16 對*類位元組物件* *s* 進行編碼，並回傳編碼後的 "bytes"。

base64.b16decode(s, casefold=False)

   解碼經過 Base16 編碼的*類位元組物件*或 ASCII 字串 *s*，並回傳解碼後
   的 "bytes"。

   可選的 *casefold* 是一個是否接受小寫字母表作為輸入的旗標。出於安全
   性考量，預設值為 "False"。

   如果 *s* 的填充不正確或輸入中存在非字母表字元，將引發
   "binascii.Error"。

base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

   使用 Ascii85 對*類位元組物件* *b* 進行編碼，並回傳編碼後的 "bytes"
   。

   *foldspaces* 是一個可選的旗標，它使用特殊的短序列 'y' 來替代連續的
   4 個空格 (ASCII 0x20)，這是由 'btoa' 支援的功能。這個特性不被「標準
   」的 Ascii85 編碼所支援。

   *wrapcol* 控制輸出是否應該包含換行字元 ("b'\n'") 。如果這個值不為零
   ，每行輸出的長度將不超過這個字元長度（不包含後面的換行符號）。

   *pad* 控制是否在編碼之前將輸入填充為 4 的倍數。請注意，"btoa" 實作
   始終會填充。

   *adobe* 控制編碼的位元組序列前後是否加上 "<~" 和 "~>"，這是 Adobe
   實作中使用的。

   在 3.4 版被加入.

base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b')

   解碼經過 Ascii85 編碼的*類位元組物件*或 ASCII 字串 *b*，並回傳解碼
   後的 "bytes"。

   *foldspaces* 是一個旗標，指定是否應該將短序列 'y' 視為 4 個連續的空
   格 (ASCII 0x20) 的簡寫。這個功能不受「標準」Ascii85 編碼的支援。

   *adobe* 控制輸入序列是否符合 Adobe Ascii85 格式（即前後加上 "<~" 和
   "~>"）。

   *ignorechars* 是一個包含要從輸入中忽略的字元的*類位元組物件*或
   ASCII 字串。這只包含空格字元，預設情況下包含 ASCII 中的所有空格字元
   。

   在 3.4 版被加入.

base64.b85encode(b, pad=False)

   使用 Base85（例如，git 風格的二進位差異 (binary diff)）對*類位元組
   物件* *b* 進行編碼，並回傳編碼後的 "bytes"。

   如果 *pad* 為 true，則在編碼之前，輸入將使用 "b'\0'" 進行填充，以使
   其長度為 4 的倍數。

   在 3.4 版被加入.

base64.b85decode(b)

   解碼經過 base85 編碼的*類位元組物件*或 ASCII 字串 *b*，並回傳解碼後
   的 "bytes"。必要時會隱式移除填充。

   在 3.4 版被加入.

base64.z85encode(s)

   Encode the *bytes-like object* *s* using Z85 (as used in ZeroMQ)
   and return the encoded "bytes".  See Z85  specification for more
   information.

   在 3.13 版被加入.

base64.z85decode(s)

   Decode the Z85-encoded *bytes-like object* or ASCII string *s* and
   return the decoded "bytes".  See Z85  specification for more
   information.

   在 3.13 版被加入.

舊版介面：

base64.decode(input, output)

   解碼二進位檔案 *input* 的內容，並將結果的二進位資料寫入 *output* 檔
   案。 *input* 和 *output* 必須是*檔案物件*。*input* 將被讀取，直到
   "input.readline()" 回傳一個空的 bytes 物件為止。

base64.decodebytes(s)

   解碼必須包含一行或多行的 base64 編碼資料*類位元組物件* *s*，並回傳
   解碼後的 "bytes"。

   在 3.1 版被加入.

base64.encode(input, output)

   編碼二進位檔案 *input* 的內容，並將結果的 base64 編碼資料寫入
   *output* 檔案。*input* 和 *output* 必須是*檔案物件*。*input* 將被讀
   取，直到 "input.read()" 回傳一個空的 bytes 物件為止。"encode()" 會
   在輸出的每 76 個位元組之後插入一個換行字元 ("b'\n'")，並確保輸出始
   終以換行字元結尾，符合 **RFC 2045** (MIME) 的規定。

base64.encodebytes(s)

   對包含任意二進位資料的*類位元組物件* *s* 進行編碼，並回傳包含
   base64 編碼資料 "bytes"，在每 76 個輸出位元組後插入換行字元
   ("b'\n'") ，並確保有尾隨換行字元，符合 **RFC 2045** (MIME) 的規定。

   在 3.1 版被加入.

模組的一個範例用法：

>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'


安全性注意事項
==============

**RFC 4648**（第 12 節）中添加了一個新的安全性考量部分；建議對部署到正
式環境的任何程式碼進行安全性部分的審查。

也參考:

  "binascii" 模組
     支援模組中包含 ASCII 到二進位 (ASCII-to-binary) 和二進位到 ASCII
     (binary-to-ASCII) 的轉換功能。

  **RFC 1521** - MIME（多用途網際網路郵件擴展）第一部分：指定和描述網
  際網路主體格式的機制。
     第 5.2 節，"Base64 Content-Transfer-Encoding"，提供了 base64 編碼
     的定義。
