"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*^16 + *x*^12 + *x*^5 + 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 エンコードの
     サポート。
