# `base64` --- Base16, Base32, Base64, Base85 データのエンコード

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

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

このモジュールは、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)

  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)

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

## Base85 エンコーディング

Base85 encoding is not formally specified but rather a de facto standard, thus different systems perform the encoding differently.

The `a85encode()` and `b85encode()` functions in this module are two implementations of the de facto standard. You should call the function with the Base85 implementation used by the software you intend to work with.

The two functions present in this module differ in how they handle the following:

- Whether to include enclosing `<~` and `~>` markers

- Whether to include newline characters

- The set of ASCII characters used for encoding

- Handling of null bytes

Refer to the documentation of the individual functions for more information.

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.z85encode(s)

  Encode the bytes-like object s using Z85 (as used in ZeroMQ) and return the encoded `bytes`. See Z85 specification for more information.

  Added in version 3.13.

base64.z85decode(s)

  Decode the Z85-encoded bytes-like object or ASCII string s and return the decoded `bytes`. See Z85 specification for more information.

  Added in version 3.13.

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

  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.