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

"binascii" モジュールにはバイナリと ASCII コード化されたバイナリ表現と
の間の変換を行うための多数のメソッドが含まれています。通常、これらの関
数を直接使う必要はなく、 "uu" 、 "base64" や "binhex" といった、ラッパ
(wrapper) モジュールを使うことになるでしょう。 "binascii" モジュールは
、高レベルなモジュールで利用される、高速な C で書かれた低レベル関数を
提供しています。

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

   バイナリデータを base64 でエンコードして 1 行の ASCII 文字列に変換
   します。戻り値は変換後の 1 行の文字列で、改行文字を含みます。出力に
   は改行コードが追加されます。これはこの関数の元々のユースケースが、
   MIME-base64 標準に準拠するための出力行を得るために 57 バイトずつ
   data を読んで都度出力を供給する、というものであったためです。このユ
   ースケースでの利用でないならば、出力は **RFC 3548** に準拠します
   (---訳注: MIME-base64: **RFC 1521** 、 base64: **RFC 3548** ---)。

binascii.a2b_qp(string[, header])

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

binascii.b2a_qp(data[, quotetabs, istext, header])

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

binascii.a2b_hqx(string)

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

binascii.rledecode_hqx(data)

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

binascii.rlecode_hqx(data)

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

binascii.b2a_hqx(data)

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

binascii.crc_hqx(data, crc)

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

binascii.crc32(data[, crc])

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

      print binascii.crc32("hello world")
      # Or, in two pieces:
      crc = binascii.crc32("hello")
      crc = binascii.crc32(" world", crc) & 0xffffffff
      print 'crc32 = 0x%08x' % crc

注釈: 全ての Python のバージョン、全てのプラットフォームに渡って同じ
  数値を 生成しようとするならば、 "crc32(data) & 0xffffffff" を使って
  下さい。 チェックサムをバイナリ形式そのままでだけ扱うならばこのよう
  な細工は必 要ありません。返値は符号に関係なく正しい32ビットのバイナ
  リ表現だから です。

バージョン 2.6 で変更: 返値はどのプラットフォームでも [-2**31,
2**31-1] の範囲の値です。過去においては返値はあるプラットフォームでは
符号付きでまた別のところでは符号無しでした。 3.0 における振る舞いに合
わせるためには & 0xffffffff を施して下さい。

バージョン 3.0 で変更: 戻り値の範囲は、プラットフォームに関係なく [0,
2**32-1] の範囲の符号無しです。

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 進数字 (大文字でも小文字
   でもかまいません) を偶数個含んでいなければなりません。そうでないば
   あい、例外 "TypeError" が送出されます。

exception binascii.Error

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

exception binascii.Incomplete

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

参考:

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

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

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

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