# `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.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 編碼的定義。