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

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

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

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

該模組提供了兩個介面。新介面支援將*類位元組物件* 編碼成 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 的支援。


RFC 4648 編碼
=============

**RFC 4648** 編碼適合對二進位資料進行編碼來使得電子郵件、URL 或是 HTTP
POST 內容等傳輸管道能夠安全地傳遞資料。

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)

   類似於 "b32decode()"，但使用在 **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"。


Base85 編碼
===========

Base85 encoding is not formally specified but rather a de facto
standard, thus different systems perform the encoding differently.

The "a85encode()" and "b85encode()" functions in this module are two
implementations of the de facto standard. You should call the function
with the Base85 implementation used by the software you intend to work
with.

The two functions present in this module differ in how they handle the
following:

* Whether to include enclosing "<~" and "~>" markers

* Whether to include newline characters

* The set of ASCII characters used for encoding

* Handling of null bytes

Refer to the documentation of the individual functions for more
information.

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* should be a byte string containing characters to
   ignore from the input. This should only contain whitespace
   characters, and by default contains all whitespace characters in
   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)

   使用 Z85（如用於 ZeroMQ）對*類位元組物件* *s* 進行編碼，並回傳編碼
   後的 "bytes"。有關更多資訊，請參閱 Z85 規格。

   在 3.13 版被加入.

base64.z85decode(s)

   解碼經 Z85 編碼的*類位元組物件*或 ASCII 字串 *s*，並回傳解碼後的
   "bytes"。有關更多資訊，請參閱 Z85 規格。

   在 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 編碼
     的定義。
