"base64" --- Base16、Base32、Base64、Base85 資料編碼
****************************************************

**原始碼：** Lib/base64.py

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

This module provides functions for encoding binary data to printable
ASCII characters and decoding such encodings back to binary data. This
includes the encodings specified in **RFC 4648** (Base64, Base32 and
Base16), the Base85 encoding specified in PDF 2.0, and non-standard
variants of Base85 used elsewhere.

該模組提供了兩個介面。新介面支援將*類位元組物件* 編碼成 ASCII "bytes"
，並將包含 ASCII 的*類位元組物件*或字串解碼為 "bytes"。支援 **RFC
4648** 中定義的兩種 base-64 字母表（常見和 URL 安全 (URL-safe) 及檔案
系統安全 (filesystem-safe) 字母表）。

舊版介面不支援從字串解碼，但它提供對*檔案物件*進行編碼和解碼的函式。它
僅支援 Base64 標準字母表，並且按照 **RFC 2045** 每 76 個字元添加換行字
元。請注意，如果你需要 **RFC 2045** 的支援，你可能會需要 "email" 函式
庫。

在 3.3 版的變更: 新介面的解碼功能現在接受 ASCII-only 的 Unicode 字串。

在 3.4 版的變更: 任何*類位元組物件*現在被該模組中的所有編碼和解碼函式
接受。新增了對 Ascii85/Base85 的支援。


RFC 4648 編碼
=============

**RFC 4648** 編碼適合對二進位資料進行編碼來使得電子郵件、URL 或是 HTTP
POST 內容等傳輸管道能夠安全地傳遞資料。

base64.b64encode(s, altchars=None, *, padded=True, wrapcol=0)

   使用 Base64 對*類位元組物件* *s* 進行編碼並回傳編碼過的 "bytes"。

   可選的 *altchars* 必須是一個長度為 2 的*類位元組物件*，用來指定替代
   的字母表，以替換 "+" 和 "/" 字元。這使得應用程式可以生成對 URL 或檔
   案系統安全的 Base64 字串。預設值為 "None"，即使用標準的 Base64 字母
   表。

   If *padded* is true (default), pad the encoded data with the '='
   character to a size multiple of 4. 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 insert any newlines.

   在 3.15 版的變更: Added the *padded* and *wrapcol* parameters.

base64.b64decode(s, altchars=None, validate=False, *, padded=True, canonical=False)
base64.b64decode(s, altchars=None, validate=True, *, ignorechars, padded=True, canonical=False)

   將經過 Base64 編碼的*類位元組物件*或 ASCII 字串 *s* 解碼，並回傳解
   碼後的 "bytes"。

   可選的 *altchars* 必須是長度為 2 的*類位元組物件*或 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* 填充 (pad) 不正確，將引發 "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 版的變更: Added the *canonical*, *ignorechars*, and
   *padded* parameters.

   在 3.15 版之後被棄用: Accepting the "+" and "/" characters with an
   alternative alphabet is now deprecated.

base64.standard_b64encode(s)

   使用標準 Base64 字母表對*類位元組物件* *s* 進行編碼，並回傳編碼後的
   "bytes"。

base64.standard_b64decode(s)

   使用標準 Base64 字母表對*類位元組物件*或 ASCII 字串 *s* 進行解碼，
   並回傳解碼後的 "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 版的變更: Added the *padded* parameter.

base64.urlsafe_b64decode(s, *, padded=False)

   使用 URL 安全和檔案系統安全字母表對*類位元組物件*或 ASCII 字串 *s*
   進行解碼，該字母表將標準 Base64 字母表中的 "+" 替換為 "-"，"/" 替換
   為 "_"，並回傳解碼後的 "bytes"。

   在 3.15 版的變更: Added the *padded* parameter. Padding of input is
   no longer required by default.

   在 3.15 版之後被棄用: Accepting the "+" and "/" characters is now
   deprecated.

base64.b32encode(s, *, padded=True, wrapcol=0)

   使用 Base32 對*類位元組物件* *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 版的變更: Added the *padded* and *wrapcol* parameters.

base64.b32decode(s, casefold=False, map01=None, *, padded=True, ignorechars=b'', canonical=False)

   解碼經過 Base32 編碼的*類位元組物件*或 ASCII 字串 *s*，並回傳解碼後
   的 "bytes"。

   可選的 *casefold* 是一個是否接受小寫字母表作為輸入的旗標。出於安全
   性考量，預設值為 "False"。

   **RFC 4648** 允許將數字 0 選擇性地對應對映為字母 O，並且允許將數字
   1 選擇性地對映為字母 I 或字母 L。當可選的引數 *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* should be a *bytes-like object* containing characters
   to ignore from the input.

   If *canonical* is true, non-zero padding bits are rejected. See
   "binascii.a2b_base32()" for details.

   如果 *s* 的填充不正確或輸入中存在非字母表字元，將引發
   "binascii.Error"。

   在 3.15 版的變更: Added the *canonical*, *ignorechars*, and
   *padded* parameters.

base64.b32hexencode(s, *, padded=True, wrapcol=0)

   類似於 "b32encode()"，但使用在 **RFC 4648** 中定義的擴展十六進位字
   母表 (Extended Hex Alphabet)。

   在 3.10 版被加入.

   在 3.15 版的變更: Added the *padded* and *wrapcol* parameters.

base64.b32hexdecode(s, casefold=False, *, padded=True, ignorechars=b'', canonical=False)

   類似於 "b32decode()"，但使用在 **RFC 4648** 中定義的擴展十六進位字
   母表。

   這個版本不允許將數字 0 對映為字母 O ，以及將數字 1 對映為字母 I 或
   字母 L，所有這些字元都包含在擴展十六進位字母表中，並且不能互換使用
   。

   在 3.10 版被加入.

   在 3.15 版的變更: Added the *canonical*, *ignorechars*, and
   *padded* parameters.

base64.b16encode(s, *, wrapcol=0)

   使用 Base16 對*類位元組物件* *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 版的變更: Added the *wrapcol* parameter.

base64.b16decode(s, casefold=False, *, ignorechars=b'')

   解碼經過 Base16 編碼的*類位元組物件*或 ASCII 字串 *s*，並回傳解碼後
   的 "bytes"。

   可選的 *casefold* 是一個是否接受小寫字母表作為輸入的旗標。出於安全
   性考量，預設值為 "False"。

   *ignorechars* should be a *bytes-like object* containing characters
   to ignore from the input.

   如果 *s* 的填充不正確或輸入中存在非字母表字元，將引發
   "binascii.Error"。

   在 3.15 版的變更: Added the *ignorechars* parameter.


Base85 編碼
===========

Base85 encoding is a family of algorithms which represent four bytes
using five ASCII characters.  Originally implemented in the Unix
"btoa(1)" utility, a version of it was later adopted by Adobe in the
PostScript language and is standardized in PDF 2.0 (ISO 32000-2). This
version, in both its "btoa" and PDF variants, is implemented by
"a85encode()".

A separate version, using a different output character set, was
defined as an April Fool's joke in **RFC 1924** but is now used by Git
and other software.  This version is implemented by "b85encode()".

Finally, a third version, using yet another output character set
designed for safe inclusion in programming language strings, is
defined by ZeroMQ and implemented here by "z85encode()".

The functions present in this module differ in how they handle the
following:

* Whether to include and expect enclosing "<~" and "~>" markers.

* Whether to fold the input into multiple lines.

* The set of ASCII characters used for encoding.

* Compact encodings of sequences of spaces and null bytes.

* The encoding of zero-padding bytes applied to the input.

Refer to the documentation of the individual functions for more
information.

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

   使用 Ascii85 對*類位元組物件* *b* 進行編碼，並回傳編碼後的 "bytes"
   。

   *foldspaces* is an optional flag that uses the special short
   sequence 'y' instead of 4 consecutive spaces (ASCII 0x20) as
   supported by 'btoa'. This feature is not supported by the standard
   encoding used in PDF.

   If *wrapcol* is non-zero, insert a newline ("b'\n'") character
   after at most every *wrapcol* characters. If *wrapcol* is zero
   (default), do not insert any newlines.

   *pad* controls whether zero-padding applied to the end of the input
   is fully retained in the output encoding, as done by "btoa",
   producing an exact multiple of 5 bytes of output. This is not part
   of the standard encoding used in PDF, as it does not preserve the
   length of the data.

   *adobe* controls whether the encoded byte sequence is framed with
   "<~" and "~>", as in a PostScript base-85 string literal.  Note
   that while ASCII85Decode streams in PDF documents *must* be
   terminated with "~>", they *must not* use a leading "<~".

   在 3.4 版被加入.

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

   解碼經過 Ascii85 編碼的*類位元組物件*或 ASCII 字串 *b*，並回傳解碼
   後的 "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 used in PDF and PostScript.

   *adobe* controls whether the "<~" and "~>" markers are present.
   While the leading "<~" is not required, the input must end with
   "~>", or a "ValueError" is raised.

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

   If *canonical* is true, non-canonical encodings are rejected. See
   "binascii.a2b_ascii85()" for details.

   在 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 風格的二進位差異 (binary diff)）對*類位元組
   物件* *b* 進行編碼，並回傳編碼後的 "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, and thus the length of the data may not be
   preserved on decoding.

   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.4 版被加入.

   在 3.15 版的變更: Added the *wrapcol* parameter.

base64.b85decode(b, *, ignorechars=b'', canonical=False)

   Decode the base85-encoded *bytes-like object* or ASCII string *b*
   and return the decoded "bytes".

   *ignorechars* should be a *bytes-like object* containing characters
   to ignore from the input.

   If *canonical* is true, non-canonical encodings are rejected. See
   "binascii.a2b_base85()" for details.

   在 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)

   Encode the *bytes-like object* *s* using Z85 (as used in ZeroMQ)
   and return the encoded "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.

   在 3.13 版被加入.

   在 3.15 版的變更: The *pad* parameter was added.

   在 3.15 版的變更: Added the *wrapcol* parameter.

base64.z85decode(s, *, ignorechars=b'', canonical=False)

   Decode the Z85-encoded *bytes-like object* or ASCII string *s* and
   return the decoded "bytes".

   *ignorechars* should be a *bytes-like object* containing characters
   to ignore from the input.

   If *canonical* is true, non-canonical encodings are rejected. See
   "binascii.a2b_base85()" for details.

   在 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()" 回傳一個空的 bytes 物件為止。

base64.decodebytes(s)

   解碼必須包含一行或多行的 base64 編碼資料*類位元組物件* *s*，並回傳
   解碼後的 "bytes"。

   在 3.1 版被加入.

base64.encode(input, output)

   編碼二進位檔案 *input* 的內容，並將結果的 base64 編碼資料寫入
   *output* 檔案。*input* 和 *output* 必須是*檔案物件*。*input* 將被讀
   取，直到 "input.read()" 回傳一個空的 bytes 物件為止。"encode()" 會
   在輸出的每 76 個位元組之後插入一個換行字元 ("b'\n'")，並確保輸出始
   終以換行字元結尾，符合 **RFC 2045** (MIME) 的規定。

base64.encodebytes(s)

   對包含任意二進位資料的*類位元組物件* *s* 進行編碼，並回傳包含
   base64 編碼資料 "bytes"，在每 76 個輸出位元組後插入換行字元
   ("b'\n'") ，並確保有尾隨換行字元，符合 **RFC 2045** (MIME) 的規定。

   在 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-to-binary) 和二進位到 ASCII
     (binary-to-ASCII) 的轉換功能。

  **RFC 1521** - MIME（多用途網際網路郵件擴展）第一部分：指定和描述網
  際網路主體格式的機制。
     第 5.2 節，"Base64 Content-Transfer-Encoding"，提供了 base64 編碼
     的定義。

  ISO 32000-2 Portable document format - Part 2: PDF 2.0
     Section 7.4.3, "ASCII85Decode Filter," provides the definition of
     the Ascii85 encoding used in PDF and PostScript, including the
     output character set and the details of data length preservation
     using zero-padding and partial output groups.

  ZeroMQ RFC 32/Z85
     The "Formal Specification" section provides the character set
     used in Z85.
