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** プログラムで用いられているものとは同じではありません。

There are two interfaces provided by this module.  The modern
interface supports encoding *bytes-like objects* to ASCII "bytes", and
decoding *bytes-like objects* or strings containing ASCII to "bytes".
Both base-64 alphabets defined in **RFC 3548** (normal, and URL- and
filesystem-safe) are supported.

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 のサポートが追加されました。

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

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" 例外を発
   生させます。

   If *validate* is "False" (the default), characters that are neither
   in the normal base-64 alphabet nor the alternative alphabet are
   discarded prior to the padding check.  If *validate* is "True",
   these non-alphabet characters in the input result in a
   "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)

   Encode *bytes-like object* *s* using the URL- and filesystem-safe
   alphabet, which substitutes "-" instead of "+" and "_" instead of
   "/" in the standard Base64 alphabet, and return the encoded
   "bytes".  The result can still contain "=".

base64.urlsafe_b64decode(s)

   Decode *bytes-like object* or ASCII string *s* using the URL- and
   filesystem-safe alphabet, which substitutes "-" instead of "+" and
   "_" instead of "/" in the standard Base64 alphabet, and return the
   decoded "bytes".

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)

   Encode the *bytes-like object* *b* using Ascii85 and return the
   encoded "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')

   Decode the Ascii85 encoded *bytes-like object* or ASCII string *b*
   and return the decoded "bytes".

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

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

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

   バージョン 3.4 で追加.

base64.b85encode(b, pad=False)

   Encode the *bytes-like object* *b* using base85 (as used in e.g.
   git-style binary diffs) and return the encoded "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)

   Decode the *bytes-like object* *s*, which must contain one or more
   lines of base64 encoded data, and return the decoded "bytes".

   バージョン 3.1 で追加.

base64.decodestring(s)

   Deprecated alias of "decodebytes()".

   バージョン 3.1 で非推奨.

base64.encode(input, output)

   Encode the contents of the binary *input* file and write the
   resulting base64 encoded data to the *output* file. *input* and
   *output* must be *file objects*. *input* will be read until
   "input.read()" returns an empty bytes object. "encode()" inserts a
   newline character ("b'\n'") after every 76 bytes of the output, as
   well as ensuring that the output always ends with a newline, as per
   **RFC 2045** (MIME).

base64.encodebytes(s)

   Encode the *bytes-like object* *s*, which can contain arbitrary
   binary data, and return "bytes" containing the base64-encoded data,
   with newlines ("b'\n'") inserted after every 76 bytes of output,
   and ensuring that there is a trailing newline, as per **RFC 2045**
   (MIME).

   バージョン 3.1 で追加.

base64.encodestring(s)

   Deprecated alias of "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.
