| \section{\module{binascii} --- |
| Convert between binary and \ASCII{}} |
| |
| \declaremodule{builtin}{binascii} |
| \modulesynopsis{Tools for converting between binary and various |
| \ASCII{}-encoded binary representations.} |
| |
| |
| The \module{binascii} module contains a number of methods to convert |
| between binary and various \ASCII{}-encoded binary |
| representations. Normally, you will not use these functions directly |
| but use wrapper modules like \refmodule{uu}\refstmodindex{uu} or |
| \refmodule{binhex}\refstmodindex{binhex} instead, this module solely |
| exists because bit-manipulation of large amounts of data is slow in |
| Python. |
| |
| The \module{binascii} module defines the following functions: |
| |
| \begin{funcdesc}{a2b_uu}{string} |
| Convert a single line of uuencoded data back to binary and return the |
| binary data. Lines normally contain 45 (binary) bytes, except for the |
| last line. Line data may be followed by whitespace. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{b2a_uu}{data} |
| Convert binary data to a line of \ASCII{} characters, the return value |
| is the converted line, including a newline char. The length of |
| \var{data} should be at most 45. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{a2b_base64}{string} |
| Convert a block of base64 data back to binary and return the |
| binary data. More than one line may be passed at a time. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{b2a_base64}{data} |
| Convert binary data to a line of \ASCII{} characters in base64 coding. |
| The return value is the converted line, including a newline char. |
| The length of \var{data} should be at most 57 to adhere to the base64 |
| standard. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{a2b_hqx}{string} |
| Convert binhex4 formatted \ASCII{} data to binary, without doing |
| RLE-decompression. The string should contain a complete number of |
| binary bytes, or (in case of the last portion of the binhex4 data) |
| have the remaining bits zero. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{rledecode_hqx}{data} |
| Perform RLE-decompression on the data, as per the binhex4 |
| standard. The algorithm uses \code{0x90} after a byte as a repeat |
| indicator, followed by a count. A count of \code{0} specifies a byte |
| value of \code{0x90}. The routine returns the decompressed data, |
| unless data input data ends in an orphaned repeat indicator, in which |
| case the \exception{Incomplete} exception is raised. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{rlecode_hqx}{data} |
| Perform binhex4 style RLE-compression on \var{data} and return the |
| result. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{b2a_hqx}{data} |
| Perform hexbin4 binary-to-\ASCII{} translation and return the |
| resulting string. The argument should already be RLE-coded, and have a |
| length divisible by 3 (except possibly the last fragment). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{crc_hqx}{data, crc} |
| Compute the binhex4 crc value of \var{data}, starting with an initial |
| \var{crc} and returning the result. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{crc32}{data\optional{, crc}} |
| Compute CRC-32, the 32-bit checksum of data, starting with an initial |
| crc. This is consistent with the ZIP file checksum. Use as follows: |
| \begin{verbatim} |
| print binascii.crc32("hello world") |
| # Or, in two pieces: |
| crc = binascii.crc32("hello") |
| crc = binascii.crc32(" world", crc) |
| print crc |
| \end{verbatim} |
| \end{funcdesc} |
| |
| \begin{excdesc}{Error} |
| Exception raised on errors. These are usually programming errors. |
| \end{excdesc} |
| |
| \begin{excdesc}{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. |
| \end{excdesc} |
| |
| |
| \begin{seealso} |
| \seemodule{base64}{support for base64 encoding used in MIME email messages} |
| |
| \seemodule{binhex}{support for the binhex format used on the Macintosh} |
| |
| \seemodule{uu}{support for UU encoding used on \UNIX{}} |
| \end{seealso} |