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

   Convert binary data to a line of ASCII characters in base64 coding.
   The return value is the converted line, including a newline char.
   The newline is added because the original use case for this
   function was to feed it a series of 57 byte input lines to get
   output lines that conform to the MIME-base64 standard.  Otherwise
   the output conforms to **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)

   Compute a 16-bit CRC value of *data*, starting with an initial
   *crc* and returning the result.  This uses the CRC-CCITT polynomial
   *x*^16 + *x*^12 + *x*^5 + 1, often represented as 0x1021.  This CRC
   is used in the binhex4 format.

binascii.crc32(data[, crc])

   Compute CRC-32, the 32-bit checksum of data, starting with an
   initial crc.  This is consistent with the ZIP file checksum.  Since
   the algorithm is designed for use as a checksum algorithm, it is
   not suitable for use as a general hash algorithm.  Use as follows:

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

注釈: To generate the same numeric value across all Python versions
  and platforms use crc32(data) & 0xffffffff.  If you are only using
  the checksum in packed binary format this is not necessary as the
  return value is the correct 32bit binary representation regardless
  of sign.

バージョン 2.6 で変更: The return value is in the range [-2**31,
2**31-1] regardless of platform.  In the past the value would be
signed on some platforms and unsigned on others.  Use & 0xffffffff on
the value if you want it to match Python 3 behavior.

バージョン 3.0 で変更: The return value is unsigned and in the range
[0, 2**32-1] regardless of platform.

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

   Return the hexadecimal representation of the binary *data*.  Every
   byte of *data* is converted into the corresponding 2-digit hex
   representation.  The resulting string is therefore twice as long as
   the length of *data*.

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

   Return the binary data represented by the hexadecimal string
   *hexstr*.  This function is the inverse of "b2a_hex()". *hexstr*
   must contain an even number of hexadecimal digits (which can be
   upper or lower case), otherwise a "TypeError" is raised.

exception binascii.Error

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

exception binascii.Incomplete

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

参考:

  "base64" モジュール
     Support for RFC compliant base64-style encoding in base 16, 32,
     and 64.

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

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

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