"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 object* を ASCII "bytes" にエンコードし、
*bytes-like object* か ASCII 文字列を、"bytes" にデコードすることがで
きます。**RFC 3548** に定義されている base-64 アルファベット (一般の、
URL あるいはファイルシステムセーフなもの) の両方が使用できます。

従来のインターフェースは文字列からのデコードができませんが、*file
object* との間のエンコードとデコードが可能な関数を提供します。これは標
準の 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)

   *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 で追加.

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

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.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 で追加.

モジュールの使用例:

>>> 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.
