19.8. "binascii" --- バイナリデータと ASCII データとの間での変換
****************************************************************

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

"binascii" モジュールにはバイナリと ASCII コード化されたバイナリ表現と
の間の変換を行うための多数のメソッドが含まれています。通常、これらの関
数を直接使う必要はなく、 "uu" 、 "base64" や "binhex" といった、ラッパ
(wrapper) モジュールを使うことになるでしょう。 "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)

   バイナリデータを uuencode して 1 行の ASCII 文字列に変換します。戻
   り値は変換後の 1 行の文字列で、改行を含みます。 *data* の長さは 45
   バイト以下でなければなりません。

binascii.a2b_base64(string)

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

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)

   Convert binary data to a line(s) of ASCII characters in quoted-
   printable encoding.  The return value is the converted line(s). If
   the optional argument *quotetabs* is present and true, all tabs and
   spaces will be encoded.   If the optional argument *istext* is
   present and true, newlines are not encoded but trailing whitespace
   will be encoded. If the optional argument *header* is present and
   true, spaces will be encoded as underscores per **RFC 1522**. If
   the optional argument *header* is present and false, newline
   characters will be encoded as well; otherwise linefeed conversion
   might corrupt the binary data stream.

binascii.a2b_hqx(string)

   binhex4 形式の ASCII 文字列データを RLE 展開を行わないでバイナリに
   変換します。文字列はバイナリのバイトデータを完全に含むような長さか
   、または (binhex4 データの最後の部分の場合) 余白のビットがゼロにな
   っていなければなりません。

binascii.rledecode_hqx(data)

   *data* に対し、 binhex4 標準に従って RLE 展開を行います。このアルゴ
   リズムでは、あるバイトの後ろに "0x90" がきた場合、そのバイトの反復
   を指示しており、さらにその後ろに反復カウントが続きます。カウントが
   "0" の場合 "0x90" 自体を示します。このルーチンは入力データの末端に
   おける反復指定が不完全でないかぎり解凍されたデータを返しますが、不
   完全な場合、例外 "Incomplete" が送出されます。

   バージョン 3.2 で変更: 入力として bytestring または bytearray オブ
   ジェクトのみを受け取ります。

binascii.rlecode_hqx(data)

   binhex4 方式の RLE 圧縮を *data* に対して行い、その結果を返します。

binascii.b2a_hqx(data)

   バイナリを hexbin4 エンコードして ASCII 文字列に変換し、変換後の文
   字列を返します。引数の *data* はすでに RLE エンコードされていなけれ
   ばならず、その長さは (最後のフラグメントを除いて) 3 で割り切れなけ
   ればなりません。

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 で変更: 結果は常に unsigned です。すべてのバージョン
   とプラットフォームの Python に渡って同一の数値を生成するには、
   "crc32(data) & 0xffffffff" を使用します。

binascii.b2a_hex(data)
binascii.hexlify(data)

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

binascii.a2b_hex(hexstr)
binascii.unhexlify(hexstr)

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

exception binascii.Error

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

exception binascii.Incomplete

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

参考:

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

  "binhex" モジュール
     Macintosh で使われる binhex フォーマットのサポート。

  "uu" モジュール
     Unix で使われる UU エンコードのサポート。

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