144 lines
5.4 KiB
TeX
144 lines
5.4 KiB
TeX
\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_qp}{string\optional{, header}}
|
|
Convert a block of quoted-printable data back to binary and return the
|
|
binary data. More than one line may be passed at a time.
|
|
If the optional argument \var{header} is present and true, underscores
|
|
will be decoded as spaces.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{b2a_qp}{data\optional{, quotetabs, istext, header}}
|
|
Convert binary data to a line(s) of \ASCII{} characters in
|
|
quoted-printable encoding. The return value is the converted line(s).
|
|
If the optional argument \var{quotetabs} is present and true, all tabs
|
|
and spaces will be encoded. If the optional argument \var{header} is
|
|
present and true, spaces will be encoded as underscores per RFC1522.
|
|
If the optional argument \var{header} is present and false, newline
|
|
characters will be encoded as well, otherwise linefeed conversion might
|
|
corrupt the binary data stream.
|
|
\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. Since the
|
|
algorithm is designed for use as a checksum algorithm, it is not
|
|
suitable for use as a general hash algorithm. 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{funcdesc}{b2a_hex}{data}
|
|
\funcline{hexlify}{data}
|
|
Return the hexadecimal representation of the binary \var{data}. Every
|
|
byte of \var{data} is converted into the corresponding 2-digit hex
|
|
representation. The resulting string is therefore twice as long as
|
|
the length of \var{data}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{a2b_hex}{hexstr}
|
|
\funcline{unhexlify}{hexstr}
|
|
Return the binary data represented by the hexadecimal string
|
|
\var{hexstr}. This function is the inverse of \function{b2a_hex()}.
|
|
\var{hexstr} must contain an even number of hexadecimal digits (which
|
|
can be upper or lower case), otherwise a \exception{TypeError} is
|
|
raised.
|
|
\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.}
|
|
|
|
\seemodule{quopri}{Support for quoted-printable encoding used in MIME email messages. }
|
|
\end{seealso}
|