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

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

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

このモジュールは、バイナリデータを表示可能な ASCII 文字にエンコードし
、エンコードされたデータをバイナリデータに戻す関数を提供します。 **RFC
4648** で 規定されているエンコーディング (Base64、Base32、Base16)、PDF
2.0 で規定されている Base85 エンコーディング、その他の場所で使われる
Base85 の非標準の変種を含みます。

このモジュールは、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 のサポートが追加されました。


RFC 4648 エンコーディング
=========================

**RFC 4648** エンコーディングは、email で安全に送信したり、 URL の一部
として使ったり、あるいは HTTP POST リクエストの一部に含めるために用い
るのに適しています。

base64.b64encode(s, altchars=None, *, padded=True, wrapcol=0)

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

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

   *padded* が真 (デフォルト) の場合、エンコードしたデータの長さが 4
   の倍数になるように '=' でパディングします。 *padded* が偽の場合、パ
   ディング文字を追加しません。

   *wrapcol* がゼロでない場合、最大 *wrapcol* 文字ごとに改行文字
   ("b'\n'") を挿入します。 *wrapcol* がゼロ (デフォルト) の場合、改行
   を挿入しません。

   バージョン 3.15 で変更: *padded* と *wrapcol* パラメーターが追加さ
   れました。

base64.b64decode(s, altchars=None, validate=False, *, padded=True, canonical=False)
base64.b64decode(s, altchars=None, validate=True, *, ignorechars, padded=True, canonical=False)

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

   オプション引数の *altchars* は長さ 2 の *bytes-like object*  または
   ASCII 文字列で、"+" と "/" の代わりに使われる代替アルファベットを指
   定します。

   *padded* が真の場合、Base64 アルファベットの最後の 4 文字の組には
   '=' によるパディングが必要です。 *padded* が偽の場合、パディングは
   不要で、パディングとしての認識もしません。 '=' はパディングではなく
   アルファベット外の文字として扱われるため、*validate* が偽なら黙って
   破棄されます。 *validate* が真なら、*ignorechars* に "b'='" が含ま
   れていない限り "Error" が発生します。

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

   *ignorechars* を指定する場合は、*validate* が真のときに入力から無視
   する文字を含む *bytes-like object* を渡してください。 *ignorechars*
   にパディング文字 "'='" を含めると、エンコードされたデータの末尾より
   前に現れるパディング文字や、余分なパディング文字を無視します。
   *validate* のデフォルト値は、*ignorechars* を指定した場合は "True"
   、それ以外は "False" です。

   If *validate* is false, characters that are neither in the normal
   base-64 alphabet nor (if *ignorechars* is not specified) the
   alternative alphabet are discarded prior to the padding check, but
   the "+" and "/" characters keep their meaning if they are not in
   *altchars* (they will be discarded in future Python versions).

   *validate* が真の場合、入力にこれらのアルファベット外の文字があると
   "binascii.Error" が発生します。

   *canonical* が真の場合、ゼロでないパディングビットを拒否します。 詳
   しくは "binascii.a2b_base64()" を参照してください。

   厳密な base64 チェックのについての詳細は "binascii.a2b_base64()" を
   参照してください

   バージョン 3.15 で変更: *canonical*、*ignorechars*、*padded* パラメ
   ーターが追加されました。

   バージョン 3.15 で非推奨: 代替アルファベットの使用時に "+" と "/"
   を受け入れることは非推奨になりました。

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, *, padded=True)

   *bytes-like object* *s* を、URL やファイルシステムで安全に使えるア
   ルファベットでエンコードし、エンコードされた "bytes" を返します。
   このアルファベットは、標準の Base64 アルファベットの "+" を "-" に
   、"/" を "_" に置き換えたものです。 *padded* が真 (デフォルト) の場
   合、結果には "=" が含まれることがあります。

   バージョン 3.15 で変更: *padded* パラメーターが追加されました。

base64.urlsafe_b64decode(s, *, padded=False)

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

   バージョン 3.15 で変更: *padded* パラメーターが追加されました。 デ
   フォルトでは入力のパディングが不要になりました。

   バージョン 3.15 で非推奨: "+" と "/" を受け入れることは非推奨になり
   ました。

base64.b32encode(s, *, padded=True, wrapcol=0)

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

   *padded* が真 (デフォルト) の場合、エンコードしたデータの長さが 8
   の倍数になるように '=' でパディングします。 *padded* が偽の場合、パ
   ディング文字を追加しません。

   *wrapcol* がゼロでない場合、最大 *wrapcol* 文字ごとに改行文字
   ("b'\n'") を挿入します。 *wrapcol* がゼロ (デフォルト) の場合、改行
   を追加しません。

   バージョン 3.15 で変更: *padded* と *wrapcol* パラメーターが追加さ
   れました。

base64.b32decode(s, casefold=False, map01=None, *, padded=True, ignorechars=b'', canonical=False)

   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 は入力
   として許可されていません。

   *padded* が真の場合、Base32 アルファベットの最後の 8 文字の組には
   '=' によるパディングが必要です。 *padded* が偽の場合、パディングは
   不要で、パディングとしての認識もしません。 '=' はパディングではなく
   アルファベット外の文字として扱われるため、*ignorechars* に "b'='"
   が含まれていない限り "Error" が発生します。

   *ignorechars* には、入力から無視する文字を含む *bytes-like object*
   を指定してください。

   *canonical* が真の場合、ゼロでないパディングビットを拒否します。 詳
   しくは "binascii.a2b_base32()" を参照してください。

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

   バージョン 3.15 で変更: *canonical*、*ignorechars*、*padded* パラメ
   ーターが追加されました。

base64.b32hexencode(s, *, padded=True, wrapcol=0)

   "b32encode()" に似ていますが、 **RFC 4648** で定義されているように
   Extended Hex Alphabetを使用します。

   Added in version 3.10.

   バージョン 3.15 で変更: *padded* と *wrapcol* パラメーターが追加さ
   れました。

base64.b32hexdecode(s, casefold=False, *, padded=True, ignorechars=b'', canonical=False)

   "b32decode()" に似ていますが、 **RFC 4648** で定義されているように
   Extended Hex Alphabetを使用します。

   この方式では、数字の 0 (ゼロ) を文字の O (オー) に、数字の 1 (いち)
   を文字の I (アイ) または L (エル) に対応付けることはできません。 こ
   れらはすべて Extended Hex Alphabet に含まれる別々の文字で、置き換え
   られないためです。

   Added in version 3.10.

   バージョン 3.15 で変更: *canonical*、*ignorechars*、*padded* パラメ
   ーターが追加されました。

base64.b16encode(s, *, wrapcol=0)

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

   *wrapcol* がゼロでない場合、最大 *wrapcol* 文字ごとに改行文字
   ("b'\n'") を挿入します。 *wrapcol* がゼロ (デフォルト) の場合、改行
   を追加しません。

   バージョン 3.15 で変更: *wrapcol* パラメーターが追加されました。

base64.b16decode(s, casefold=False, *, ignorechars=b'')

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

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

   *ignorechars* には、入力から無視する文字を含む *bytes-like object*
   を指定してください。

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

   バージョン 3.15 で変更: *ignorechars* パラメーターが追加されました
   。


Base85 エンコーディング
=======================

Base85 エンコーディングは、4 バイトを 5 つの ASCII 文字で表すアルゴリ
ズム群です。 もともとは Unix の "btoa(1)" ユーティリティに実装され、そ
の後 Adobe がその一種を PostScript 言語に採用し、PDF 2.0 (ISO 32000-2)
で標準化されました。 この方式の "btoa" 版と PDF 版は、どちらも
"a85encode()" に実装されています。

出力に異なる文字集合を使う別の方式は、エイプリルフールのジョークとして
**RFC 1924** で定義されましたが、現在は Git などのソフトウェアで使われ
ています。 この方式は "b85encode()" に実装されています。

さらに、プログラミング言語の文字列に安全に含められるよう設計された、別
の出力文字集合を使う 3 番目の方式を ZeroMQ が定義しています。 この方式
は "z85encode()" に実装されています。

このモジュールの各関数は、次の点の扱いが異なります。

* 囲みのマーカー "<~" と "~>" を出力に含めるか、入力に期待するか。

* 入力を複数の行に折り返すか。

* エンコードに使う ASCII 文字の集合。

* 連続するスペースやヌルバイトの短縮表現。

* 入力に加えたゼロパディングのバイトをどうエンコードするか。

詳しくは、各関数のドキュメントを参照してください。

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

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

   *foldspaces* は省略可能なフラグです。 'btoa' と同様に、連続する 4
   つのスペース (ASCII 0x20) の代わりに特別な短縮表現 'y' を使います。
   PDF で使われる標準のエンコーディングは、この機能をサポートしていま
   せん。

   *wrapcol* がゼロでない場合、最大 *wrapcol* 文字ごとに改行文字
   ("b'\n'") を挿入します。 *wrapcol* がゼロ (デフォルト) の場合、改行
   を挿入しません。

   *pad* controls whether zero-padding applied to the end of the input
   is fully retained in the output encoding, as done by "btoa",
   producing an exact multiple of 5 bytes of output. This is not part
   of the standard encoding used in PDF, as it does not preserve the
   length of the data.

   *adobe* は、PostScript の Base85 文字列リテラルのように、エンコード
   したバイト列を "<~" と "~>" で囲むかどうかを制御します。 PDF 文書の
   ASCII85Decode ストリームは "~>" で終わる *必要があります* が、先頭
   に "<~" を付けては *いけません*。

   Added in version 3.4.

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

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

   *foldspaces* は、短縮表現 'y' を連続する 4 つのスペース (ASCII
   0x20) として受け入れるかどうかを指定するフラグです。 PDF や
   PostScript で使われる標準の Ascii85 エンコーディングは、この機能を
   サポートしていません。

   *adobe* は、マーカー "<~" と "~>" の有無を指定します。 先頭の "<~"
   は必須ではありませんが、入力は "~>" で終わる必要があり、そうでなけ
   れば "ValueError" を送出します。

   *ignorechars* should be a *bytes-like object* containing characters
   to ignore from the input. This should only contain whitespace
   characters, and by default contains all whitespace characters in
   ASCII.

   *canonical* が真の場合、正規形でないエンコーディングを拒否します。
   詳しくは "binascii.a2b_ascii85()" を参照してください。

   Added in version 3.4.

   バージョン 3.15 で変更: *canonical* パラメーターが追加されました。
   最後のグループが 1 文字だけの場合は、エンコーディングの規則に違反す
   るものとして常に拒否するようになりました。

base64.b85encode(b, pad=False, *, wrapcol=0)

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

   エンコードの前に、入力の長さが 4 バイトの倍数になるよう "b'\0'" で
   パディングします。 *pad* が真の場合、結果の文字はすべて出力に残るた
   め、出力の長さは常に 5 バイトの倍数になります。 そのため、デコード
   時にデータの長さが保たれない場合があります。

   *wrapcol* がゼロでない場合、最大 *wrapcol* 文字ごとに改行文字
   ("b'\n'") を挿入します。 *wrapcol* がゼロ (デフォルト) の場合、改行
   を追加しません。

   Added in version 3.4.

   バージョン 3.15 で変更: *wrapcol* パラメーターが追加されました。

base64.b85decode(b, *, ignorechars=b'', canonical=False)

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

   *ignorechars* には、入力から無視する文字を含む *bytes-like object*
   を指定してください。

   *canonical* が真の場合、正規形でないエンコーディングを拒否します。
   詳しくは "binascii.a2b_base85()" を参照してください。

   Added in version 3.4.

   バージョン 3.15 で変更: *canonical* と *ignorechars* パラメーターが
   追加されました。 最後のグループが 1 文字だけの場合は、エンコーディ
   ングの規則に違反するものとして常に拒否するようになりました。

base64.z85encode(s, pad=False, *, wrapcol=0)

   *bytes-like object* *s* を、ZeroMQ で使われる Z85 でエンコードし、
   エンコードされた "bytes" を返します。

   エンコードの前に、入力の長さが 4 バイトの倍数になるよう "b'\0'" で
   パディングします。 *pad* が真の場合、結果の文字はすべて出力に残るた
   め、ZeroMQ の標準で要求されるとおり、出力の長さは常に 5 バイトの倍
   数になります。

   *wrapcol* がゼロでない場合、最大 *wrapcol* 文字ごとに改行文字
   ("b'\n'") を挿入します。 *wrapcol* がゼロ (デフォルト) の場合、改行
   を追加しません。

   Added in version 3.13.

   バージョン 3.15 で変更: *pad* パラメーターが追加されました。

   バージョン 3.15 で変更: *wrapcol* パラメーターが追加されました。

base64.z85decode(s, *, ignorechars=b'', canonical=False)

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

   *ignorechars* には、入力から無視する文字を含む *bytes-like object*
   を指定してください。

   *canonical* が真の場合、正規形でないエンコーディングを拒否します。
   詳しくは "binascii.a2b_base85()" を参照してください。

   Added in version 3.13.

   バージョン 3.15 で変更: *canonical* と *ignorechars* パラメーターが
   追加されました。 最後のグループが 1 文字だけの場合は、エンコーディ
   ングの規則に違反するものとして常に拒否するようになりました。


レガシーインターフェース
========================

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'


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

**RFC 4648** に、セキュリティ上の考慮事項をまとめた節 (第 12 節) が新
たに追加されました。 本番環境で使うコードでは、このセキュリティの節を
確認することを推奨します。

参考:

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

  ISO 32000-2 Portable document format - Part 2: PDF 2.0
     第 7.4.3 節 "ASCII85Decode Filter" は、PDF と PostScript で使われ
     る Ascii85 エンコーディングを定義しています。 出力の文字集合のほ
     か、ゼロパディングと部分的な出力グループによってデータ長を保持す
     る方法が詳しく説明されています。

  ZeroMQ RFC 32/Z85
     "Formal Specification" の節は、Z85 で使われる文字集合を定義してい
     ます。
