19.6. "base64" --- Base16, Base32, Base64, Base85 数据编码
**********************************************************

**Source code:** Lib/base64.py

======================================================================

此模块提供了将二进制数据编码为可打印的 ASCII 字符以及将其解码为二进制
的函数。它为 **RFC 3548** 指定的编码（包括 Base16, Base32 和 Base64 算
法），以及已被广泛接受的 Ascii85 和 Base85 编码提供了编码(encoding)和
解码(decoding)函数。

**RFC 3548** 编码是编码二进制数据的一个合适的编码，它可以安全地被电子
邮件发送，用作 URL 的一部分，或者被包含进一段 HTTP POST request 中。编
码算法和 **uuencode** 程序不同。

此模块提供了两个接口。现代的接口提供了从 *类字节对象* 到 ASCII 字节
"bytes" 的编码，和从包含了 ASCII 的 *类字节对象* 或字符串到 "bytes" 的
解码。定义在 **RFC 3548** 中的 base-64 字母表 (normal, and URL- and
filesystem-safe) 都被支持。

传统接口并不提供从字符串的解码，不过提供了 *文件对象* 编码、解码函数。
这只支持标准 Base64 字母表，并且根据 **RFC 2045**，每 76 个字符增加一
个换行符。注意，如果你正在寻找 **RFC 2045** 支持，你可能得查看 "email"
包来代替。

在 3.3 版更改: 只有 ASCII 的 Unicode 字符串现在被现代接口的解码函数接
受。

在 3.4 版更改: 任何 *类字节对象* 现在起被所有编码、解码函数接受。添加
了 Ascii85/Base85 支持。

现代接口提供：

base64.b64encode(s, altchars=None)

   用 Base64 编码 *bytes-like object* *s* 并返回编码过的 "bytes"

   可选项 *altchars* 必须是一个长 2 字节的 *bytes-like object*，它指定
   了用于替换 "+" 和 "/" 的字符。这允许应用程序生成 URL 或文件系统安全
   的 Base64 字符串。默认值是 "None"，使用标准 Base64 字母表。

base64.b64decode(s, altchars=None, validate=False)

   解码 Base64 编码过的 *bytes-like object* 或 ASCII 字符串 *s* 并返回
   解码过的 "bytes"。

   可选项 *altchars* 必须是一个长 2 字节的 *bytes-like object*，它指定
   了用于替换 "+" 和 "/" 的字符。

   如果 *s* 被不正确地填写，一个 "binascii.Error" 错误将被抛出。

   如果 *validate* 值为 "False" （默认情况），则在填充检查前，将丢弃既
   不在标准 base-64 字母表之中也不在备用字母表中的字符。如果
   *validate* 为 "True"，这些非 base64 字符将导致 "binascii.Error"。

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)

   编码 *bytes-like object* *s*，使用 URL 与文件系统安全的字母表，使用
   "-" 以及 "_" 代替标准 Base64 字母表中的 "+" 和 "/"。返回编码过的
   "bytes"。结果中可能包含 "="。

base64.urlsafe_b64decode(s)

   解码 *bytes-like object* 或 ASCII 字符串 *s*，使用 URL 与文件系统安
   全的字母表，使用 "-" 以及 "_" 代替标准 Base64 字母表中的 "+" 和 "/"
   。返回解码过的 "bytes"

base64.b32encode(s)

   用 Base32 编码 *bytes-like object* *s* 并返回编码过的 "bytes"

base64.b32decode(s, casefold=False, map01=None)

   解码 Base32 编码过的 *bytes-like object* 或 ASCII 字符串 *s* 并返回
   解码过的 "bytes"。

   可选的 *casefold* 是一个指定小写字幕是否可接受为输入的标志。为了安
   全考虑，默认值为 "False"。

   **RFC 3548** 允许将字母 0(zero) 映射为字母 O(oh)，并可以选择是否将
   字母 1(one) 映射为 I(eye) 或 L(el)。可选参数 *map01* 不是 "None" 时
   ，它的值指定 1 的映射目标 (I 或 l)，当 *map01* 非 "None" 时， 0 总
   是被映射为 O。为了安全考虑，默认值被设为 "None"，如果是这样， 0 和
   1 不允许被作为输入。

   如果 *s* 被错误地填写或输入中存在字母表之外的字符，将抛出
   "binascii.Error"。

base64.b16encode(s)

   用 Base16 编码 *bytes-like object* *s* 并返回编码过的 "bytes"

base64.b16decode(s, casefold=False)

   解码 Base16 编码过的 *bytes-like object* 或 ASCII 字符串 *s* 并返回
   解码过的 "bytes"。

   可选的 *casefold* 是一个指定小写字幕是否可接受为输入的标志。为了安
   全考虑，默认值为 "False"。

   如果 *s* 被错误地填写或输入中存在字母表之外的字符，将抛出
   "binascii.Error"。

base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

   用 Ascii85 编码 *bytes-like object* *s* 并返回编码过的 "bytes"

   *foldspaces* 是一个可选的标志，使用特殊的短序列 'y' 代替 'btoa' 提
   供的 4 个连续空格 (ASCII 0x20)。这个特性不被 "标准" Ascii85 编码支
   持。

   *wrapcol* 控制了输出是否包含换行符 ("b'\n'"). 如果该值非零, 则每一
   行只有该值所限制的字符长度.

   *pad* 控制在编码之前输入是否填充为4的倍数。请注意，"btoa" 实现总是
   填充。

   *adobe* controls whether the encoded byte sequence is framed with
   "<~" and "~>", which is used by the Adobe implementation.

   3.4 新版功能.

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

   解码 Ascii85 编码过的 *bytes-like object* 或 ASCII 字符串 *s* 并返
   回解码过的 "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.

   *adobe* controls whether the input sequence is in Adobe Ascii85
   format (i.e. is framed with <~ and ~>).

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

   3.4 新版功能.

base64.b85encode(b, pad=False)

   Encode the *bytes-like object* *b* using base85 (as used in e.g.
   git-style binary diffs) and return the encoded "bytes".

   If *pad* is true, the input is padded with "b'\0'" so its length is
   a multiple of 4 bytes before encoding.

   3.4 新版功能.

base64.b85decode(b)

   Decode the base85-encoded *bytes-like object* or ASCII string *b*
   and return the decoded "bytes".  Padding is implicitly removed, if
   necessary.

   3.4 新版功能.

The legacy interface:

base64.decode(input, output)

   Decode the contents of the binary *input* file and write the
   resulting binary data to the *output* file. *input* and *output*
   must be *file objects*. *input* will be read until
   "input.readline()" returns an empty bytes object.

base64.decodebytes(s)

   Decode the *bytes-like object* *s*, which must contain one or more
   lines of base64 encoded data, and return the decoded "bytes".

   3.1 新版功能.

base64.decodestring(s)

   Deprecated alias of "decodebytes()".

   3.1 版后已移除.

base64.encode(input, output)

   Encode the contents of the binary *input* file and write the
   resulting base64 encoded data to the *output* file. *input* and
   *output* must be *file objects*. *input* will be read until
   "input.read()" returns an empty bytes object. "encode()" inserts a
   newline character ("b'\n'") after every 76 bytes of the output, as
   well as ensuring that the output always ends with a newline, as per
   **RFC 2045** (MIME).

base64.encodebytes(s)

   Encode the *bytes-like object* *s*, which can contain arbitrary
   binary data, and return "bytes" containing the base64-encoded data,
   with newlines ("b'\n'") inserted after every 76 bytes of output,
   and ensuring that there is a trailing newline, as per **RFC 2045**
   (MIME).

   3.1 新版功能.

base64.encodestring(s)

   Deprecated alias of "encodebytes()".

   3.1 版后已移除.

An example usage of the module:

>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'

参见:

  Module "binascii"
     Support module containing ASCII-to-binary and binary-to-ASCII
     conversions.

  **RFC 1521** - MIME (Multipurpose Internet Mail Extensions) Part
  One: Mechanisms for Specifying and Describing the Format of Internet
  Message Bodies
     Section 5.2, "Base64 Content-Transfer-Encoding," provides the
     definition of the base64 encoding.
