"base64" --- Base16, Base32, Base64, Base85 データのエンコード
**************************************************************

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

======================================================================

このモジュールは、バイナリデータを印刷可能なASCII文字列にエンコードし
て、また逆にデコードするための関数を提供しています。**RFC 4648** に定
義されている Base16、Base32、 Base64 に加えて事実上の標準となっている
Ascii85 と Base 85 をサポートしています。

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

このモジュールは、2つのインターフェースを提供します。このモダンなイン
ターフェースは、*bytes-like object* を ASCII "bytes" にエンコードし、
*bytes-like object* か ASCII 文字列を、"bytes" にデコードすることがで
きます。**RFC 4648** に定義されている 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
   アルファベットが使われます。

   *altchars* の長さが2でない場合は、 assert または "ValueError" が発
   生します。 *altchars* が *bytes-like object* でない場合は、
   "TypeError" が発生します。

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 チェックのについての詳細は "binascii.a2b_base64()" を
   参照してください

   May assert or raise a "ValueError" if the length of *altchars* is
   not 2.

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

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

base64.b32hexencode(s)

   Similar to "b32encode()" but uses the Extended Hex Alphabet, as
   defined in **RFC 4648**.

   Added in version 3.10.

base64.b32hexdecode(s, casefold=False)

   Similar to "b32decode()" but uses the Extended Hex Alphabet, as
   defined in **RFC 4648**.

   This version does not allow the digit 0 (zero) to the letter O (oh)
   and digit 1 (one) to either the letter I (eye) or letter L (el)
   mappings, all these characters are included in the Extended Hex
   Alphabet and are not interchangeable.

   Added in version 3.10.

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* controls whether the output should have newline ("b'\n'")
   characters added to it. If this is non-zero, each output line will
   be at most this many characters long, excluding the trailing
   newline.

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

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

   Added in version 3.4.

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

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

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

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

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

   Added in version 3.4.

base64.b85encode(b, pad=False)

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

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

   Added in version 3.4.

base64.b85decode(b)

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

   Added in version 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 形式でエンコードされたデータが含ま
   れている必要があります。

   Added in version 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" を返します。

   Added in version 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'


セキュリティで考慮すべき点
==========================

A new security considerations section was added to **RFC 4648**
(section 12); it's recommended to review the security section for any
code deployed to production.

参考:

  モジュール "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.
