`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, /, *, padded=True, alphabet=BASE64_ALPHABET, strict_mode=False, canonical=False)¶

binascii.a2b_base64(string, /, *, ignorechars, padded=True, alphabet=BASE64_ALPHABET, strict_mode=True, canonical=False)

base64 でエンコードされたデータのブロックをバイナリに変換し、変換後のバイナリデータを返します。一度に 1 行以上のデータを与えてもかまいません。

省略可能な alphabet には、代替アルファベットを指定する長さ 64 の bytes オブジェクトを渡してください。

padded が真の場合、Base64 アルファベットの最後の 4 文字の組には '=' によるパディングが必要です。 padded が偽の場合、パディングは不要で、パディングとしての認識もしません。 '=' はパディングではなくアルファベット外の文字として扱われるため、strict_mode が偽なら黙って破棄されます。 strict_mode が真なら、ignorechars に b'=' が含まれていない限り Error が発生します。

ignorechars を指定する場合は、strict_mode が真のときに入力から無視する文字を含む bytes-like object を渡してください。 ignorechars にパディング文字 '=' を含めると、エンコードされたデータの末尾より前に現れるパディング文字や、余分なパディング文字を無視します。 strict_mode のデフォルト値は、ignorechars を指定した場合は True、それ以外は False です。

strict_mode が真の場合、有効な Base64 データのみ変換します。無効な Base64 データでは binascii.Error を送出します。

有効な Base64 データの条件:

RFC 4648 に準拠している。
Base64 アルファベットの文字だけを含む。
パディングの後に余分なデータ (余分なパディングや改行などを含む) がない。
パディングで始まらない。

canonical が真の場合、最後のグループのゼロでないパディングビットを binascii.Error で拒否し、RFC 4648 の第 3.5 節で定義された正規形のエンコーディングを要求します。この検査は strict_mode とは独立しています。

バージョン 3.11 で変更: strict_mode パラメーターが追加されました。

バージョン 3.15 で変更: alphabet、canonical、ignorechars、padded パラメーターが追加されました。

binascii.b2a_base64(data, *, padded=True, alphabet=BASE64_ALPHABET, wrapcol=0, newline=True)¶

バイナリデータを、RFC 4648 で規定された Base64 エンコーディングで、1 行以上の ASCII 文字列に変換します。

padded が真 (デフォルト) の場合、エンコードしたデータの長さが 4 の倍数になるように '=' でパディングします。 padded が偽の場合、パディング文字を追加しません。

wrapcol がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を挿入しません。

newline が真 (デフォルト) の場合、出力の末尾に改行文字を追加します。

バージョン 3.6 で変更: パラメータに newline を追加しました。

バージョン 3.15 で変更: alphabet、padded、wrapcol パラメーターが追加されました。

binascii.a2b_ascii85(string, /, *, foldspaces=False, adobe=False, ignorechars=b'', canonical=False)¶

Ascii85 データをバイナリに戻し、バイナリデータを返します。

有効な Ascii85 データは、Ascii85 アルファベットの文字を 5 文字ずつのグループにしたものです (最後のグループは 2～5 文字でもかまいません)。各グループは 0 から 2 ** 32 - 1 までの範囲の 32 ビットのバイナリデータを表します。特別な文字 z は、連続する 4 つのヌルバイトを表すグループ !!!!! の短縮形として受け入れられます。最後のグループが 1 文字だけの場合は、エンコーディングの規則に違反するものとして常に拒否します。

foldspaces は、短い特殊文字 'y' を受け取って 4 つの連続した空白文字(ASCII 0x20)と解釈するかどうかを制御します。この機能は "標準" Ascii85 ではサポートされていません。

adobe は、PostScript の Base85 文字列リテラルのように、エンコードされたバイト列が <~ と ~> で囲まれているかどうかを指定します。 adobe が真の場合、先頭の <~ は省略できますが、末尾の ~> は必須です。末尾のマーカーがなければ binascii.Error を送出します。

ignorechars には、入力から無視する文字を含む bytes-like object を指定してください。空白文字だけを含めるようにしてください。

canonical が真の場合、正規形でないエンコーディングを binascii.Error で拒否します。ここで「正規形」とは、b2a_ascii85() が生成するエンコーディングです。すべてゼロのグループには !!!!! ではなく短縮形 z を使い、最後の不完全なグループにはエンコーダーと同じパディング桁を使う必要があります。

無効な Ascii85 データでは binascii.Error を送出します。

Added in version 3.15.

binascii.b2a_ascii85(data, /, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)¶

バイナリデータを Ascii85 エンコーディングで整形された ASCII 文字列に変換し、変換結果を返します。

foldspaces を使うと、4 つの連続した空白文字(ASCII 0x20)を 'btoa' によってサポートされている短い特殊文字 'y' に置き換えます。この機能は "標準" Ascii85 ではサポートされていません。

wrapcol がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を挿入しません。

If pad is true, the zero-padding applied to the end of the input is fully retained in the output encoding, as done by btoa, producing an exact multiple of 5 bytes of output. This is not part of the standard encoding used in PDF, as it does not preserve the length of the data.

adobe は、PostScript の Base85 文字列リテラルのように、エンコードしたバイト列を <~ と ~> で囲むかどうかを制御します。 PDF 文書の ASCII85Decode ストリームは ~> で終わる 必要があります が、先頭に <~ を付けては いけません。

Added in version 3.15.

binascii.a2b_base85(string, /, *, alphabet=BASE85_ALPHABET, ignorechars=b'', canonical=False)¶

Base85 データをバイナリに戻し、バイナリデータを返します。一度に複数行を渡すこともできます。

有効な Base85 データは、Base85 アルファベットの文字を 5 文字ずつのグループにしたものです (最後のグループは 2～5 文字でもかまいません)。各グループは 0 から 2 ** 32 - 1 までの範囲の 32 ビットのバイナリデータを表します。最後のグループが 1 文字だけの場合は、エンコーディングの規則に違反するものとして常に拒否します。

省略可能な alphabet には、代替アルファベットを指定する長さ 85 の bytes オブジェクトを渡してください。

ignorechars には、入力から無視する文字を含む bytes-like object を指定してください。

canonical が真の場合、正規形でないエンコーディングを binascii.Error で拒否します。ここで「正規形」とは、b2a_base85() が生成するエンコーディングです。最後の不完全なグループには、エンコーダーと同じパディング桁を使う必要があります。

無効な Base85 データでは binascii.Error を送出します。

Added in version 3.15.

binascii.b2a_base85(data, /, *, alphabet=BASE85_ALPHABET, wrapcol=0, pad=False)¶

バイナリデータを Base85 エンコーディングで 1 行の ASCII 文字列に変換し、その行を返します。

省略可能な alphabet には、代替アルファベットを指定する長さ 85 の bytes-like object を渡してください。

wrapcol がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を挿入しません。

pad が真の場合、入力の末尾に加えたゼロパディングを出力に残すため、出力の長さは常に 5 バイトの倍数になります。そのため、デコード時にデータの長さが保たれない場合があります。

Added in version 3.15.

binascii.a2b_base32(string, /, *, padded=True, alphabet=BASE32_ALPHABET, ignorechars=b'', canonical=False)¶

Base32 データをバイナリに戻し、バイナリデータを返します。

有効な Base32 データは、RFC 4648 で規定された Base32 アルファベットの文字を 8 文字ずつのグループにしたものです (必要なら、最後のグループを = で 8 文字までパディングします)。各グループは 0 から 2 ** 40 - 1 までの範囲の 40 ビットのバイナリデータを表します。

注釈

この関数は、標準の Base32 では無効な小文字を大文字に変換しません。また、RFC 4648 で許可されている、文脈に応じた 0 から O への変換や 1 から I または L への変換も行いません。

省略可能な alphabet には、代替アルファベットを指定する長さ 32 の bytes オブジェクトを渡してください。

padded が真の場合、Base32 アルファベットの最後の 8 文字の組には '=' によるパディングが必要です。 padded が偽の場合、'=' は他のアルファベット外の文字と同様に、ignorechars の値に応じて扱われます。

ignorechars には、入力から無視する文字を含む bytes-like object を指定してください。 ignorechars にパディング文字 '=' を含めると、エンコードされたデータの末尾より前に現れるパディング文字や、余分なパディング文字を無視します。

canonical が真の場合、最後のグループのゼロでないパディングビットを binascii.Error で拒否し、RFC 4648 の第 3.5 節で定義された正規形のエンコーディングを要求します。

無効な Base32 データでは binascii.Error を送出します。

Added in version 3.15.

binascii.b2a_base32(data, /, *, padded=True, alphabet=BASE32_ALPHABET, wrapcol=0)¶

バイナリデータを、RFC 4648 で規定された Base32 エンコーディングで 1 行の ASCII 文字列に変換し、その行を返します。

省略可能な alphabet には、代替アルファベットを指定する長さ 32 の bytes-like object を渡してください。

padded が真 (デフォルト) の場合、エンコードしたデータの長さが 8 の倍数になるように '=' でパディングします。 padded が偽の場合、パディング文字を追加しません。

wrapcol がゼロでない場合、最大 wrapcol 文字ごとに改行文字 (b'\n') を挿入します。 wrapcol がゼロ (デフォルト) の場合、改行を挿入しません。

Added in version 3.15.

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 多項式 x¹⁶ + x¹² + x⁵ + 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, *, ignorechars=b'')¶

binascii.unhexlify(hexstr, *, ignorechars=b'')¶

16進数表記の文字列 hexstr の表すバイナリデータを返します。この関数は b2a_hex() の逆です。 hexstr は 16進数字 (大文字でも小文字でも構いません) を偶数個含んでいなければなりません。そうでない場合、例外 Error が送出されます。

ignorechars には、入力から無視する文字を含む bytes-like object を指定してください。

同様の機能は bytes.fromhex() クラスメソッドからも使えます (ただし空白文字をより寛容に受け入れます)。

バージョン 3.15 で変更: ignorechars パラメーターが追加されました。

exception binascii.Error¶: エラーが発生した際に送出される例外です。通常はプログラムのエラーです。

exception binascii.Incomplete¶: 変換するデータが不完全な場合に送出される例外です。通常はプログラムのエラーではなく、多少追加読み込みを行って再度変換を試みることで対処できます。

binascii.BASE64_ALPHABET¶: RFC 4648 で規定された Base64 アルファベットです。

Added in version 3.15.

binascii.URLSAFE_BASE64_ALPHABET¶: RFC 4648 で規定された、URL とファイル名で安全に使える Base64 アルファベットです。

Added in version 3.15.

binascii.UU_ALPHABET¶: uuencode のアルファベットです。

Added in version 3.15.

binascii.CRYPT_ALPHABET¶: crypt(3) ルーチンと GEDCOM 形式で使われる Base64 アルファベットです。

Added in version 3.15.

binascii.BINHEX_ALPHABET¶: 従来の Mac OS で BinHex 4 (HQX) に使われる Base64 アルファベットです。

Added in version 3.15.

binascii.BASE85_ALPHABET¶: Base85 アルファベットです。

Added in version 3.15.

binascii.ASCII85_ALPHABET¶: Ascii85 アルファベットです。

Added in version 3.15.

binascii.Z85_ALPHABET¶: Z85 アルファベットです。

Added in version 3.15.

binascii.BASE32_ALPHABET¶: RFC 4648 で規定された Base32 アルファベットです。

Added in version 3.15.

binascii.BASE32HEX_ALPHABET¶: RFC 4648 で規定された "Extended Hex" Base32 アルファベットです。このアルファベットでエンコードしたデータは、ビット単位の比較でもソート順を保ちます。

Added in version 3.15.

参考

base64 モジュール: RFC 準拠の base64 形式の、底が 16、32、64、85 のエンコーディング。
quopri モジュール: MIME 電子メールメッセージで使われる quoted-printable エンコードのサポート。

`binascii` --- バイナリと ASCII 間の変換¶

前のトピックへ

次のトピックへ

このページ

binascii --- バイナリ と ASCII 間の変換¶

`binascii` --- バイナリと ASCII 間の変換¶