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

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

"binascii" モジュールにはバイナリと ASCII コード化されたバイナリ表現と
の間の変換を行うための多数のメソッドが含まれています。通常はこれらの関
数を直接使わずに  "base64" といったラッパーモジュールを使います。
"binascii" モジュールは C で書かれた高速な低水準関数を提供していて、そ
れらは上記の高水準なモジュールで利用されます。

注釈:

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

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

"binascii" モジュールでは以下の関数を定義します:

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, /, *, strict_mode=False)

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

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

   Valid base64:

   * Conforms to **RFC 3548**.

   * Contains only characters from the base64 alphabet.

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

   * Does not start with a padding.

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

binascii.b2a_base64(data, *, newline=True)

   バイナリデータを base64 でエンコードされた 1 行の ASCII 文字列に変
   換します。戻り値は変換後の 1 行の文字列で、*newline* が真の場合改行
   文字を含みます。この関数の出力は **RFC 3548** を遵守します。

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

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)
binascii.unhexlify(hexstr)

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

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

exception binascii.Error

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

exception binascii.Incomplete

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

参考:

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

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