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)¶ バイナリデータを base64 でエンコードして 1 行の ASCII 文字列に変換します。戻り値は変換後の 1 行の文字列で、改行文字を含みます。出力には改行コードが追加されます。これはこの関数の元々のユースケースが、MIME-base64 標準に準拠するための出力行を得るために 57 バイトずつ data を読んで都度出力を供給する、というものであったためです。このユースケースでの利用でないならば、出力は RFC 3548 に準拠します(—訳注: MIME-base64: RFC 1521 、 base64: RFC 3548 —)。
-
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 が存在し、かつその値が真である場合、空白文字は RFC1522 にしたがってアンダースコアにエンコードされます。オプション引数 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 多項式 x16 + x12 + x5 + 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¶ 変換するデータが不完全な場合に送出される例外です。通常はプログラムのエラーではなく、多少追加読み込みを行って再度変換を試みることで対処できます。