Doc/lib/libbinascii.tex

   1 \section{\module{binascii} ---
   2          Convert between binary and \ASCII{}}
   3
   4 \declaremodule{builtin}{binascii}
   5 \modulesynopsis{Tools for converting between binary and various
   6                 \ASCII-encoded binary representations.}
   7
   8
   9 The \module{binascii} module contains a number of methods to convert
  10 between binary and various \ASCII{}-encoded binary
  11 representations. Normally, you will not use these functions directly
  12 but use wrapper modules like \refmodule{uu}\refstmodindex{uu} or
  13 \refmodule{binhex}\refstmodindex{binhex} instead, this module solely
  14 exists because bit-manipulation of large amounts of data is slow in
  15 Python.
  16
  17 The \module{binascii} module defines the following functions:
  18
  19 \begin{funcdesc}{a2b_uu}{string}
  20 Convert a single line of uuencoded data back to binary and return the
  21 binary data. Lines normally contain 45 (binary) bytes, except for the
  22 last line. Line data may be followed by whitespace.
  23 \end{funcdesc}
  24
  25 \begin{funcdesc}{b2a_uu}{data}
  26 Convert binary data to a line of \ASCII{} characters, the return value
  27 is the converted line, including a newline char. The length of
  28 \var{data} should be at most 45.
  29 \end{funcdesc}
  30
  31 \begin{funcdesc}{a2b_base64}{string}
  32 Convert a block of base64 data back to binary and return the
  33 binary data. More than one line may be passed at a time.
  34 \end{funcdesc}
  35
  36 \begin{funcdesc}{b2a_base64}{data}
  37 Convert binary data to a line of \ASCII{} characters in base64 coding.
  38 The return value is the converted line, including a newline char.
  39 The length of \var{data} should be at most 57 to adhere to the base64
  40 standard.
  41 \end{funcdesc}
  42
  43 \begin{funcdesc}{a2b_hqx}{string}
  44 Convert binhex4 formatted \ASCII{} data to binary, without doing
  45 RLE-decompression. The string should contain a complete number of
  46 binary bytes, or (in case of the last portion of the binhex4 data)
  47 have the remaining bits zero.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{rledecode_hqx}{data}
  51 Perform RLE-decompression on the data, as per the binhex4
  52 standard. The algorithm uses \code{0x90} after a byte as a repeat
  53 indicator, followed by a count. A count of \code{0} specifies a byte
  54 value of \code{0x90}. The routine returns the decompressed data,
  55 unless data input data ends in an orphaned repeat indicator, in which
  56 case the \exception{Incomplete} exception is raised.
  57 \end{funcdesc}
  58
  59 \begin{funcdesc}{rlecode_hqx}{data}
  60 Perform binhex4 style RLE-compression on \var{data} and return the
  61 result.
  62 \end{funcdesc}
  63
  64 \begin{funcdesc}{b2a_hqx}{data}
  65 Perform hexbin4 binary-to-\ASCII{} translation and return the
  66 resulting string. The argument should already be RLE-coded, and have a
  67 length divisible by 3 (except possibly the last fragment).
  68 \end{funcdesc}
  69
  70 \begin{funcdesc}{crc_hqx}{data, crc}
  71 Compute the binhex4 crc value of \var{data}, starting with an initial
  72 \var{crc} and returning the result.
  73 \end{funcdesc}
  74
  75 \begin{funcdesc}{crc32}{data\optional{, crc}}
  76 Compute CRC-32, the 32-bit checksum of data, starting with an initial
  77 crc.  This is consistent with the ZIP file checksum.  Use as follows:
  78 \begin{verbatim}
  79     print binascii.crc32("hello world")
  80     # Or, in two pieces:
  81     crc = binascii.crc32("hello")
  82     crc = binascii.crc32(" world", crc)
  83     print crc
  84 \end{verbatim}
  85 \end{funcdesc}
  86
  87 \begin{funcdesc}{b2a_hex}{data}
  88 \funcline{hexlify}{data}
  89 Return the hexadecimal representation of the binary \var{data}.  Every
  90 byte of \var{data} is converted into the corresponding 2-digit hex
  91 representation.  The resulting string is therefore twice as long as
  92 the length of \var{data}.
  93 \end{funcdesc}
  94
  95 \begin{funcdesc}{a2b_hex}{hexstr}
  96 \funcline{unhexlify}{hexstr}
  97 Return the binary data represented by the hexadecimal string
  98 \var{hexstr}.  This function is the inverse of \function{b2a_hex()}.
  99 \var{hexstr} must contain an even number of hexadecimal digits (which
 100 can be upper or lower case), otherwise a \exception{TypeError} is
 101 raised.
 102 \end{funcdesc}
 103
 104 \begin{excdesc}{Error}
 105 Exception raised on errors. These are usually programming errors.
 106 \end{excdesc}
 107
 108 \begin{excdesc}{Incomplete}
 109 Exception raised on incomplete data. These are usually not programming
 110 errors, but may be handled by reading a little more data and trying
 111 again.
 112 \end{excdesc}
 113
 114
 115 \begin{seealso}
 116   \seemodule{base64}{Support for base64 encoding used in MIME email messages.}
 117
 118   \seemodule{binhex}{Support for the binhex format used on the Macintosh.}
 119
 120   \seemodule{uu}{Support for UU encoding used on \UNIX.}
 121 \end{seealso}