# `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)

  類似於 `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`。

## 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 是一個包含要從輸入中忽略的字元的類位元組物件或 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)

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