"base64" --- Base16, Base32, Base64, Base85 Data Encodings
**********************************************************

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

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

This module provides functions for encoding binary data to printable
ASCII characters and decoding such encodings back to binary data. It
provides encoding and decoding functions for the encodings specified
in **RFC 4648**, which defines the Base16, Base32, and Base64
algorithms, and for the de-facto standard Ascii85 and Base85
encodings.

The **RFC 4648** encodings are suitable for encoding binary data so
that it can be safely sent by email, used as parts of URLs, or
included as part of an HTTP POST request.  The encoding algorithm is
not the same as the **uuencode** program.

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

The legacy interface does not support decoding from strings, but it
does provide functions for encoding and decoding to and from *file
objects*.  It only supports the Base64 standard alphabet, and it adds
newlines every 76 characters as per **RFC 2045**.  Note that if you
are looking for **RFC 2045** support you probably want to be looking
at the "email" package instead.

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

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

The modern interface provides:

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()" を
   参照してください

   *altchars* の長さが2でない場合は、 assert または
   :exc:>>`<<ValueError`が発生します。

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)

   :func:>>`<<b32encode`に似ていますが、:rfc:>>`<<4648`で定義されてい
   るようにExtended Hex Alphabetを使用します。

   バージョン 3.10 で追加.

base64.b32hexdecode(s, casefold=False)

   :func:>>`<<b32decode`に似ていますが、:rfc:>>`<<4648`で定義されてい
   るようにExtended Hex Alphabetを使用します。

   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.

   バージョン 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.

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

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

   バージョン 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 における空白
   文字全てです。

   バージョン 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 で追加.

The legacy interface:

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'


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

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.
