"binascii" --- バイナリ と ASCII 間の変換
*****************************************

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

The "binascii" module contains a number of methods to convert between
binary and various ASCII-encoded binary representations. Normally, you
will not use these functions directly but use wrapper modules like
"base64" instead. The "binascii" module contains low-level functions
written in C for greater speed that are used by the higher-level
modules.

注釈:

  "a2b_*" 関数は ASCII 文字だけを含むユニコード文字列を受け取ります。
  他の関数は ("bytes" や "bytearray" またはバッファープロトコルをサポ
  ートするその他のオブジェクトのような) *bytes-like オブジェクト* だけ
  を受け取ります。

  バージョン 3.3 で変更: "a2b_*" 関数は ASCII のみのユニコード文字列を
  受け取るようになりました。

The "binascii" module defines the following functions:

binascii.a2b_uu(string)

   uuencode された 1 行のデータをバイナリに変換し、変換後のバイナリデ
   ータを返します。最後の行を除いて、通常 1 行には (バイナリデータで)
   45 バイトが含まれます。入力データの先頭には空白文字が連続していても
   かまいません。

binascii.b2a_uu(data, *, backtick=False)

   Convert binary data to a line of ASCII characters, the return value
   is the converted line, including a newline char. The length of
   *data* should be at most 45. If *backtick* is true, zeros are
   represented by "'`'" instead of spaces.

   バージョン 3.7 で変更: *backtick* パラメータを追加しました.

binascii.a2b_base64(string, /, *, padded=True, alphabet=BASE64_ALPHABET, strict_mode=False, canonical=False)
binascii.a2b_base64(string, /, *, ignorechars, padded=True, alphabet=BASE64_ALPHABET, strict_mode=True, canonical=False)

   base64 でエンコードされたデータのブロックをバイナリに変換し、変換後
   のバイナリデータを返します。一度に 1 行以上のデータを与えてもかまい
   ません。

   Optional *alphabet* must be a "bytes" object of length 64 which
   specifies an alternative alphabet.

   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 *strict_mode*
   is false, or causes an "Error" when *strict_mode* is true unless
   b'=' is included in *ignorechars*.

   If *ignorechars* is specified, it should be a *bytes-like object*
   containing characters to ignore from the input when *strict_mode*
   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
   *strict_mode* is "True" if *ignorechars* is specified, "False"
   otherwise.

   If *strict_mode* is true, only valid base64 data will be converted.
   Invalid base64 data will raise "binascii.Error".

   Valid base64:

   * Conforms to **RFC 4648**.

   * Contains only characters from the base64 alphabet.

   * Contains no excess data after padding (including excess padding,
     newlines, etc.).

   * Does not start with a padding.

   If *canonical* is true, non-zero padding bits in the last group are
   rejected with "binascii.Error", enforcing canonical encoding as
   defined in **RFC 4648** section 3.5.  This check is independent of
   *strict_mode*.

   バージョン 3.11 で変更: Added the *strict_mode* parameter.

   バージョン 3.15 で変更: Added the *alphabet*, *canonical*,
   *ignorechars*, and *padded* parameters.

binascii.b2a_base64(data, *, padded=True, alphabet=BASE64_ALPHABET, wrapcol=0, newline=True)

   Convert binary data to a line(s) of ASCII characters in base64
   coding, as specified in **RFC 4648**.

   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.

   If *newline* is true (default), a newline character will be added
   at the end of the output.

   バージョン 3.6 で変更: パラメータに *newline* を追加しました。

   バージョン 3.15 で変更: Added the *alphabet*, *padded* and
   *wrapcol* parameters.

binascii.a2b_ascii85(string, /, *, foldspaces=False, adobe=False, ignorechars=b'', canonical=False)

   Convert Ascii85 data back to binary and return the binary data.

   Valid Ascii85 data contains characters from the Ascii85 alphabet in
   groups of five (except for the final group, which may have from two
   to five characters). Each group encodes 32 bits of binary data in
   the range from "0" to "2 ** 32 - 1", inclusive. The special
   character "z" is accepted as a short form of the group "!!!!!",
   which encodes four consecutive null bytes. A single-character final
   group is always rejected as an encoding violation.

   *foldspaces* は、短い特殊文字 'y' を受け取って 4 つの連続した空白文
   字(ASCII 0x20)と解釈するかどうかを制御します。この機能は "標準"
   Ascii85 ではサポートされていません。

   *adobe* controls whether the encoded byte sequence is framed with
   "<~" and "~>", as in a PostScript base-85 string literal.  If
   *adobe* is true, a leading "<~" is optionally accepted, while a
   trailing "~>" is *required*, and "binascii.Error" is raised if it
   is not found.

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

   If *canonical* is true, non-canonical encodings are rejected with
   "binascii.Error".  Here "canonical" means the encoding that
   "b2a_ascii85()" would produce: the "z" abbreviation must be used
   for all-zero groups (rather than "!!!!!"), and partial final groups
   must use the same padding digits as the encoder.

   Invalid Ascii85 data will raise "binascii.Error".

   Added in version 3.15.

binascii.b2a_ascii85(data, /, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

   Convert binary data to a formatted sequence of ASCII characters in
   Ascii85 coding. The return value is the converted data.

   *foldspaces* を使うと、4 つの連続した空白文字(ASCII 0x20)を 'btoa'
   によってサポートされている短い特殊文字 'y' に置き換えます。この機能
   は "標準" Ascii85 ではサポートされていません。

   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.

   If *pad* is true, the 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 "<~".

   Added in version 3.15.

binascii.a2b_base85(string, /, *, alphabet=BASE85_ALPHABET, ignorechars=b'', canonical=False)

   Convert Base85 data back to binary and return the binary data. More
   than one line may be passed at a time.

   Valid Base85 data contains characters from the Base85 alphabet in
   groups of five (except for the final group, which may have from two
   to five characters). Each group encodes 32 bits of binary data in
   the range from "0" to "2 ** 32 - 1", inclusive. A single-character
   final group is always rejected as an encoding violation.

   Optional *alphabet* must be a "bytes" object of length 85 which
   specifies an alternative alphabet.

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

   If *canonical* is true, non-canonical encodings are rejected with
   "binascii.Error".  Here "canonical" means the encoding that
   "b2a_base85()" would produce: partial final groups must use the
   same padding digits as the encoder.

   Invalid Base85 data will raise "binascii.Error".

   Added in version 3.15.

binascii.b2a_base85(data, /, *, alphabet=BASE85_ALPHABET, wrapcol=0, pad=False)

   Convert binary data to a line of ASCII characters in Base85 coding.
   The return value is the converted line.

   Optional *alphabet* must be a *bytes-like object* of length 85
   which specifies an alternative alphabet.

   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.

   If *pad* is true, the zero-padding applied to the end of the input
   is 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.

   Added in version 3.15.

binascii.a2b_base32(string, /, *, padded=True, alphabet=BASE32_ALPHABET, ignorechars=b'', canonical=False)

   Convert base32 data back to binary and return the binary data.

   Valid base32 data contains characters from the base32 alphabet
   specified in **RFC 4648** in groups of eight (if necessary, the
   final group is padded to eight characters with "="). Each group
   encodes 40 bits of binary data in the range from "0" to "2 ** 40 -
   1", inclusive.

   注釈:

     This function does not map lowercase characters (which are
     invalid in standard base32) to their uppercase counterparts, nor
     does it contextually map "0" to "O" and "1" to "I"/"L" as **RFC
     4648** allows.

   Optional *alphabet* must be a "bytes" object of length 32 which
   specifies an alternative alphabet.

   If *padded* is true, the last group of 8 base 32 alphabet
   characters must be padded with the '=' character. If *padded* is
   false, the '=' character is treated as other non-alphabet
   characters (depending on the value of *ignorechars*).

   *ignorechars* should be a *bytes-like object* containing characters
   to ignore from the input. 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.

   If *canonical* is true, non-zero padding bits in the last group are
   rejected with "binascii.Error", enforcing canonical encoding as
   defined in **RFC 4648** section 3.5.

   Invalid base32 data will raise "binascii.Error".

   Added in version 3.15.

binascii.b2a_base32(data, /, *, padded=True, alphabet=BASE32_ALPHABET, wrapcol=0)

   Convert binary data to a line of ASCII characters in base32 coding,
   as specified in **RFC 4648**. The return value is the converted
   line.

   Optional *alphabet* must be a *bytes-like object* of length 32
   which specifies an alternative alphabet.

   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 insert any newlines.

   Added in version 3.15.

binascii.a2b_qp(data, header=False)

   quoted-printable 形式のデータをバイナリに変換し、バイナリデータを返
   します。一度に 1 行以上のデータを渡すことができます。オプション引数
   *header* が与えられており、かつその値が真であれば、アンダースコアは
   空白文字にデコードされます。

binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)

   バイナリデータを quoted-printable 形式でエンコードして 1 行から複数
   行の ASCII 文字列に変換します。変換後の文字列を返します。オプション
   引数 *quptetabs* が存在し、かつその値が真であれば、全てのタブおよび
   空白文字もエンコードされます。オプション引数 *istext* が存在し、か
   つその値が真であれば、改行はエンコードされませんが、行末の空白文字
   はエンコードされます。オプション引数 *header* が存在し、かつその値
   が真である場合、空白文字は **RFC 1522** にしたがってアンダースコア
   にエンコードされます。オプション引数 *header* が存在し、かつその値
   が偽である場合、改行文字も同様にエンコードされます。そうでない場合
   、復帰 (linefeed) 文字の変換によってバイナリデータストリームが破損
   してしまうかもしれません。

binascii.crc_hqx(data, value)

   *value* を CRC の初期値として *data* の 16 ビット CRC 値を計算し、
   その結果を返します。 この関数は、よく 0x1021 と表現される CRC-CCITT
   多項式 *x*^16 + *x*^12 + *x*^5 + 1 を使います。 この CRC は binhex4
   形式で使われています。

binascii.crc32(data[, value])

   符号無し 32 ビットチェックサムである CRC-32 を *data* に対して計算
   します。 crc の初期値は *value* です。デフォルトの CRC の初期値はゼ
   ロです。このアルゴリズムは ZIP ファイルのチェックサムと同じです。こ
   のアルゴリズムはチェックサムアルゴリズムとして設計されたもので、一
   般的なハッシュアルゴリズムには向きません。以下のようにして使います:

      print(binascii.crc32(b"hello world"))
      # Or, in two pieces:
      crc = binascii.crc32(b"hello")
      crc = binascii.crc32(b" world", crc)
      print('crc32 = {:#010x}'.format(crc))

   バージョン 3.0 で変更: The result is always unsigned.

binascii.b2a_hex(data[, sep[, bytes_per_sep=1]])
binascii.hexlify(data[, sep[, bytes_per_sep=1]])

   バイナリ *data* の16進表現を返します。*data* の各バイトは、対応する
   2桁の16進表現に変換されます。したがって、返されるバイトオブジェクト
   は *data* の2倍の長さになります。

   Similar functionality (but returning a text string) is also
   conveniently accessible using the "bytes.hex()" method.

   If *sep* is specified, it must be a single character str or bytes
   object. It will be inserted in the output after every
   *bytes_per_sep* input bytes. Separator placement is counted from
   the right end of the output by default, if you wish to count from
   the left, supply a negative *bytes_per_sep* value.

   >>> import binascii
   >>> binascii.b2a_hex(b'\xb9\x01\xef')
   b'b901ef'
   >>> binascii.hexlify(b'\xb9\x01\xef', '-')
   b'b9-01-ef'
   >>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2)
   b'b9_01ef'
   >>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2)
   b'b901 ef'

   バージョン 3.8 で変更: 引数 *sep* と *bytes_per_sep* が追加されまし
   た.

binascii.a2b_hex(hexstr, *, ignorechars=b'')
binascii.unhexlify(hexstr, *, ignorechars=b'')

   16進数表記の文字列 *hexstr* の表すバイナリデータを返します。この関
   数は "b2a_hex()" の逆です。 *hexstr* は 16進数字 (大文字でも小文字
   でも構いません) を偶数個含んでいなければなりません。そうでない場合
   、例外 "Error" が送出されます。

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

   Similar functionality (accepting only text string arguments, but
   more liberal towards whitespace) is also accessible using the
   "bytes.fromhex()" class method.

   バージョン 3.15 で変更: Added the *ignorechars* parameter.

exception binascii.Error

   エラーが発生した際に送出される例外です。通常はプログラムのエラーで
   す。

exception binascii.Incomplete

   変換するデータが不完全な場合に送出される例外です。通常はプログラム
   のエラーではなく、多少追加読み込みを行って再度変換を試みることで対
   処できます。

binascii.BASE64_ALPHABET

   The Base 64 alphabet according to **RFC 4648**.

   Added in version 3.15.

binascii.URLSAFE_BASE64_ALPHABET

   The "URL and filename safe" Base 64 alphabet according to **RFC
   4648**.

   Added in version 3.15.

binascii.UU_ALPHABET

   The uuencoding alphabet.

   Added in version 3.15.

binascii.CRYPT_ALPHABET

   The Base 64 alphabet used in the *crypt(3)* routine and in the
   GEDCOM format.

   Added in version 3.15.

binascii.BINHEX_ALPHABET

   The Base 64 alphabet used in BinHex 4 (HQX) within the classic Mac
   OS.

   Added in version 3.15.

binascii.BASE85_ALPHABET

   The Base85 alphabet.

   Added in version 3.15.

binascii.ASCII85_ALPHABET

   The Ascii85 alphabet.

   Added in version 3.15.

binascii.Z85_ALPHABET

   The Z85 alphabet.

   Added in version 3.15.

binascii.BASE32_ALPHABET

   The Base 32 alphabet according to **RFC 4648**.

   Added in version 3.15.

binascii.BASE32HEX_ALPHABET

   The "Extended Hex" Base 32 alphabet according to **RFC 4648**. Data
   encoded with this alphabet maintains its sort order during bitwise
   comparisons.

   Added in version 3.15.

参考:

  "base64" モジュール
     RFC 準拠の base64 形式の、底が 16、32、64、85 のエンコーディング
     。

  "quopri" モジュール
     MIME 電子メールメッセージで使われる quoted-printable エンコードの
     サポート。
