19.8. binascii — バイナリデータと ASCIIデータとの間での変換

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

注釈

a2b_* 関数は ASCII 文字だけを含むユニコード文字列を受け取ります。他の関数は (bytesbytearray またはバッファープロトコルをサポートするその他のオブジェクトのような) bytes-like object だけを受け取ります。

バージョン 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 行の文字列で、改行文字を含みます。base64 標準を遵守するためには、data の長さは 57 バイト以下でなくてはなりません。

binascii.a2b_qp(string, header=False)

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

binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)

バイナリデータを quoted-printable 形式でエンコードして 1 行から複数行の ASCII 文字列に変換します。変換後の文字列を返します。オプション引数 quotetabs が存在し、かつその値が真であれば、全てのタブおよび空白文字もエンコードされます。オプション引数 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, crc)

data の binhex4 CRC 値を計算します。初期値は crc で、計算結果を返します。

binascii.crc32(data[, crc])

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

print(binascii.crc32(b"hello world"))
# Or, in two pieces:
crc = binascii.crc32(b"hello")
crc = binascii.crc32(b" world", crc) & 0xffffffff
print('crc32 = {:#010x}'.format(crc))

注釈

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

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 モジュール

MIME 電子メールメッセージで使われる base64 エンコードのサポート。

binhex モジュール

Macintosh で使われる binhex フォーマットのサポート。

uu モジュール

Unixで使われる UU エンコードのサポート。

quopri モジュール

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