Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 4549b13

Browse files
jackjansenjackjansen
committed
Documented binascii, binhex and uu modules. Put them in the
Internet/WWW section, for lack of a better place.
1 parent 6ec3c65 commit 4549b13

5 files changed

Lines changed: 296 additions & 2 deletions

File tree

‎Doc/Makefile‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \
100100
LIBFILES = lib.tex \
101101
libal.tex libaifc.tex liballos.tex \
102102
libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \
103-
libbltin.tex \
103+
libbltin.tex libbinascii.tex \
104104
libcd.tex \
105105
libcgi.tex libcopy.tex libctb.tex libcrypto.tex \
106106
libdbm.tex \
@@ -111,7 +111,7 @@ libhtmllib.tex libhttplib.tex \
111111
libimageop.tex libimgfile.tex libintro.tex \
112112
libjpeg.tex \
113113
libmac.tex libmacconsole.tex libmacdnr.tex \
114-
libmacfs.tex libmactcp.tex libmacspeech.tex \
114+
libmacfs.tex libmacos.tex libmactcp.tex libmacspeech.tex \
115115
libmain.tex libmarshal.tex libmath.tex \
116116
libmd5.tex libmimetools.tex libmisc.tex \
117117
libmm.tex libmpz.tex \

‎Doc/lib.tex‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@
137137
\input{libsgmllib}
138138
\input{librfc822}
139139
\input{libmimetools}
140+
\input{libbinascii}
140141

141142
\input{libmm} % Multimedia Services
142143
\input{libaudioop}

‎Doc/lib/lib.tex‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@
137137
\input{libsgmllib}
138138
\input{librfc822}
139139
\input{libmimetools}
140+
\input{libbinascii}
140141

141142
\input{libmm} % Multimedia Services
142143
\input{libaudioop}

‎Doc/lib/libbinascii.tex‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
\section{Standard module \sectcode{binhex}}
2+
\stmodindex{binhex}
3+
4+
This module encodes and decodes files in binhex4 format, a format
5+
allowing representation of Macintosh files in ASCII. On the macintosh,
6+
both forks of a file and the finder information are encoded (or
7+
decoded), on other platforms only the data fork is handled.
8+
9+
The \code{binhex} module defines the following functions:
10+
11+
\renewcommand{\indexsubitem}{(in module binhex)}
12+
13+
\begin{funcdesc}{binhex}{input\, output}
14+
Convert a binary file with filename \var{input} to binhex file
15+
\var{output}. The \var{output} parameter can either be a filename or a
16+
file-like object (any object supporting a \var{write} and \var{close}
17+
method).
18+
\end{funcdesc}
19+
20+
\begin{funcdesc}{hexbin}{input\optional{\, output}}
21+
Decode a binhex file \var{input}. \var{Input} may be a filename or a
22+
file-like object supporting \var{read} and \var{close} methods.
23+
The resulting file is written to a file named \var{output}, unless the
24+
argument is empty in which case the output filename is read from the
25+
binhex file.
26+
\end{funcdesc}
27+
28+
\subsection{notes}
29+
There is an alternative, more powerful interface to the coder and
30+
decoder, see the source for details.
31+
32+
If you code or decode textfiles on non-Macintosh platforms they will
33+
still use the macintosh newline convention (carriage-return as end of
34+
line).
35+
36+
As of this writing, hexbin appears to not work in all cases.
37+
38+
\section{Standard module \sectcode{uu}}
39+
\stmodindex{uu}
40+
41+
This module encodes and decodes files in uuencode format, allowing
42+
arbitrary binary data to be transferred over ascii-only connections.
43+
44+
The \code{uu} module defines the following functions:
45+
46+
\renewcommand{\indexsubitem}{(in module uu)}
47+
48+
\begin{funcdesc}{encode}{filename\, mode\, in_file\, out_file}
49+
Uuencode file \var{in_file} into file \var{out_file}. Both are
50+
file-like objects supporting a \var{read} and \var{write} method
51+
respectively. The uuencoded file will have the header specifying
52+
\var{filename} and \var{mode} as the defaults for the results of
53+
decoding the file.
54+
\end{funcdesc}
55+
56+
\begin{funcdesc}{decode}{filename\, mode\, in_file}
57+
Note that this function uses a non-standard form of variable
58+
arguments, see below for other variants of argument lists.
59+
60+
This call decodes uuencoded file \var{in_file} (an object supporting a
61+
\var{readline} method), placing the result on a file with name
62+
\var{filename} and mode \var{mode}.
63+
\end{funcdesc}
64+
65+
\begin{funcdesc}{decode}{in_file\, out_file}
66+
An alternative form of \var{decode} which writes the resulting data to
67+
\var{out_file} (an object supporting a \var{write} method).
68+
\end{funcdesc}
69+
70+
\begin{funcdesc}{decode}{in_file}
71+
An alternative form of \var{decode} which stores the result in the
72+
file specified in the uuencoded file.
73+
\end{funcdesc}
74+
75+
\subsection{notes}
76+
This code was contributed by Lance Ellinghouse, and modified by Jack
77+
Jansen to use the \var{binascii} module.
78+
79+
Encoding a file on a non-unix platforms may well result in a file
80+
with the incorrect newline semantics or a file extractable only on the
81+
original platform.
82+
\section{Built-in Module \sectcode{binascii}} % If implemented in C
83+
\bimodindex{binascii}
84+
85+
The binascii module contains a number of methods to convert between
86+
binary and various ascii-encoded binary representations. Normally, you
87+
will not use these modules directly but use wrapper modules like
88+
\var{uu} or \var{hexbin} in stead, this module solely exists because
89+
bit-manipuation of large amounts of data is slow in python.
90+
91+
The \code{binascii} module defines the following functions:
92+
93+
\renewcommand{\indexsubitem}{(in module binascii)}
94+
95+
\begin{funcdesc}{a2b_uu}{string}
96+
Convert a single line of uuencoded data back to binary and return the
97+
binary data. Lines normally contain 45 (binary) bytes, except for the
98+
last line. Line data may be followed by whitespace.
99+
\end{funcdesc}
100+
101+
\begin{funcdesc}{b2a_uu}{data}
102+
Convert binary data to a line of ascii characters, the return value is
103+
the converted line, including a newline char. The length of \var{data}
104+
should be at most 45.
105+
\end{funcdesc}
106+
107+
\begin{funcdesc}{a2b_hqx}{string}
108+
Convert binhex4 formatted ascii data to binary, without doing
109+
rle-decompression. The string should contain a complete number of
110+
binary bytes, or (in case of the last portion of the binhex4 data)
111+
have the remaining bits zero.
112+
\end{funcdesc}
113+
114+
\begin{funcdesc}{rledecode_hqx}{data}
115+
Perform RLE-decompression on the data, as per the binhex4
116+
standard. The algorithm uses \code{0x90} after a byte as a repeat
117+
indicator, followed by a count. A count of \code{0} specifies a byte
118+
value of \code{0x90}. The routine returns the decompressed data,
119+
unless data input data ends in an orphaned repeat indicator, in which
120+
case the \var{Incomplete} exception is raised.
121+
\end{funcdesc}
122+
123+
\begin{funcdesc}{rlecode_hqx}{data}
124+
Perform binhex4 style RLE-compression on \var{data} and return the
125+
result.
126+
\end{funcdesc}
127+
128+
\begin{funcdesc}{b2a_hqx}{data}
129+
Perform hexbin4 binary-to-ascii translation and return the resulting
130+
string. The argument should already be rle-coded, and have a length
131+
divisible by 3 (except possibly the last fragment).
132+
\end{funcdesc}
133+
134+
\begin{funcdesc}{crc_hqx}{data, crc}
135+
Compute the binhex4 crc value of \var{data}, starting with an initial
136+
\var{crc} and returning the result.
137+
\end{funcdesc}
138+
139+
\begin{excdesc}{Error}
140+
Exception raised on errors. These are usually programming errors.
141+
\end{excdesc}
142+
143+
\begin{excdesc}{Incomplete}
144+
Exception raised on incomplete data. These are usually not programming
145+
errors, but handled by reading a little more data and trying again.
146+
\end{excdesc}

‎Doc/libbinascii.tex‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
\section{Standard module \sectcode{binhex}}
2+
\stmodindex{binhex}
3+
4+
This module encodes and decodes files in binhex4 format, a format
5+
allowing representation of Macintosh files in ASCII. On the macintosh,
6+
both forks of a file and the finder information are encoded (or
7+
decoded), on other platforms only the data fork is handled.
8+
9+
The \code{binhex} module defines the following functions:
10+
11+
\renewcommand{\indexsubitem}{(in module binhex)}
12+
13+
\begin{funcdesc}{binhex}{input\, output}
14+
Convert a binary file with filename \var{input} to binhex file
15+
\var{output}. The \var{output} parameter can either be a filename or a
16+
file-like object (any object supporting a \var{write} and \var{close}
17+
method).
18+
\end{funcdesc}
19+
20+
\begin{funcdesc}{hexbin}{input\optional{\, output}}
21+
Decode a binhex file \var{input}. \var{Input} may be a filename or a
22+
file-like object supporting \var{read} and \var{close} methods.
23+
The resulting file is written to a file named \var{output}, unless the
24+
argument is empty in which case the output filename is read from the
25+
binhex file.
26+
\end{funcdesc}
27+
28+
\subsection{notes}
29+
There is an alternative, more powerful interface to the coder and
30+
decoder, see the source for details.
31+
32+
If you code or decode textfiles on non-Macintosh platforms they will
33+
still use the macintosh newline convention (carriage-return as end of
34+
line).
35+
36+
As of this writing, hexbin appears to not work in all cases.
37+
38+
\section{Standard module \sectcode{uu}}
39+
\stmodindex{uu}
40+
41+
This module encodes and decodes files in uuencode format, allowing
42+
arbitrary binary data to be transferred over ascii-only connections.
43+
44+
The \code{uu} module defines the following functions:
45+
46+
\renewcommand{\indexsubitem}{(in module uu)}
47+
48+
\begin{funcdesc}{encode}{filename\, mode\, in_file\, out_file}
49+
Uuencode file \var{in_file} into file \var{out_file}. Both are
50+
file-like objects supporting a \var{read} and \var{write} method
51+
respectively. The uuencoded file will have the header specifying
52+
\var{filename} and \var{mode} as the defaults for the results of
53+
decoding the file.
54+
\end{funcdesc}
55+
56+
\begin{funcdesc}{decode}{filename\, mode\, in_file}
57+
Note that this function uses a non-standard form of variable
58+
arguments, see below for other variants of argument lists.
59+
60+
This call decodes uuencoded file \var{in_file} (an object supporting a
61+
\var{readline} method), placing the result on a file with name
62+
\var{filename} and mode \var{mode}.
63+
\end{funcdesc}
64+
65+
\begin{funcdesc}{decode}{in_file\, out_file}
66+
An alternative form of \var{decode} which writes the resulting data to
67+
\var{out_file} (an object supporting a \var{write} method).
68+
\end{funcdesc}
69+
70+
\begin{funcdesc}{decode}{in_file}
71+
An alternative form of \var{decode} which stores the result in the
72+
file specified in the uuencoded file.
73+
\end{funcdesc}
74+
75+
\subsection{notes}
76+
This code was contributed by Lance Ellinghouse, and modified by Jack
77+
Jansen to use the \var{binascii} module.
78+
79+
Encoding a file on a non-unix platforms may well result in a file
80+
with the incorrect newline semantics or a file extractable only on the
81+
original platform.
82+
\section{Built-in Module \sectcode{binascii}} % If implemented in C
83+
\bimodindex{binascii}
84+
85+
The binascii module contains a number of methods to convert between
86+
binary and various ascii-encoded binary representations. Normally, you
87+
will not use these modules directly but use wrapper modules like
88+
\var{uu} or \var{hexbin} in stead, this module solely exists because
89+
bit-manipuation of large amounts of data is slow in python.
90+
91+
The \code{binascii} module defines the following functions:
92+
93+
\renewcommand{\indexsubitem}{(in module binascii)}
94+
95+
\begin{funcdesc}{a2b_uu}{string}
96+
Convert a single line of uuencoded data back to binary and return the
97+
binary data. Lines normally contain 45 (binary) bytes, except for the
98+
last line. Line data may be followed by whitespace.
99+
\end{funcdesc}
100+
101+
\begin{funcdesc}{b2a_uu}{data}
102+
Convert binary data to a line of ascii characters, the return value is
103+
the converted line, including a newline char. The length of \var{data}
104+
should be at most 45.
105+
\end{funcdesc}
106+
107+
\begin{funcdesc}{a2b_hqx}{string}
108+
Convert binhex4 formatted ascii data to binary, without doing
109+
rle-decompression. The string should contain a complete number of
110+
binary bytes, or (in case of the last portion of the binhex4 data)
111+
have the remaining bits zero.
112+
\end{funcdesc}
113+
114+
\begin{funcdesc}{rledecode_hqx}{data}
115+
Perform RLE-decompression on the data, as per the binhex4
116+
standard. The algorithm uses \code{0x90} after a byte as a repeat
117+
indicator, followed by a count. A count of \code{0} specifies a byte
118+
value of \code{0x90}. The routine returns the decompressed data,
119+
unless data input data ends in an orphaned repeat indicator, in which
120+
case the \var{Incomplete} exception is raised.
121+
\end{funcdesc}
122+
123+
\begin{funcdesc}{rlecode_hqx}{data}
124+
Perform binhex4 style RLE-compression on \var{data} and return the
125+
result.
126+
\end{funcdesc}
127+
128+
\begin{funcdesc}{b2a_hqx}{data}
129+
Perform hexbin4 binary-to-ascii translation and return the resulting
130+
string. The argument should already be rle-coded, and have a length
131+
divisible by 3 (except possibly the last fragment).
132+
\end{funcdesc}
133+
134+
\begin{funcdesc}{crc_hqx}{data, crc}
135+
Compute the binhex4 crc value of \var{data}, starting with an initial
136+
\var{crc} and returning the result.
137+
\end{funcdesc}
138+
139+
\begin{excdesc}{Error}
140+
Exception raised on errors. These are usually programming errors.
141+
\end{excdesc}
142+
143+
\begin{excdesc}{Incomplete}
144+
Exception raised on incomplete data. These are usually not programming
145+
errors, but handled by reading a little more data and trying again.
146+
\end{excdesc}

0 commit comments

Comments
 (0)