21.1 Encoding Binary Data as Text

Several kinds of media (e.g., email messages) contain only text. When you want to transmit binary data via such media, you need to encode the data as text strings. The Python standard library supplies modules that support the standard encodings known as Base 64, Quoted Printable, and UU.

21.1.1 The base64 Module

The base64 module supports the encoding specified in RFC 1521 as Base 64. The Base 64 encoding is a compact way to represent arbitrary binary data as text, without any attempt to produce human-readable results. Module base64 supplies four functions.

decode(infile,outfile)

Reads text-file-like object infile, by calling infile.readline until end of file (i.e, until a call to infile.readline returns an empty string), decodes the Base 64-encoded text thus read, and writes the decoded data to binary-file-like object outfile.

decodestring(s)

Decodes text string s, which contains one or more complete lines of Base 64-encoded text, and returns the byte string with the corresponding decoded data.

encode(infile,outfile)

Reads binary-file-like object infile, by calling infile.read (for a few bytes at a time—the amount of data that Base 64 encodes into a single output line) until end of file (i.e, until a call to infile.read returns an empty string). Then it encodes the data thus read in Base 64, and writes the encoded text as lines to text-file-like object outfile. encode appends \n to each line of text it emits, including the last one.

encodestring(s)

Encodes binary string s, which contains arbitrary bytes, and returns a text string with one or more complete lines of Base 64-encoded data. encodestring always returns a text string ending with \n.

21.1.2 The quopri Module

The quopri module supports the encoding specified in RFC 1521 as Quoted Printable (QP). QP can represent any binary data as text, but it's mainly intended for data that is textual, with a relatively modest amount of characters with the high bit set (i.e., characters outside of the ASCII range). For such data, QP produces results that are both compact and rather human-readable. Module quopri supplies four functions.

decode(infile,outfile,header=False)

Reads file-like object infile, by calling infile.readline until end of file (i.e, until a call to infile.readline returns an empty string), decodes the QP-encoded ASCII text thus read, and writes the decoded data to file-like object outfile. When header is true, decode also decodes _ (underscores) into spaces.

decodestring(s,header=False)

Decodes string s, which contains QP-encoded ASCII text, and returns the byte string with the decoded data. When header is true, decodestring also decodes _ (underscores) into spaces.

encode(infile,outfile,spaces,header=False)

Reads file-like object infile, by calling infile.readline until end of file (i.e, until a call to infile.readline returns an empty string), encodes the data thus read in QP, and writes the encoded ASCII text to file-like object outfile. When spaces is true, encode also encodes spaces and tabs. When header is true, encode encodes spaces as _ (underscores).

encodestring(s,spaces=False,header=False)

Encodes string s, which contains arbitrary bytes, and returns a string with QP-encoded ASCII text. When spaces is true, encodestring also encodes spaces and tabs. When header is true, encodestring encodes spaces as _ (underscores).

21.1.3 The uu Module

The uu module supports the traditional Unix-to-Unix (UU) encoding, as implemented by Unix programs uuencode and uudecode. UU begins encoded data with a begin line, which also gives the filename and permissions of the file being encoded, and ends it with an end line. Therefore, UU encoding lets you embed encoded data in otherwise unstructured text, while Base 64 encoding relies on the existence of other indications of where the encoded data starts and finishes. Module uu supplies two functions.

decode(infile,outfile=None,mode=None)

Reads file-like object infile, by calling infile.readline until end of file (i.e, until a call to infile.readline returns an empty string) or until a terminator line (the string 'end' surrounded by any amount of whitespace). decode decodes the UU-encoded text thus read, and writes the decoded data to file-like object outfile. When outfile is None, decode creates the file specified in the UU-format begin line, with the permission bits given by mode (the permission bits specified in the begin line, when mode is None). In this case, decode raises an exception if the file already exists.

encode(infile,outfile,name='-',mode=0666)

Reads file-like object infile, by calling infile.read (for a few bytes at a time—the amount of data that UU encodes into a single output line) until end of file (i.e, until a call to infile.read returns an empty string). Then it encodes the data thus read in UU, and writes the encoded text to file-like object outfile. encode also writes a UU begin line before the encoded text, and a UU end line after the encoded text. In the begin line, encode specifies the filename as name and the mode as mode.