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 例外。

如果 validateFalse(預設值),在 padding check(填充檢查)之前,不屬於標準 base-64 字母表和替代字母表的字元將被丟棄。如果 validateTrue,輸入中的這些非字母表字元將導致引發 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 檔案。 inputoutput 必須是檔案物件input 將被讀取,直到 input.readline() 回傳一個空的 bytes 物件為止。

base64.decodebytes(s)

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

在 3.1 版被加入.

base64.encode(input, output)

編碼二進位檔案 input 的內容,並將結果的 base64 編碼資料寫入 output 檔案。inputoutput 必須是檔案物件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 編碼的定義。