"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.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 版新加入.

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.
