Fred Drake | 6f07010 | 1997-12-17 13:45:50 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{binhex}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-binhex} |
Jack Jansen | 4549b13 | 1995-08-29 11:30:24 +0000 | [diff] [blame] | 3 | \stmodindex{binhex} |
| 4 | |
| 5 | This module encodes and decodes files in binhex4 format, a format |
| 6 | allowing representation of Macintosh files in ASCII. On the macintosh, |
| 7 | both forks of a file and the finder information are encoded (or |
| 8 | decoded), on other platforms only the data fork is handled. |
| 9 | |
| 10 | The \code{binhex} module defines the following functions: |
| 11 | |
| 12 | \renewcommand{\indexsubitem}{(in module binhex)} |
| 13 | |
| 14 | \begin{funcdesc}{binhex}{input\, output} |
| 15 | Convert a binary file with filename \var{input} to binhex file |
| 16 | \var{output}. The \var{output} parameter can either be a filename or a |
| 17 | file-like object (any object supporting a \var{write} and \var{close} |
| 18 | method). |
| 19 | \end{funcdesc} |
| 20 | |
| 21 | \begin{funcdesc}{hexbin}{input\optional{\, output}} |
Guido van Rossum | e9a0732 | 1997-04-27 21:29:51 +0000 | [diff] [blame] | 22 | Decode a binhex file \var{input}. \var{input} may be a filename or a |
Jack Jansen | 4549b13 | 1995-08-29 11:30:24 +0000 | [diff] [blame] | 23 | file-like object supporting \var{read} and \var{close} methods. |
| 24 | The resulting file is written to a file named \var{output}, unless the |
| 25 | argument is empty in which case the output filename is read from the |
| 26 | binhex file. |
| 27 | \end{funcdesc} |
| 28 | |
| 29 | \subsection{notes} |
| 30 | There is an alternative, more powerful interface to the coder and |
| 31 | decoder, see the source for details. |
| 32 | |
| 33 | If you code or decode textfiles on non-Macintosh platforms they will |
| 34 | still use the macintosh newline convention (carriage-return as end of |
| 35 | line). |
| 36 | |
Jack Jansen | 7e183e9 | 1995-08-30 12:23:43 +0000 | [diff] [blame] | 37 | As of this writing, \var{hexbin} appears to not work in all cases. |
Jack Jansen | 4549b13 | 1995-08-29 11:30:24 +0000 | [diff] [blame] | 38 | |
Fred Drake | 6f07010 | 1997-12-17 13:45:50 +0000 | [diff] [blame] | 39 | \section{Standard Module \sectcode{uu}} |
Jack Jansen | 4549b13 | 1995-08-29 11:30:24 +0000 | [diff] [blame] | 40 | \stmodindex{uu} |
| 41 | |
| 42 | This module encodes and decodes files in uuencode format, allowing |
| 43 | arbitrary binary data to be transferred over ascii-only connections. |
Guido van Rossum | e9a0732 | 1997-04-27 21:29:51 +0000 | [diff] [blame] | 44 | Wherever a file argument is expected, the methods accept a file-like |
| 45 | object. For backwards compatibility, a string containing a pathname |
| 46 | is also accepted, and the corresponding file will be opened for |
| 47 | reading and writing; the pathname \code{'-'} is understood to mean the |
| 48 | standard input or output. However, this interface is deprecated; it's |
| 49 | better for the caller to open the file itself, and be sure that, when |
| 50 | required, the mode is \code{'rb'} or \code{'wb'} on Windows or DOS. |
Jack Jansen | 7e183e9 | 1995-08-30 12:23:43 +0000 | [diff] [blame] | 51 | |
| 52 | This code was contributed by Lance Ellinghouse, and modified by Jack |
| 53 | Jansen. |
Jack Jansen | 4549b13 | 1995-08-29 11:30:24 +0000 | [diff] [blame] | 54 | |
| 55 | The \code{uu} module defines the following functions: |
| 56 | |
| 57 | \renewcommand{\indexsubitem}{(in module uu)} |
| 58 | |
Jack Jansen | 7e183e9 | 1995-08-30 12:23:43 +0000 | [diff] [blame] | 59 | \begin{funcdesc}{encode}{in_file\, out_file\optional{\, name\, mode}} |
| 60 | Uuencode file \var{in_file} into file \var{out_file}. The uuencoded |
| 61 | file will have the header specifying \var{name} and \var{mode} as the |
| 62 | defaults for the results of decoding the file. The default defaults |
| 63 | are taken from \var{in_file}, or \code{'-'} and \code{0666} |
| 64 | respectively. |
Jack Jansen | 4549b13 | 1995-08-29 11:30:24 +0000 | [diff] [blame] | 65 | \end{funcdesc} |
| 66 | |
Jack Jansen | 7e183e9 | 1995-08-30 12:23:43 +0000 | [diff] [blame] | 67 | \begin{funcdesc}{decode}{in_file\optional{\, out_file\, mode}} |
| 68 | This call decodes uuencoded file \var{in_file} placing the result on |
| 69 | file \var{out_file}. If \var{out_file} is a pathname the \var{mode} is |
| 70 | also set. Defaults for \var{out_file} and \var{mode} are taken from |
| 71 | the uuencode header. |
Jack Jansen | 4549b13 | 1995-08-29 11:30:24 +0000 | [diff] [blame] | 72 | \end{funcdesc} |
| 73 | |
Jack Jansen | 4549b13 | 1995-08-29 11:30:24 +0000 | [diff] [blame] | 74 | \section{Built-in Module \sectcode{binascii}} % If implemented in C |
| 75 | \bimodindex{binascii} |
| 76 | |
| 77 | The binascii module contains a number of methods to convert between |
| 78 | binary and various ascii-encoded binary representations. Normally, you |
| 79 | will not use these modules directly but use wrapper modules like |
| 80 | \var{uu} or \var{hexbin} in stead, this module solely exists because |
| 81 | bit-manipuation of large amounts of data is slow in python. |
| 82 | |
| 83 | The \code{binascii} module defines the following functions: |
| 84 | |
| 85 | \renewcommand{\indexsubitem}{(in module binascii)} |
| 86 | |
| 87 | \begin{funcdesc}{a2b_uu}{string} |
| 88 | Convert a single line of uuencoded data back to binary and return the |
| 89 | binary data. Lines normally contain 45 (binary) bytes, except for the |
| 90 | last line. Line data may be followed by whitespace. |
| 91 | \end{funcdesc} |
| 92 | |
| 93 | \begin{funcdesc}{b2a_uu}{data} |
| 94 | Convert binary data to a line of ascii characters, the return value is |
| 95 | the converted line, including a newline char. The length of \var{data} |
| 96 | should be at most 45. |
| 97 | \end{funcdesc} |
| 98 | |
Jack Jansen | 06cf5d0 | 1995-10-10 14:41:03 +0000 | [diff] [blame] | 99 | \begin{funcdesc}{a2b_base64}{string} |
| 100 | Convert a block of base64 data back to binary and return the |
| 101 | binary data. More than one line may be passed at a time. |
| 102 | \end{funcdesc} |
| 103 | |
| 104 | \begin{funcdesc}{b2a_base64}{data} |
| 105 | Convert binary data to a line of ascii characters in base64 coding. |
| 106 | The return value is the converted line, including a newline char. |
| 107 | The length of \var{data} should be at most 57 to adhere to the base64 |
| 108 | standard. |
| 109 | \end{funcdesc} |
| 110 | |
Jack Jansen | 4549b13 | 1995-08-29 11:30:24 +0000 | [diff] [blame] | 111 | \begin{funcdesc}{a2b_hqx}{string} |
| 112 | Convert binhex4 formatted ascii data to binary, without doing |
| 113 | rle-decompression. The string should contain a complete number of |
| 114 | binary bytes, or (in case of the last portion of the binhex4 data) |
| 115 | have the remaining bits zero. |
| 116 | \end{funcdesc} |
| 117 | |
| 118 | \begin{funcdesc}{rledecode_hqx}{data} |
| 119 | Perform RLE-decompression on the data, as per the binhex4 |
| 120 | standard. The algorithm uses \code{0x90} after a byte as a repeat |
| 121 | indicator, followed by a count. A count of \code{0} specifies a byte |
| 122 | value of \code{0x90}. The routine returns the decompressed data, |
| 123 | unless data input data ends in an orphaned repeat indicator, in which |
| 124 | case the \var{Incomplete} exception is raised. |
| 125 | \end{funcdesc} |
| 126 | |
| 127 | \begin{funcdesc}{rlecode_hqx}{data} |
| 128 | Perform binhex4 style RLE-compression on \var{data} and return the |
| 129 | result. |
| 130 | \end{funcdesc} |
| 131 | |
| 132 | \begin{funcdesc}{b2a_hqx}{data} |
| 133 | Perform hexbin4 binary-to-ascii translation and return the resulting |
| 134 | string. The argument should already be rle-coded, and have a length |
| 135 | divisible by 3 (except possibly the last fragment). |
| 136 | \end{funcdesc} |
| 137 | |
| 138 | \begin{funcdesc}{crc_hqx}{data, crc} |
| 139 | Compute the binhex4 crc value of \var{data}, starting with an initial |
| 140 | \var{crc} and returning the result. |
| 141 | \end{funcdesc} |
| 142 | |
| 143 | \begin{excdesc}{Error} |
| 144 | Exception raised on errors. These are usually programming errors. |
| 145 | \end{excdesc} |
| 146 | |
| 147 | \begin{excdesc}{Incomplete} |
| 148 | Exception raised on incomplete data. These are usually not programming |
| 149 | errors, but handled by reading a little more data and trying again. |
| 150 | \end{excdesc} |