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

原始碼： Lib/base64.py

---

This module provides functions for encoding binary data to printable ASCII characters and decoding such encodings back to binary data. This includes the encodings specified in RFC 4648 (Base64, Base32 and Base16), the Base85 encoding specified in PDF 2.0, and non-standard variants of Base85 used elsewhere.

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

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

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

If padded is true (default), pad the encoded data with the '=' character to a size multiple of 4. If padded is false, do not add the pad characters.

If wrapcol is non-zero, insert a newline (b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.

在 3.15 版的變更: Added the padded and wrapcol parameters.

base64.b64decode(s, altchars=None, validate=False, *, padded=True, canonical=False)

base64.b64decode(s, altchars=None, validate=True, *, ignorechars, padded=True, canonical=False)

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

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

If padded is true, the last group of 4 base 64 alphabet characters must be padded with the '=' character. If padded is false, padding is neither required nor recognized: the '=' character is not treated as padding but as a non-alphabet character, which means it is silently discarded when validate is false, or causes an Error when validate is true unless b'=' is included in ignorechars.

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

If ignorechars is specified, it should be a bytes-like object containing characters to ignore from the input when validate is true. If ignorechars contains the pad character '=', the pad characters presented before the end of the encoded data and the excess pad characters will be ignored. The default value of validate is True if ignorechars is specified, False otherwise.

If validate is false, characters that are neither in the normal base-64 alphabet nor (if ignorechars is not specified) the alternative alphabet are discarded prior to the padding check, but the + and / characters keep their meaning if they are not in altchars (they will be discarded in future Python versions).

If validate is true, these non-alphabet characters in the input result in a binascii.Error.

If canonical is true, non-zero padding bits are rejected. See binascii.a2b_base64() for details.

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

在 3.15 版的變更: Added the canonical, ignorechars, and padded parameters.

在 3.15 版之後被棄用: Accepting the + and / characters with an alternative alphabet is now deprecated.

base64.standard_b64encode(s)

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

base64.standard_b64decode(s)

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

base64.urlsafe_b64encode(s, *, padded=True)

Encode bytes-like object s using the URL- and filesystem-safe alphabet, which substitutes - instead of + and _ instead of / in the standard Base64 alphabet, and return the encoded bytes. The result can still contain = if padded is true (default).

在 3.15 版的變更: Added the padded parameter.

base64.urlsafe_b64decode(s, *, padded=False)

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

在 3.15 版的變更: Added the padded parameter. Padding of input is no longer required by default.

在 3.15 版之後被棄用: Accepting the + and / characters is now deprecated.

base64.b32encode(s, *, padded=True, wrapcol=0)

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

If padded is true (default), pad the encoded data with the '=' character to a size multiple of 8. If padded is false, do not add the pad characters.

If wrapcol is non-zero, insert a newline (b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.

在 3.15 版的變更: Added the padded and wrapcol parameters.

base64.b32decode(s, casefold=False, map01=None, *, padded=True, ignorechars=b'', canonical=False)

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

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

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

If padded is true, the last group of 8 base 32 alphabet characters must be padded with the '=' character. If padded is false, padding is neither required nor recognized: the '=' character is not treated as padding but as a non-alphabet character, which means it raises an Error unless b'=' is included in ignorechars.

ignorechars should be a bytes-like object containing characters to ignore from the input.

If canonical is true, non-zero padding bits are rejected. See binascii.a2b_base32() for details.

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

在 3.15 版的變更: Added the canonical, ignorechars, and padded parameters.

base64.b32hexencode(s, *, padded=True, wrapcol=0)

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

在 3.10 版被加入.

在 3.15 版的變更: Added the padded and wrapcol parameters.

base64.b32hexdecode(s, casefold=False, *, padded=True, ignorechars=b'', canonical=False)

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

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

在 3.10 版被加入.

在 3.15 版的變更: Added the canonical, ignorechars, and padded parameters.

base64.b16encode(s, *, wrapcol=0)

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

If wrapcol is non-zero, insert a newline (b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.

在 3.15 版的變更: Added the wrapcol parameter.

base64.b16decode(s, casefold=False, *, ignorechars=b'')

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

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

ignorechars should be a bytes-like object containing characters to ignore from the input.

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

在 3.15 版的變更: Added the ignorechars parameter.

Base85 編碼

Base85 encoding is a family of algorithms which represent four bytes using five ASCII characters. Originally implemented in the Unix btoa(1) utility, a version of it was later adopted by Adobe in the PostScript language and is standardized in PDF 2.0 (ISO 32000-2). This version, in both its btoa and PDF variants, is implemented by a85encode().

A separate version, using a different output character set, was defined as an April Fool's joke in RFC 1924 but is now used by Git and other software. This version is implemented by b85encode().

Finally, a third version, using yet another output character set designed for safe inclusion in programming language strings, is defined by ZeroMQ and implemented here by z85encode().

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

• Whether to include and expect enclosing <~ and ~> markers.

• Whether to fold the input into multiple lines.

• The set of ASCII characters used for encoding.

• Compact encodings of sequences of spaces and null bytes.

• The encoding of zero-padding bytes applied to the input.

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 is an optional flag that uses the special short sequence 'y' instead of 4 consecutive spaces (ASCII 0x20) as supported by 'btoa'. This feature is not supported by the standard encoding used in PDF.

If wrapcol is non-zero, insert a newline (b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.

pad controls whether zero-padding applied to the end of the input is fully retained in the output encoding, as done by btoa, producing an exact multiple of 5 bytes of output. This is not part of the standard encoding used in PDF, as it does not preserve the length of the data.

adobe controls whether the encoded byte sequence is framed with <~ and ~>, as in a PostScript base-85 string literal. Note that while ASCII85Decode streams in PDF documents must be terminated with ~>, they must not use a leading <~.

在 3.4 版被加入.

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

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

foldspaces is a flag that specifies whether the 'y' short sequence should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20). This feature is not supported by the standard Ascii85 encoding used in PDF and PostScript.

adobe controls whether the <~ and ~> markers are present. While the leading <~ is not required, the input must end with ~>, or a ValueError is raised.

ignorechars should be a bytes-like object containing characters to ignore from the input. This should only contain whitespace characters, and by default contains all whitespace characters in ASCII.

If canonical is true, non-canonical encodings are rejected. See binascii.a2b_ascii85() for details.

在 3.4 版被加入.

在 3.15 版的變更: Added the canonical parameter. Single-character final groups are now always rejected as encoding violations.

base64.b85encode(b, pad=False, *, wrapcol=0)

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

The input is padded with b'\0' so its length is a multiple of 4 bytes before encoding. If pad is true, all the resulting characters are retained in the output, which will always be a multiple of 5 bytes, and thus the length of the data may not be preserved on decoding.

If wrapcol is non-zero, insert a newline (b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.

在 3.4 版被加入.

在 3.15 版的變更: Added the wrapcol parameter.

base64.b85decode(b, *, ignorechars=b'', canonical=False)

Decode the base85-encoded bytes-like object or ASCII string b and return the decoded bytes.

ignorechars should be a bytes-like object containing characters to ignore from the input.

If canonical is true, non-canonical encodings are rejected. See binascii.a2b_base85() for details.

在 3.4 版被加入.

在 3.15 版的變更: Added the canonical and ignorechars parameters. Single-character final groups are now always rejected as encoding violations.

base64.z85encode(s, pad=False, *, wrapcol=0)

Encode the bytes-like object s using Z85 (as used in ZeroMQ) and return the encoded bytes.

The input is padded with b'\0' so its length is a multiple of 4 bytes before encoding. If pad is true, all the resulting characters are retained in the output, which will always be a multiple of 5 bytes, as required by the ZeroMQ standard.

If wrapcol is non-zero, insert a newline (b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.

在 3.13 版被加入.

在 3.15 版的變更: The pad parameter was added.

在 3.15 版的變更: Added the wrapcol parameter.

base64.z85decode(s, *, ignorechars=b'', canonical=False)

Decode the Z85-encoded bytes-like object or ASCII string s and return the decoded bytes.

ignorechars should be a bytes-like object containing characters to ignore from the input.

If canonical is true, non-canonical encodings are rejected. See binascii.a2b_base85() for details.

在 3.13 版被加入.

在 3.15 版的變更: Added the canonical and ignorechars parameters. Single-character final groups are now always rejected as encoding violations.

舊版介面

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

ISO 32000-2 Portable document format - Part 2: PDF 2.0

Section 7.4.3, "ASCII85Decode Filter," provides the definition of the Ascii85 encoding used in PDF and PostScript, including the output character set and the details of data length preservation using zero-padding and partial output groups.

ZeroMQ RFC 32/Z85

The "Formal Specification" section provides the character set used in Z85.