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 多項式 x16 + x12 + x5 + 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¶ 変換するデータが不完全な場合に送出される例外です。通常はプログラムのエラーではなく、多少追加読み込みを行って再度変換を試みることで対処できます。