base64 --- Base16, Base32, Base64, Base85 数据编码¶
源代码： Lib/base64.py
该模块提供了用于将二进制数据编码为可打印 ASCII 字符以及将此类编码解码回二进制数据的函数。这包括 RFC 4648 中 指定的编码 （Base64、Base32 和 Base16）， PDF 2.0 中指定的 Base85 编码 ，以及在其他地方使用的非标准 Base85 变体。
此模块提供了两个接口。较新的接口支持将 字节类对象 编码为 ASCII bytes，以及将 字节类对象 或包含 ASCII 的字符串解码为 bytes。在 RFC 4648 中定义的几种 base-64 字母表（普通的以及 URL 和文件系统安全的）都受到支持。
旧式接口 不支持对字符串的解码，但它提供了用于编码和解码 文件对象 的函数。它只支持 Base64 标准字符表，并且按照 RFC 2045 的规定会每 76 个字符增加一个换行符。 请注意如果你要找 RFC 2045 支持那么你可能应当改用 email 包。
在 3.3 版本发生变更: 新的接口提供的解码函数现在已经支持只包含 ASCII 的 Unicode 字符串。
在 3.4 版本发生变更: 所有 类字节对象 现在已经被所有编码和解码函数接受。添加了对 Ascii85/Base85 的支持。
RFC 4648 编码格式¶
RFC 4648 中的编码格式适用于编码二进制数据以便它能安全地通过电子邮件发送、用作 URL 的组成部分，或者包括在 HTTP POST 请求当中。
- base64.b64encode(s, altchars=None, *, padded=True, wrapcol=0)¶
对 bytes-like object s 进行 Base64 编码，并返回编码后的
bytes。可选项 altchars 必须是一个长度为 2 的 bytes-like object，它指定了用于替换
+和/的字符表。这允许应用程序生成对 URL 或文件系统安全的 Base64 字符串。默认值为None，即使用标准 Base64 字符表。如果 padded 为（默认的）真值，则用 '=' 字符填充已编码数据长度为 4 的倍数。 如果 padded 为假值，则不添加填充字符。
如果 wrapcol 为非零值，则在至多每 wrapcol 个字符后插入一个换行符 (
b'\n')。 如果 wrapcol 为零（默认），则不插入换行符。在 3.15 版本发生变更: 增加 padded 和 wrapcol 形参。
- base64.b64decode(s, altchars=None, validate=False, *, padded=True, canonical=False)¶
- base64.b64decode(s, altchars=None, validate=True, *, ignorechars, padded=True, canonical=False)
解码 Base64 编码过的 bytes-like object 或 ASCII 字符串 s 并返回解码过的
bytes.可选项 altchars 必须是一个长度为 2 的 bytes-like object 或 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
Errorwhen validate is true unless b'=' is included in ignorechars.如果 s 被不正确地填充，将引发
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 isTrueif ignorechars is specified,Falseotherwise.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 版本发生变更: 增加了 canonical, ignorechars 和 padded 形参。
自 3.15 版本弃用: 接受使用替代字母表的
+和/字符现已被弃用。
- base64.standard_b64encode(s)¶
编码 bytes-like object s，使用标准 Base64 字母表并返回编码过的
bytes。
- base64.standard_b64decode(s)¶
解码 bytes-like object 或 ASCII 字符串 s，使用标准 Base64 字母表并返回解码过的
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 encodedbytes. The result can still contain=if padded is true (default).在 3.15 版本发生变更: 增加 padded 形参。
- base64.urlsafe_b64decode(s, *, padded=False)¶
解码 bytes-like object 或 ASCII 字符串 s，使用 URL 与文件系统安全的字母表，使用
-以及_代替标准 Base64 字母表中的+和/。返回解码过的bytes。在 3.15 版本发生变更: 增加了 padded 形参。 在默认情况下不再要求对输入的填充。
自 3.15 版本弃用: 接受
+和/字符的做法现已被弃用。
- base64.b32encode(s, *, padded=True, wrapcol=0)¶
用 Base32 编码 bytes-like object 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 版本发生变更: 增加 padded 和 wrapcol 形参。
- base64.b32decode(s, casefold=False, map01=None, *, padded=True, ignorechars=b'', canonical=False)¶
解码 Base32 编码过的 bytes-like object 或 ASCII 字符串 s 并返回解码过的
bytes.可选的 casefold 是一个指定小写字母是否可接受为输入的标志。为了安全考虑，默认值为
False。RFC 4648 允许可以选择将数码 0 (zero) 映射为字母 O (oh)，并可以选择将数码 1 (one) 映射为字母 I (eye) 或字母 L (el)。可选参数 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
Errorunless b'=' is included in ignorechars.ignorechars 应当是一个包含要从输入中忽略的字符的 bytes-like object。
如果 canonical 为真值，则会拒绝非零的填充位值。 详情参见
binascii.a2b_base32()。如果 s 被错误地填充或输入中存在字母表之外的字符，将引发
binascii.Error。在 3.15 版本发生变更: 增加了 canonical, ignorechars 和 padded 形参。
- base64.b32hexencode(s, *, padded=True, wrapcol=0)¶
类似于
b32encode()但是使用 Extended Hex Alphabet，如 RFC 4648 所定义。Added in version 3.10.
在 3.15 版本发生变更: 增加 padded 和 wrapcol 形参。
- base64.b32hexdecode(s, casefold=False, *, padded=True, ignorechars=b'', canonical=False)¶
类似于
b32decode()但是使用 Extended Hex Alphabet，如 RFC 4648 所定义。这个版本不允许数字 0（零）与字母 O（oh）和数字 1（一）与字母 I（eye）或字母 L （el）的映射，所有这些字符都包含在扩展的十六进制字母表中，不能互换。
Added in version 3.10.
在 3.15 版本发生变更: 增加了 canonical, ignorechars 和 padded 形参。
- base64.b16encode(s, *, wrapcol=0)¶
用 Base16 编码 bytes-like object 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 版本发生变更: 增加了 wrapcol 形参。
- base64.b16decode(s, casefold=False, *, ignorechars=b'')¶
解码 Base16 编码过的 bytes-like object 或 ASCII 字符串 s 并返回解码过的
bytes.可选的 casefold 是一个指定小写字母是否可接受为输入的标志。为了安全考虑，默认值为
False。ignorechars 应当是一个包含要从输入中忽略的字符的 bytes-like object。
如果 s 被错误地填充或输入中存在字母表之外的字符，将引发
binascii.Error。在 3.15 版本发生变更: 增加了 ignorechars 形参。
Base85 编码格式¶
Base85 编码是使用五个 ASCII 字符表示四个字节的一系列算法。它最初在 Unix btoa(1) 工具中实现，其一个版本后来被 Adobe 在 PostScript 语言中采用，并在 PDF 2.0 (ISO 32000-2) 中进行了标准化。该版本的 btoa 和 PDF 变体由 a85encode() 实现。
另一个使用不同输出字符集的版本在 RFC 1924 中作为愚人节笑话被定义，但现在被 Git 和其他软件所使用。该版本由 b85encode() 实现。
最后，第三个版本使用了专为安全包含在编程语言字符串中而设计的另一种输出字符集，它由 ZeroMQ 定义并在本模块中由 z85encode() 实现。
本模块中的函数在处理以下内容时有所不同：
是否包含并预期封闭的
<~和~>标记。是否将输入折叠为多行。
用于编码的 ASCII 字符集。
连续空格和空字节序列的紧凑编码。
应用于输入的零填充字节的编码。
请参阅每个函数的文档了解详情。
- base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)¶
用 Ascii85 编码 bytes-like object b 并返回编码过的
bytes。foldspaces 是一个可选旗标，它使用特殊的短序列 'y' 代替 4 个连续空格（ASCII 0x20），就像 'btoa' 所支持的那样。PDF 中使用的标准编码不支持此特性。
如果 wrapcol 为非零值，则在至多每 wrapcol 个字符后插入一个换行符 (
b'\n')。 如果 wrapcol 为零（默认），则不插入换行符。pad 控制应用于输入末尾的零填充是否完全保留在输出编码中（就像
btoa所做的那样），从而生成恰好为 5 个字节整数倍的输出。这不是 PDF 中使用的标准编码的一部分，因为它不能保留数据的长度。adobe 控制编码后的字节序列是否像 PostScript base-85 字符串字面值那样用
<~和~>框起来。请注意，虽然 PDF 文档中的 ASCII85Decode 流 必须 以~>结尾，但它们 绝不能 使用前导<~。Added in version 3.4.
- base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b', canonical=False)¶
解码 Ascii85 编码过的 bytes-like object 或 ASCII 字符串 b 并返回解码过的
bytes.foldspaces 是一个旗标，指定是否应将 'y' 短序列作为 4 个连续空格（ASCII 0x20）的简写形式接受。PDF 和 PostScript 中使用的标准 Ascii85 编码不支持此特性。
adobe 控制是否存在
<~和~>标记。虽然不要求前导<~，但输入必须以~>结尾，否则会引发ValueError。ignorechars 应当是一个包含要从输入中忽略的字符的 bytes-like object。 这应当只包含空白字符，并且默认包含 ASCII 中所有的空白字符。
If canonical is true, non-canonical encodings are rejected. See
binascii.a2b_ascii85()for details.Added in version 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 风格的二进制 diff 数据所用格式）编码 bytes-like object b 并返回编码后的
bytes.在编码之前，输入会用
b'\0'进行填充，使其长度为 4 个字节的整数倍。如果 pad 为 true，则所有生成的字符都会保留在输出中，输出将始终是 5 个字节的倍数，因此在解码时可能无法保留数据的长度。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.Added in version 3.4.
在 3.15 版本发生变更: 增加了 wrapcol 形参。
- base64.b85decode(b, *, ignorechars=b'', canonical=False)¶
解码经过 base85 编码的 bytes-like object 或 ASCII 字符串 b 并返回解码后的
bytes。ignorechars 应当是一个包含要从输入中忽略的字符的 bytes-like object。
If canonical is true, non-canonical encodings are rejected. See
binascii.a2b_base85()for details.Added in version 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)¶
使用 Z85（在 ZeroMQ 中使用）对 bytes-like object s 进行编码并返回编码后的
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.Added in version 3.13.
在 3.15 版本发生变更: The pad parameter was added.
在 3.15 版本发生变更: 增加了 wrapcol 形参。
- base64.z85decode(s, *, ignorechars=b'', canonical=False)¶
解码经过 Z85 编码的 bytes-like object 或 ASCII 字符串 s 并返回解码后的
bytes。ignorechars 应当是一个包含要从输入中忽略的字符的 bytes-like object。
If canonical is true, non-canonical encodings are rejected. See
binascii.a2b_base85()for details.Added in version 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()返回空字节串对象。
- base64.decodebytes(s)¶
解码 bytes-like object s，该对象必须包含一行或多行 base64 编码的数据，并返回已解码的
bytes.Added in version 3.1.
- base64.encode(input, output)¶
编码二进制 input 文件的内容并将经 base64 编码的数据写入 output 文件。 input 和 output 必须为 文件对象。 input 将被读取直到
input.read()返回空字节串对象。encode()会在每输出 76 个字节之后插入一个换行符 (b'\n')，并会确保输出总是以换行符来结束，如 RFC 2045 (MIME) 所规定的那样。
- base64.encodebytes(s)¶
编码 bytes-like object s，其中可以包含任意二进制数据，并返回包含经 base64 编码数据的
bytes，每输出 76 个字节之后将带一个换行符 (b'\n')，并会确保在末尾也有一个换行符，如 RFC 2045 (MIME) 所规定的那样。Added in version 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 转换。
- RFC 1521 - MIME (Multipurpose Internet Mail Extensions) 第一部分：规定并描述因特网消息体的格式的机制。
第 5.2 节，“Base64 内容转换编码格式”提供了 base64 编码格式的定义。
- ISO 32000-2 便携式文档格式 - 第 2 部分：PDF 2.0
第 7.4.3 节“ASCII85Decode 过滤器”提供了在 PDF 和 PostScript 中使用的 Ascii85 编码的定义，包括输出字符集以及使用零填充和部分输出组保留数据长度的细节。
- ZeroMQ RFC 32/Z85
“正式规范”一节提供了 Z85 中使用的字符集。