"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 "Error" when *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* 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 版本发生变更: 增加了 *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 encoded
   "bytes".  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 "Error" unless 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 中使用的字符集。
