binascii --- バイナリ と ASCII 間の変換¶
binascii モジュールは、バイナリデータと、ASCII でエンコードされたさまざまなバイナリ表現との間で変換するための関数を提供します。
通常はこれらの関数を直接使わず、base64 などのラッパーモジュールを使います。
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)¶
バイナリデータを 1 行の ASCII 文字列に変換し、改行文字を含む変換結果を返します。 data の長さは 45 以下でなければなりません。 backtick が真の場合、ゼロをスペースではなく
'`'で表します。バージョン 3.7 で変更: backtick パラメータを追加しました.
- binascii.a2b_base64(string, /, *, strict_mode=False)¶
base64 でエンコードされたデータのブロックをバイナリに変換し、変換後のバイナリデータを返します。一度に 1 行以上のデータを与えてもかまいません。
strict_mode が真の場合、有効な Base64 データのみ変換します。 無効な Base64 データでは
binascii.Errorを送出します。有効な Base64 データの条件:
Conforms to RFC 3548.
Base64 アルファベットの文字だけを含む。
パディングの後に余分なデータ (余分なパディングや改行などを含む) がない。
パディングで始まらない。
バージョン 3.11 で変更: strict_mode パラメーターが追加されました。
- binascii.b2a_base64(data, *, newline=True)¶
Convert binary data to a line of ASCII characters in base64 coding. The return value is the converted line, including a newline char if newline is true. The output of this function conforms to 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 文字列に変換します。 変換後の文字列を返します。 オプション引数 quotetabs が存在し、かつその値が真であれば、全てのタブおよび空白文字もエンコードされます。 オプション引数 istext が存在し、かつその値が真であれば、改行はエンコードされませんが、行末の空白文字はエンコードされます。 オプション引数 header が存在し、かつその値が真である場合、空白文字は RFC 1522 にしたがってアンダースコアにエンコードされます。 オプション引数 header が存在し、かつその値が偽である場合、改行文字も同様にエンコードされます。 そうでない場合、改行 (linefeed) 文字の変換によってバイナリデータストリームが破損してしまうかもしれません。
- 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")) # または、2 つに分けて計算する: crc = binascii.crc32(b"hello") crc = binascii.crc32(b" world", crc) print('crc32 = {:#010x}'.format(crc))
バージョン 3.0 で変更: 結果は常に符号なしになりました。
- binascii.b2a_hex(data[, sep[, bytes_per_sep=1]])¶
- binascii.hexlify(data[, sep[, bytes_per_sep=1]])¶
バイナリ data の16進表現を返します。data の各バイトは、対応する2桁の16進表現に変換されます。したがって、返されるバイトオブジェクトは data の2倍の長さになります。
同様の機能は
bytes.hex()メソッドからも手軽に使えます (ただしテキスト文字列を返します)。sep を指定する場合は、1 文字の
strまたはbytesオブジェクトでなければなりません。 入力の bytes_per_sep バイトごとに、出力に区切り文字を挿入します。 デフォルトでは出力の右端から数えて区切り文字を配置します。 左端から数えるには bytes_per_sep に負の値を指定してください。>>> 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が送出されます。同様の機能は
bytes.fromhex()クラスメソッドからも使えます (ただし空白文字をより寛容に受け入れます)。
- exception binascii.Error¶
エラーが発生した際に送出される例外です。通常はプログラムのエラーです。
- exception binascii.Incomplete¶
変換するデータが不完全な場合に送出される例外です。通常はプログラムのエラーではなく、多少追加読み込みを行って再度変換を試みることで対処できます。