19.6. base64 --- Base16, Base32, Base64, Base85 データの符号化

ソースコード: Lib/base64.py

このモジュールはバイナリデータを印字可能な ASCII にエンコード関数、およびそのようなエンコードデータをバイナリにデコードする関数を提供します。それらは、RFC 3548 が定義する Base16, Base32, Base64 のエンコーディング、デファクトスタンダードになっている Ascii85, Base85 のエンコーディングについてのエンコード、デコード関数です。

RFC 3548 エンコーディングは、email で安全に送信したり、 URL の一部として使ったり、あるいは HTTP POST リクエストの一部に含めるために用いるのに適しています。このエンコーディングで使われているアルゴリズムは uuencode プログラムで用いられているものとは同じではありません。

このモジュールは、2つのインターフェースを提供します。このモダンなインターフェースは、bytes-like objects を ASCII bytes にエンコードし、bytes-like objects か ASCII 文字列を、bytes にデコードすることができます。RFC 3548 に定義されている base-64 アルファベット (一般の、URL あるいはファイルシステムセーフなもの) の両方が使用できます。

従来のインターフェースは文字列からのデコードができませんが、file objects ` との間のエンコードとデコードが可能な関数を提供します。これは標準の base64 アルファベットのみをサポートし、:rfc:`2045 の規定にあるように、76文字ごとに改行されます。RFC 2045 のサポートのためには、代わりに email パッケージを参照する必要があるかもしれません。

バージョン 3.3 で変更: モダンなインターフェイスのデコード関数が ASCII のみの Unicode 文字列を受け付けるようになりました。

バージョン 3.4 で変更: このモジュールのすべてのエンコード・デコード関数が任意の bytes-like オブジェクト を受け取るようになりました。Ascii85/Base85 のサポートが追加されました。

モダンなインターフェイスは以下のものを提供します:

base64.b64encode(s, altchars=None)

Base64 を使って bytes-like object の s をエンコードし、エンコードされた bytes を返します。

オプション引数 altchars は最低でも 2 の長さをもつ bytes-like object で (これ以降の文字は無視されます)、これは + と / の代わりに使われる代替アルファベットを指定します。これにより、アプリケーションはたとえば URL やファイルシステムの影響をうけない Base64 文字列を生成することができます。デフォルトの値は None で、これは標準の Base64 アルファベット集合が使われることを意味します。

base64.b64decode(s, altchars=None, validate=False)

Base64 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた bytes を返します。

オプション引数の altchars は最低でも 2 の長さをもつ bytes-like object または ASCII 文字列で (これ以降の文字は無視されます)、これは + と / の代わりに使われる代替アルファベットを指定します。

s が正しくパディングされていない場合は binascii.Error 例外を発生させます。

validate が False (デフォルト) の場合、標準の base64 アルファベットでも代替文字でもない文字はパディングチェックの前に無視されます。 validate が True の場合、入力に base64 アルファベット以外の文字があると binascii.Error を発生させます。

base64.standard_b64encode(s)

標準の base64 アルファベットを使用して bytes-like object の s をエンコードし、エンコードされた bytes を返します。

base64.standard_b64decode(s)

標準の base64 アルファベットを使用した bytes-like object または ASCII 文字列 s をデコードし、デコードされた bytes を返します。

base64.urlsafe_b64encode(s)

term:bytes-like object の s を URLとファイルシステムセーフなアルファベットを利用してエンコードし、エンコードされた bytes を返します。標準 base64 アルファベットに比べて、+ の替わりに - を、/ の替わりに _ を利用します。結果は = を含みます。

base64.urlsafe_b64decode(s)

bytes-like object または ASCII 文字列の s を URLとファイルシステムセーフなアルファベットを利用してデコードし、デコードされた bytes を返します。標準 base64 アルファベットに比べて、+ の替わりに - を、/ の替わりに _ を置換します。

base64.b32encode(s)

Base32 を使って bytes-like object の s をエンコードし、エンコードされた bytes を返します。

base64.b32decode(s, casefold=False, map01=None)

Base32 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた bytes を返します。

オプション引数 casefold は小文字のアルファベットを受けつけるかどうかを指定します。セキュリティ上の理由により、デフォルトではこれは False になっています。

RFC 3548 は付加的なマッピングとして、数字の 0 (零) をアルファベットの O (オー) に、数字の 1 (壱) をアルファベットの I (アイ) または L (エル) に対応させることを許しています。オプション引数は map01 は、 None でないときは、数字の 1 をどの文字に対応づけるかを指定します (map01 が None でないとき、数字の 0 はつねにアルファベットの O (オー) に対応づけられます)。セキュリティ上の理由により、これはデフォルトでは None になっているため、 0 および 1 は入力として許可されていません。

s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、 binascii.Error 例外を発生させます。

base64.b16encode(s)

Base16 を使って bytes-like object の s をエンコードし、エンコードされた bytes を返します。

base64.b16decode(s, casefold=False)

Base16 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた bytes を返します。

オプション引数 casefold は小文字のアルファベットを受けつけるかどうかを指定します。セキュリティ上の理由により、デフォルトではこれは False になっています。

s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、 binascii.Error 例外を発生させます。

base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

Ascii85 を使って bytes-like object の b をエンコードし、エンコードされた bytes を返します。

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

wrapcol は何文字ごとに改行文字 (b'\n') を挿入するかを制御します。ゼロでない場合、出力の各行はこの与えられた文字数を超えません。

pad を指定すると、エンコード前に入力が 4 の倍数になるようにパディングされます。なお、 btoa の実装は常にパディングします。

adobe を指定すると、エンコードしたバイトシーケンスを <~ と ~> で囲みます。これは Adobe の実装で使われています。

バージョン 3.4 で追加.

base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')

Ascii85 エンコードされた bytes-like object または ASCII 文字列 b をデコードし、デコードされた bytes を返します。

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

adobe で、入力シーケンスが Adobe Ascii85 (つまり <~ と ~> で囲まれている)かどうかを伝えます。

ignorechars には、入力に含まれていれば無視する文字で構成された bytes-like object または ASCII 文字列を指定してください。これは空白文字だけで構成されているべきです。デフォルトは ASCII における空白文字全てです。

バージョン 3.4 で追加.

base64.b85encode(b, pad=False)

base85 (これは例えば git スタイルのバイナリ diff で用いられています) を使って bytes-like object の b をエンコードし、エンコードされた bytes を返します。

pad が真ならば、エンコードに先立って、バイト数が 4 の倍数となるように入力が b'\0' でパディングされます。

バージョン 3.4 で追加.

base64.b85decode(b)

base85でエンコードされた bytes-like object または ASCII 文字列の b をデコードし、デコードされた bytes を返します。パディングは、もしあれば、暗黙に削除されます。

バージョン 3.4 で追加.

注釈

Both Base85 and Ascii85 have an expansion factor of 5 to 4 (5 Base85 or Ascii85 characters can encode 4 binary bytes), while the better-known Base64 has an expansion factor of 6 to 4. They are therefore more efficient when space expensive. They differ by details such as the character map used for encoding.

レガシーなインターフェイスは以下のものを提供します:

base64.decode(input, output)

input ファイルの中身をデコードし、結果のバイナリデータを output ファイルに出力します。 input 、 output ともに file objects でなければなりません。 input は input.readline() が空バイト列を返すまで読まれます。

base64.decodebytes(s)

bytes-like object の s をデコードし、デコードされた bytes を返します。 s には一行以上の base64 形式でエンコードされたデータが含まれている必要があります。

バージョン 3.1 で追加.

base64.decodestring(s)

decodestring は廃止されたエイリアスです。

バージョン 3.1 で非推奨.

base64.encode(input, output)

バイナリの input ファイルの中身を base64 形式でエンコードした結果を output ファイルに出力します。 input 、 output ともに file objects でなければなりません。 input は input.read() が空バイト列を返すまで読まれます。 encode() は76バイトの出力ごとに改行文字(b'\n')を挿入し、RFC 2045 (MIME) の規定にあるように常に出力が新しい行で終わることを保証します。

base64.encodebytes(s)

bytes-like object s (任意のバイナリデータを含むことができます) を、RFC 2045 (MIME) に規定されるように末尾に新しい行のある、76バイトの出力ごとに新しい行 (b'\n') が挿入された、base64 形式でエンコードしたデータを含む bytes を返します。

バージョン 3.1 で追加.

base64.encodestring(s)

encodebytes() は廃止されたエイリアスです。

バージョン 3.1 で非推奨.

モジュールの使用例:

>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'

参考

モジュール binascii
ASCII からバイナリへ、バイナリから ASCII への変換をサポートするモジュール。
RFC 1521 - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the base64 encoding.