19.6. "base64" —— Base16、Base32、Base64、Base85 資料編碼
*********************************************************

**源代码：** Lib/base64.py

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

這個模組提供將二進位資料編碼成可顯示 ASCII 字元以及解碼回原始資料的功
能，包括了**RFC 3548**中的 Base16、Base32、Base64 等編碼方式，以及標準
Ascii85、Base85 編碼等。

**RFC 3548**標準編碼可以使電子郵件、URL，或是 HTTP POST 內容等傳輸管道
安全地傳遞資料。這些編碼演算法與**uuencode** 並不相同。

此模块提供了两个接口。新的接口提供了从 *类字节对象* 到 ASCII 字节
"bytes" 的编码，以及将 ASCII 的 *类字节对象* 或字符串解码到 "bytes" 的
操作。此模块支持定义在 **RFC 3548** 中的所有 base-64 字母表 （普通的、
URL 安全的和文件系统安全的）。

旧的接口不提供从字符串的解码操作，但提供了操作 *文件对象* 的编码和解码
函数。旧接口只支持标准的 Base64 字母表，并且按照 **RFC 2045** 的规范每
76 个字符增加一个换行符。注意：如果你需要支持 **RFC 2045**，那么使用
"email" 模块可能更加合适。

3.3 版更變: 新的接口提供的解码函数现在已经支持只包含 ASCII 的 Unicode
字符串。

3.4 版更變: 所有 *类字节对象* 现在已经被所有编码和解码函数接受。添加了
对 Ascii85/Base85 的支持。

新的接口提供：

base64.b64encode(s, altchars=None)

   对 *bytes-like object* *s* 进行 Base64 编码，并返回编码后的 "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'

也參考:

  模块 "binascii"
     支持模块，包含ASCII到二进制和二进制到ASCII转换。

  **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.
