binascii — Convert between binary and ASCII¶

Thebinascii module contains a number of methods to convert betweenbinary and various ASCII-encoded binary representations. Normally, you will notuse these functions directly but use wrapper modules likebase64 instead. Thebinascii module containslow-level functions written in C for greater speed that are used by thehigher-level modules.

Thebinascii module defines the following functions:

binascii.a2b_uu(string)¶

Convert a single line of uuencoded data back to binary and return the binarydata. Lines normally contain 45 (binary) bytes, except for the last line. Linedata may be followed by whitespace.

binascii.b2a_uu(data,*,backtick=False)¶

Convert binary data to a line of ASCII characters, the return value is theconverted line, including a newline char. The length ofdata should be at most45. Ifbacktick is true, zeros are represented by'`' instead of spaces.

Changed in version 3.7:Added thebacktick parameter.

binascii.a2b_base64(string,/,*,strict_mode=False)¶

binascii.a2b_base64(string,/,*,strict_mode=True,ignorechars)

Convert a block of base64 data back to binary and return the binary data. Morethan one line may be passed at a time.

Ifignorechars is specified, it should be abytes-like objectcontaining characters to ignore from the input whenstrict_mode is true.Ifignorechars contains the pad character'=', the pad characterspresented before the end of the encoded data and the excess pad characterswill be ignored.The default value ofstrict_mode isTrue ifignorechars is specified,False otherwise.

Ifstrict_mode is true, only valid base64 data will be converted. Invalid base64data will raisebinascii.Error.

Valid base64:

• Conforms toRFC 4648.

• Contains only characters from the base64 alphabet.

• Contains no excess data after padding (including excess padding, newlines, etc.).

• Does not start with a padding.

Changed in version 3.11:Added thestrict_mode parameter.

Changed in version 3.15.0a5 (unreleased):Added theignorechars parameter.

binascii.b2a_base64(data,*,wrapcol=0,newline=True)¶

Convert binary data to a line(s) of ASCII characters in base64 coding,as specified inRFC 4648.

Ifwrapcol is non-zero, insert a newline (b'\n') characterafter at most everywrapcol characters.Ifwrapcol is zero (default), do not insert any newlines.

Ifnewline is true (default), a newline character will be addedat the end of the output.

Changed in version 3.6:Added thenewline parameter.

Changed in version 3.15:Added thewrapcol parameter.

binascii.a2b_ascii85(string,/,*,foldspaces=False,adobe=False,ignorechars=b'')¶

Convert Ascii85 data back to binary and return the binary data.

Valid Ascii85 data contains characters from the Ascii85 alphabet in groupsof five (except for the final group, which may have from two to fivecharacters). Each group encodes 32 bits of binary data in the range from0 to2**32-1, inclusive. The special characterz isaccepted as a short form of the group!!!!!, which encodes fourconsecutive null bytes.

foldspaces is a flag that specifies whether the ‘y’ short sequenceshould be accepted as shorthand for 4 consecutive spaces (ASCII 0x20).This feature is not supported by the “standard” Ascii85 encoding.

adobe controls whether the input sequence is in Adobe Ascii85 format(i.e. is framed with <~ and ~>).

ignorechars should be abytes-like object containing charactersto ignore from the input.This should only contain whitespace characters.

Invalid Ascii85 data will raisebinascii.Error.

Added in version 3.15.0a5 (unreleased).

binascii.b2a_ascii85(data,/,*,foldspaces=False,wrapcol=0,pad=False,adobe=False)¶

Convert binary data to a formatted sequence of ASCII characters in Ascii85coding. The return value is the converted data.

foldspaces is an optional flag that uses the special short sequence ‘y’instead of 4 consecutive spaces (ASCII 0x20) as supported by ‘btoa’. Thisfeature is not supported by the “standard” Ascii85 encoding.

Ifwrapcol is non-zero, insert a newline (b'\n') characterafter at most everywrapcol characters.Ifwrapcol is zero (default), do not insert any newlines.

Ifpad is true, the input is padded withb'\0' so its length is amultiple of 4 bytes before encoding.Note that thebtoa implementation always pads.

adobe controls whether the encoded byte sequence is framed with<~and~>, which is used by the Adobe implementation.

Added in version 3.15.0a5 (unreleased).

binascii.a2b_base85(string,/)¶

Convert Base85 data back to binary and return the binary data.More than one line may be passed at a time.

Valid Base85 data contains characters from the Base85 alphabet in groupsof five (except for the final group, which may have from two to fivecharacters). Each group encodes 32 bits of binary data in the range from0 to2**32-1, inclusive.

Invalid Base85 data will raisebinascii.Error.

Added in version 3.15.0a5 (unreleased).

binascii.b2a_base85(data,/,*,pad=False)¶

Convert binary data to a line of ASCII characters in Base85 coding.The return value is the converted line.

Ifpad is true, the input is padded withb'\0' so its length is amultiple of 4 bytes before encoding.

Added in version 3.15.0a5 (unreleased).

binascii.a2b_z85(string,/)¶

Convert Z85 data back to binary and return the binary data.More than one line may be passed at a time.

Valid Z85 data contains characters from the Z85 alphabet in groupsof five (except for the final group, which may have from two to fivecharacters). Each group encodes 32 bits of binary data in the range from0 to2**32-1, inclusive.

SeeZ85 specification for more information.

Invalid Z85 data will raisebinascii.Error.

Added in version 3.15.0a5 (unreleased).

binascii.b2a_z85(data,/,*,pad=False)¶

Convert binary data to a line of ASCII characters in Z85 coding.The return value is the converted line.

Ifpad is true, the input is padded withb'\0' so its length is amultiple of 4 bytes before encoding.

SeeZ85 specification for more information.

Added in version 3.15.0a5 (unreleased).

binascii.a2b_qp(data,header=False)¶

Convert a block of quoted-printable data back to binary and return the binarydata. More than one line may be passed at a time. If the optional argumentheader is present and true, underscores will be decoded as spaces.

binascii.b2a_qp(data,quotetabs=False,istext=True,header=False)¶

Convert binary data to a line(s) of ASCII characters in quoted-printableencoding. The return value is the converted line(s). If the optional argumentquotetabs is present and true, all tabs and spaces will be encoded. If theoptional argumentistext is present and true, newlines are not encoded buttrailing whitespace will be encoded. If the optional argumentheader ispresent and true, spaces will be encoded as underscores perRFC 1522. If theoptional argumentheader is present and false, newline characters will beencoded as well; otherwise linefeed conversion might corrupt the binary datastream.

binascii.crc_hqx(data,value)¶

Compute a 16-bit CRC value ofdata, starting withvalue as theinitial CRC, and return the result. This uses the CRC-CCITT polynomialx¹⁶ +x¹² +x⁵ + 1, often represented as0x1021. This CRC is used in the binhex4 format.

binascii.crc32(data[,value])¶

Compute CRC-32, the unsigned 32-bit checksum ofdata, starting with aninitial CRC ofvalue. The default initial CRC is zero. The algorithmis consistent with the ZIP file checksum. Since the algorithm is designed foruse as a checksum algorithm, it is not suitable for use as a general hashalgorithm. Use as follows:

print(binascii.crc32(b"hello world"))# Or, in two pieces:crc=binascii.crc32(b"hello")crc=binascii.crc32(b" world",crc)print('crc32 ={:#010x}'.format(crc))

Changed in version 3.0:The result is always unsigned.

binascii.b2a_hex(data[,sep[,bytes_per_sep=1]])¶

binascii.hexlify(data[,sep[,bytes_per_sep=1]])¶

Return the hexadecimal representation of the binarydata. Every byte ofdata is converted into the corresponding 2-digit hex representation. Thereturned bytes object is therefore twice as long as the length ofdata.

Similar functionality (but returning a text string) is also convenientlyaccessible using thebytes.hex() method.

Ifsep is specified, it must be a single character str or bytes object.It will be inserted in the output after everybytes_per_sep input bytes.Separator placement is counted from the right end of the output by default,if you wish to count from the left, supply a negativebytes_per_sep value.

>>>importbinascii>>>binascii.b2a_hex(b'\xb9\x01\xef')b'b901ef'>>>binascii.hexlify(b'\xb9\x01\xef','-')b'b9-01-ef'>>>binascii.b2a_hex(b'\xb9\x01\xef',b'_',2)b'b9_01ef'>>>binascii.b2a_hex(b'\xb9\x01\xef',b' ',-2)b'b901 ef'

Changed in version 3.8:Thesep andbytes_per_sep parameters were added.

binascii.a2b_hex(hexstr)¶

binascii.unhexlify(hexstr)¶

Return the binary data represented by the hexadecimal stringhexstr. Thisfunction is the inverse ofb2a_hex().hexstr must contain an even numberof hexadecimal digits (which can be upper or lower case), otherwise anError exception is raised.

Similar functionality (accepting only text string arguments, but moreliberal towards whitespace) is also accessible using thebytes.fromhex() class method.

exceptionbinascii.Error¶

Exception raised on errors. These are usually programming errors.

exceptionbinascii.Incomplete¶

Exception raised on incomplete data. These are usually not programming errors,but may be handled by reading a little more data and trying again.