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

   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)

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

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[, 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 のエンコーディング
     。

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

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

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