base64 --- Base16, Base32, Base64, Base85 データのエンコード¶
ソースコード: Lib/base64.py
This module provides functions for encoding binary data to printable ASCII characters and decoding such encodings back to binary data. This includes the encodings specified in RFC 4648 (Base64, Base32 and Base16), the Base85 encoding specified in PDF 2.0, and non-standard variants of Base85 used elsewhere.
このモジュールは、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 アルファベットが使われます。If padded is true (default), pad the encoded data with the '=' character to a size multiple of 4. If padded is false, do not add the pad characters.
If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.バージョン 3.15 で変更: Added the padded and wrapcol parameters.
- 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 文字列で、
+と/の代わりに使われる代替アルファベットを指定します。If padded is true, the last group of 4 base 64 alphabet characters must be padded with the '=' character. If padded is false, padding is neither required nor recognized: the '=' character is not treated as padding but as a non-alphabet character, which means it is silently discarded when validate is false, or causes an
Errorwhen validate is true unless b'=' is included in ignorechars.s が正しくパディングされていない場合は
binascii.Error例外を発生させます。If ignorechars is specified, it should be a bytes-like object containing characters to ignore from the input when validate is true. If ignorechars contains the pad character
'=', the pad characters presented before the end of the encoded data and the excess pad characters will be ignored. The default value of validate isTrueif ignorechars is specified,Falseotherwise.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).If validate is true, these non-alphabet characters in the input result in a
binascii.Error.If canonical is true, non-zero padding bits are rejected. See
binascii.a2b_base64()for details.厳密な base64 チェックのについての詳細は
binascii.a2b_base64()を参照してくださいバージョン 3.15 で変更: Added the canonical, ignorechars, and padded parameters.
バージョン 3.15 で非推奨: Accepting the
+and/characters with an alternative alphabet is now deprecated.
- 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)¶
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 encodedbytes. The result can still contain=if padded is true (default).バージョン 3.15 で変更: Added the padded parameter.
- base64.urlsafe_b64decode(s, *, padded=False)¶
bytes-like object または ASCII 文字列 s を URLとファイルシステムセーフなアルファベットを利用してデコードし、デコードされた
bytesを返します。標準 base64 アルファベットに比べて、+の替わりに-を、/の替わりに_を置換します。バージョン 3.15 で変更: Added the padded parameter. Padding of input is no longer required by default.
バージョン 3.15 で非推奨: Accepting the
+and/characters is now deprecated.
- base64.b32encode(s, *, padded=True, wrapcol=0)¶
Base32 を使って bytes-like object の s をエンコードし、エンコードされた
bytesを返します。If padded is true (default), pad the encoded data with the '=' character to a size multiple of 8. If padded is false, do not add the pad characters.
If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.バージョン 3.15 で変更: Added the padded and wrapcol parameters.
- 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 は入力として許可されていません。If padded is true, the last group of 8 base 32 alphabet characters must be padded with the '=' character. If padded is false, padding is neither required nor recognized: the '=' character is not treated as padding but as a non-alphabet character, which means it raises an
Errorunless b'=' is included in ignorechars.ignorechars should be a bytes-like object containing characters to ignore from the input.
If canonical is true, non-zero padding bits are rejected. See
binascii.a2b_base32()for details.s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、
binascii.Error例外を発生させます。バージョン 3.15 で変更: Added the canonical, ignorechars, and padded parameters.
- base64.b32hexencode(s, *, padded=True, wrapcol=0)¶
:func:`b32encode`に似ていますが、:rfc:`4648`で定義されているようにExtended Hex Alphabetを使用します。
Added in version 3.10.
バージョン 3.15 で変更: Added the padded and wrapcol parameters.
- base64.b32hexdecode(s, casefold=False, *, padded=True, ignorechars=b'', canonical=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.
Added in version 3.10.
バージョン 3.15 で変更: Added the canonical, ignorechars, and padded parameters.
- base64.b16encode(s, *, wrapcol=0)¶
Base16 を使って bytes-like object の s をエンコードし、エンコードされた
bytesを返します。If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.バージョン 3.15 で変更: Added the wrapcol parameter.
- base64.b16decode(s, casefold=False, *, ignorechars=b'')¶
Base16 エンコードされた bytes-like object または ASCII 文字列 s をデコードし、デコードされた
bytesを返します。オプション引数 casefold は小文字のアルファベットを受けつけるかどうかを指定します。セキュリティ上の理由により、デフォルトではこれは
Falseになっています。ignorechars should be a bytes-like object containing characters to ignore from the input.
s が正しくパディングされていない場合や、入力にアルファベットでない文字が含まれていた場合に、
binascii.Error例外を発生させます。バージョン 3.15 で変更: Added the ignorechars parameter.
Base85 エンコーディング¶
Base85 encoding is a family of algorithms which represent four bytes
using five ASCII characters. Originally implemented in the Unix
btoa(1) utility, a version of it was later adopted by Adobe in the
PostScript language and is standardized in PDF 2.0 (ISO 32000-2).
This version, in both its btoa and PDF variants, is implemented by
a85encode().
A separate version, using a different output character set, was
defined as an April Fool's joke in RFC 1924 but is now used by Git
and other software. This version is implemented by b85encode().
Finally, a third version, using yet another output character set
designed for safe inclusion in programming language strings, is
defined by ZeroMQ and implemented here by z85encode().
The functions present in this module differ in how they handle the following:
Whether to include and expect enclosing
<~and~>markers.Whether to fold the input into multiple lines.
The set of ASCII characters used for encoding.
Compact encodings of sequences of spaces and null bytes.
The encoding of zero-padding bytes applied to the input.
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 is an optional flag that uses the special short sequence 'y' instead of 4 consecutive spaces (ASCII 0x20) as supported by 'btoa'. This feature is not supported by the standard encoding used in PDF.
If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not insert any newlines.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 controls whether the encoded byte sequence is framed with
<~and~>, as in a PostScript base-85 string literal. Note that while ASCII85Decode streams in PDF documents must be terminated with~>, they must not use a leading<~.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 is a flag that specifies whether the 'y' short sequence should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20). This feature is not supported by the standard Ascii85 encoding used in PDF and PostScript.
adobe controls whether the
<~and~>markers are present. While the leading<~is not required, the input must end with~>, or aValueErroris raised.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.
If canonical is true, non-canonical encodings are rejected. See
binascii.a2b_ascii85()for details.Added in version 3.4.
バージョン 3.15 で変更: Added the canonical parameter. Single-character final groups are now always rejected as encoding violations.
- base64.b85encode(b, pad=False, *, wrapcol=0)¶
base85 (これは例えば git スタイルのバイナリ diff で用いられています) を使って bytes-like object の b をエンコードし、エンコードされた
bytesを返します。The input is padded with
b'\0'so its length is a multiple of 4 bytes before encoding. If pad is true, all the resulting characters are retained in the output, which will always be a multiple of 5 bytes, and thus the length of the data may not be preserved on decoding.If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.Added in version 3.4.
バージョン 3.15 で変更: Added the wrapcol parameter.
- base64.b85decode(b, *, ignorechars=b'', canonical=False)¶
Decode the base85-encoded bytes-like object or ASCII string b and return the decoded
bytes.ignorechars should be a bytes-like object containing characters to ignore from the input.
If canonical is true, non-canonical encodings are rejected. See
binascii.a2b_base85()for details.Added in version 3.4.
バージョン 3.15 で変更: Added the canonical and ignorechars parameters. Single-character final groups are now always rejected as encoding violations.
- base64.z85encode(s, pad=False, *, wrapcol=0)¶
Encode the bytes-like object s using Z85 (as used in ZeroMQ) and return the encoded
bytes.The input is padded with
b'\0'so its length is a multiple of 4 bytes before encoding. If pad is true, all the resulting characters are retained in the output, which will always be a multiple of 5 bytes, as required by the ZeroMQ standard.If wrapcol is non-zero, insert a newline (
b'\n') character after at most every wrapcol characters. If wrapcol is zero (default), do not add any newlines.Added in version 3.13.
バージョン 3.15 で変更: The pad parameter was added.
バージョン 3.15 で変更: Added the wrapcol parameter.
- base64.z85decode(s, *, ignorechars=b'', canonical=False)¶
Decode the Z85-encoded bytes-like object or ASCII string s and return the decoded
bytes.ignorechars should be a bytes-like object containing characters to ignore from the input.
If canonical is true, non-canonical encodings are rejected. See
binascii.a2b_base85()for details.Added in version 3.13.
バージョン 3.15 で変更: Added the canonical and ignorechars parameters. Single-character final groups are now always rejected as encoding violations.
レガシーインターフェース¶
- 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.
- ISO 32000-2 Portable document format - Part 2: PDF 2.0
Section 7.4.3, "ASCII85Decode Filter," provides the definition of the Ascii85 encoding used in PDF and PostScript, including the output character set and the details of data length preservation using zero-padding and partial output groups.
- ZeroMQ RFC 32/Z85
The "Formal Specification" section provides the character set used in Z85.