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

Skip to content

Commit 64bc94e

Browse files
freddrakefreddrake
committed
New module documentation sections from Moshe Zadka <[email protected]>!
1 parent 668213d commit 64bc94e

6 files changed

Lines changed: 390 additions & 0 deletions

File tree

‎Doc/lib/libcmp.tex‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
\section{\module{cmp} ---
2+
File comparisons}
3+
4+
\declaremodule{standard}{cmp}
5+
\sectionauthor{Moshe Zadka}{[email protected]}
6+
\modulesynopsis{Compare files very efficiently.}
7+
8+
The \module{cmp} module defines a function to compare files, taking all
9+
sort of short-cuts to make it a highly efficient operation.
10+
11+
The \module{cmp} module defines the following function:
12+
13+
\begin{funcdesc}{cmp}{f1, f2}
14+
Compare two files given as names. The following tricks are used to
15+
optimize the comparisons:
16+
17+
\begin{itemize}
18+
\item Files with identical type, size and mtime are assumed equal.
19+
\item Files with different type or size are never equal.
20+
\item The module only compares files it already compared if their
21+
signature (type, size and mtime) changed.
22+
\item No external programs are called.
23+
\end{itemize}
24+
\end{funcdesc}
25+
26+
Example:
27+
28+
\begin{verbatim}
29+
>>> import cmp
30+
>>> cmp.cmp('libundoc.tex', 'libundoc.tex')
31+
1
32+
>>> cmp.cmp('libundoc.tex', 'lib.tex')
33+
0
34+
\end{verbatim}

‎Doc/lib/libcmpcache.tex‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
\section{\module{cmpcache} ---
2+
Efficient file comparisons}
3+
4+
\declaremodule{standard}{cmpcache}
5+
\sectionauthor{Moshe Zadka}{[email protected]}
6+
\modulesynopsis{Compare files very efficiently.}
7+
8+
The \module{cmpcache} module defines a function to compare files, taking all
9+
sort of short-cuts to make it a highly efficient operation.
10+
11+
The \module{cmpcache} module defines the following function:
12+
13+
\begin{funcdesc}{cmp}{f1, f2}
14+
Compare two files given as names. The following tricks are used to
15+
optimize the comparisons:
16+
17+
\begin{itemize}
18+
\item Signatures (type, size and mtime) are computed via
19+
\refmodule{statcache}
20+
\item Files with identical type, size and mtime are assumed equal.
21+
\item Files with different type or size are never equal.
22+
\item The module only compares files it already compared if their
23+
signature changed.
24+
\item No external programs are called.
25+
\end{itemize}
26+
\end{funcdesc}
27+
28+
Example:
29+
30+
\begin{verbatim}
31+
>>> import cmpcache
32+
>>> cmpcache.cmp('libundoc.tex', 'libundoc.tex')
33+
1
34+
>>> cmpcache.cmp('libundoc.tex', 'lib.tex')
35+
0
36+
\end{verbatim}

‎Doc/lib/libdircache.tex‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
\section{\module{dircache} ---
2+
Cached directory listings}
3+
4+
\declaremodule{standard}{dircache}
5+
\sectionauthor{Moshe Zadka}{[email protected]}
6+
\modulesynopsis{Return directory listing, with cache mechanism.}
7+
8+
The \module{dircache} module defines a function for reading directory listing
9+
using a cache, and cache invalidation using the \var{mtime} of the directory.
10+
Additionally, it defines a function to annotate directories by appending
11+
a slash.
12+
13+
The \module{dircache} module defines the following functions:
14+
15+
\begin{funcdesc}{listdir}{path}
16+
Return a directory listing of \var{path}, as gotten from
17+
\function{os.listdir()}. Note that unless \var{path} changes, further call
18+
to \function{listdir()} will not re-read the directory structure.
19+
20+
Note that the list returned should be regarded as read-only. (Perhaps
21+
a future version should change it to return a tuple?)
22+
\end{funcdesc}
23+
24+
\begin{funcdesc}{opendir}{path}
25+
Same as \function{listdir()}. Defined for backwards compatability.
26+
\end{funcdesc}
27+
28+
\begin{funcdesc}{annotate}{head, list}
29+
Assume \var{list} is a list of pathes relative to \var{head}, and append,
30+
in place, a \character{/} to each path which points to a directory.
31+
\end{funcdesc}
32+
33+
\begin{verbatim}
34+
>>> import dircache
35+
>>> a=dircache.listdir('/')
36+
>>> a=a[:] # Copy the return value so we can change 'a'
37+
>>> a
38+
['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
39+
found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
40+
>>> dircache.annotate('/', a)
41+
>>> a
42+
['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
43+
', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
44+
linuz']
45+
\end{verbatim}

‎Doc/lib/libnew.tex‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
\section{\module{new} ---
2+
Runtime implementation object creation}
3+
4+
\declaremodule{builtin}{new}
5+
\sectionauthor{Moshe Zadka}{[email protected]}
6+
\modulesynopsis{Interface to the creation of runtime implementation objects.}
7+
8+
9+
The \module{new} module allows an interface to the interpreter object
10+
creation functions. This is for use primarily in marshal-type functions,
11+
when a new object needs to be created ``magically'' and not by using the
12+
regular creation functions. This module provides a low-level interface
13+
to the interpreter, so care must be exercised when using this module.
14+
15+
The \module{new} module defines the following functions:
16+
17+
\begin{funcdesc}{instance}{class, dict}
18+
This function creates an instance of \class{class} with dictionary
19+
\var{dict} without calling the \method{__init__()} constructor. Note that
20+
this means that there are no guarantees that the object will be in a
21+
consistent state.
22+
23+
Arguments are \emph{not} type-checked, and an incorrectly typed argument
24+
will result in undefined behaviour.
25+
\end{funcdesc}
26+
27+
\begin{funcdesc}{instancemethod}{function, instance, class}
28+
This function will return a method object, bound to \var{instance}, or
29+
unbound if \var{instance} is \code{None}. It is checked that
30+
\var{function} is callable, and that \var{instance} is an instance
31+
object or \code{None}.
32+
\end{funcdesc}
33+
34+
\begin{funcdesc}{function}{code, globals\optional{, name\optional{argdefs}}}
35+
Returns a (Python) function with the given code and globals. If
36+
\var{name} is given, the function will have the given name. If
37+
\var{argdefs} is given, they will be the function defaults.
38+
\end{funcdesc}
39+
40+
\begin{funcdesc}{code}{argcount, nlocals, stacksize, flags, codestring,
41+
constants, names, varnames, filename, name, firstlineno,
42+
lnotab}
43+
This function is an interface to the \cfunction{PyCode_New()} internal
44+
function.
45+
XXX This is still undocumented!!!!!!!!!!!
46+
\end{funcdesc}
47+
48+
\begin{funcdesc}{module}{name}
49+
This function returns a new module object with name \var{name}.
50+
\var{name} should be a string.
51+
\end{funcdesc}
52+
53+
\begin{funcdesc}{classobj}{name, baseclasses, dict}
54+
This function returns a new class object, with name \var{name}, derived
55+
from \var{baseclasses} (which should be a tuple of classes) and with
56+
namespace \var{dict}. All parameters are type checked.
57+
\end{funcdesc}

‎Doc/lib/libstatcache.tex‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
\section{\module{statcache} ---
2+
An optimization of \function{os.stat()}}
3+
4+
\declaremodule{standard}{statcache}
5+
\sectionauthor{Moshe Zadka}{[email protected]}
6+
\modulesynopsis{Stat files, and remember results.}
7+
8+
The \module{statcache} module provides a simple optimization to
9+
\function{os.stat()}: remembering the values of previous invocations.
10+
11+
The \module{statcache} module defines the following functions:
12+
13+
\begin{funcdesc}{stat}{path}
14+
This is the main module entry-point.
15+
Identical for \function{os.stat()}, except for remembering the result
16+
for future invocations of the function.
17+
\end{funcdesc}
18+
19+
The rest of the functions are used to clear the cache, or parts of
20+
it.
21+
22+
\begin{funcdesc}{reset}{}
23+
Clear the cache: forget all results of previous \code{stat}s.
24+
\end{funcdesc}
25+
26+
\begin{funcdesc}{forget}{path}
27+
Forget the result of \code{stat(\var{path})}, if any.
28+
\end{funcdesc}
29+
30+
\begin{funcdesc}{forget_prefix}{prefix}
31+
Forget all results of \code{stat(\var{path})} for \var{path} starting
32+
with \var{prefix}.
33+
\end{funcdesc}
34+
35+
\begin{funcdesc}{forget_dir}{prefix}
36+
Forget all results of \code{stat(\var{path})} for \var{path} a file in
37+
the directory \var{prefix}, including \code{stat(\var{prefix})}.
38+
\end{funcdesc}
39+
40+
\begin{funcdesc}{forget_except_prefix}{prefix}
41+
Similar to \function{forget_prefix()}, but for all \var{path}
42+
\emph{not} starting with \var{prefix}.
43+
\end{funcdesc}
44+
45+
Example:
46+
47+
\begin{verbatim}
48+
>>> import os, statcache
49+
>>> statcache.stat('.')
50+
(16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777)
51+
>>> os.stat('.')
52+
(16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777)
53+
\end{verbatim}

‎Doc/lib/libwave.tex‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
% Documentations stolen and LaTeX'ed from comments in file.
2+
\section{\module{wave} ---
3+
Read and write .WAV files}
4+
5+
\declaremodule{standard}{wave}
6+
\sectionauthor{Moshe Zadka}{[email protected]}
7+
\modulesynopsis{Provide an interface to the WAV sound format.}
8+
9+
The \module{wave} module provides a convenient interface to the WAV sound
10+
format. It does not support compression/decompression, but it does support
11+
mono/stereo.
12+
13+
The \module{wave} module defines the following function:
14+
15+
\begin{funcdesc}{open}{file, mode}
16+
If \var{file} is a string, open the file by that name, other treat it
17+
as a seekable file-like object. \var{mode} can be any of
18+
\begin{description}
19+
\item[\code{'r'}, \code{'rb'}] Read only mode.
20+
\item[\code{'w'}, \code{'wb'}] Write only mode.
21+
\end{description}
22+
Note that it does not allow read/write WAV files.
23+
24+
A \var{mode} of \code{'r'} or \code{'rb'} returns a \class{Wave_read}
25+
object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
26+
a \class{Wave_write} object.
27+
\end{funcdesc}
28+
29+
\begin{funcdesc}{openfp}{file, mode}
30+
A synonym for \function{open()}, maintained for backwards compatibility.
31+
\end{funcdesc}
32+
33+
\begin{excdesc}{Error}
34+
An error raised when something is impossible because it violates the
35+
WAV specification or hits an implementation deficiency.
36+
\end{excdesc}
37+
38+
39+
\subsection{Wave_read Objects \label{Wave-read-objects}}
40+
41+
Wave_read objects, as returned by \function{open()} above, have the
42+
following methods:
43+
44+
\begin{methoddesc}[Wave_read]{getnchannels}{}
45+
Returns number of audio channels (1 for mone, 2 for stereo).
46+
\end{methoddesc}
47+
48+
\begin{methoddesc}[Wave_read]{getsampwidth}{}
49+
Returns sample width in bytes.
50+
\end{methoddesc}
51+
52+
\begin{methoddesc}[Wave_read]{getframerate}{}
53+
Returns sampling frequency.
54+
\end{methoddesc}
55+
56+
\begin{methoddesc}[Wave_read]{getnframes}{}
57+
Returns number of audio frames.
58+
\end{methoddesc}
59+
60+
\begin{methoddesc}[Wave_read]{getcomptype}{}
61+
Returns compression type (\code{'NONE'} is the only supported type).
62+
\end{methoddesc}
63+
64+
\begin{methoddesc}[Wave_read]{getcompname}{}
65+
Human-readable version of \method{getcomptype()}.
66+
Usually \code{'not compressed'} parallels \code{'NONE'}.
67+
\end{methoddesc}
68+
69+
\begin{methoddesc}[Wave_read]{getparams}{}
70+
Returns a tuple
71+
\code{(nchannels, sampwidth, framerate, nframes, comptype, compname)},
72+
equivalent to output of the \code{get} methods.
73+
\end{methoddesc}
74+
75+
\begin{methoddesc}[Wave_read]{readframes}{n}
76+
Reads and returns at most \var{n} frames of audio, as a string of bytes.
77+
\end{methoddesc}
78+
79+
\begin{methoddesc}[Wave_read]{rewind}{}
80+
Rewind the file pointer to the beginning of the audio stream.
81+
\end{methoddesc}
82+
83+
The following two functions are defined for compatibility with the
84+
\refmodule{aifc} module, and don't do anything interesting.
85+
86+
\begin{methoddesc}[Wave_read]{getmarkers}{}
87+
Returns \code{None}.
88+
\end{methoddesc}
89+
90+
\begin{methoddesc}[Wave_read]{getmark}{id}
91+
Raise an error.
92+
\end{methoddesc}
93+
94+
The following two methods define a term ``position'' which is compatible
95+
between them, and is otherwise implementation dependant.
96+
97+
\begin{methoddesc}[Wave_read]{setpos}{pos}
98+
Set the file pointer to the specified position.
99+
\end{methoddesc}
100+
101+
\begin{methoddesc}[Wave_read]{tell}{}
102+
Return current file pointer position.
103+
\end{methoddesc}
104+
105+
\begin{methoddesc}[Wave_read]{close}{}
106+
Close the stream, and make the instance unusable. (This is
107+
called automatically on deletion.
108+
\end{methoddesc}
109+
110+
111+
\subsection{Wave_write Objects \label{Wave-write-objects}}
112+
113+
Wave_write objects, as returned by \function{open()} above, have the
114+
following methods:
115+
116+
\begin{methoddesc}[Wave_write]{setnchannels}{n}
117+
Set the number of channels.
118+
\end{methoddesc}
119+
120+
\begin{methoddesc}[Wave_write]{setsampwidth}{n}
121+
Set the sample width (in bytes.)
122+
\end{methoddesc}
123+
124+
\begin{methoddesc}[Wave_write]{setframerate}{n}
125+
Set the frame rate.
126+
\end{methoddesc}
127+
128+
\begin{methoddesc}[Wave_write]{setnframes}{n}
129+
Set the number of frames. This can be later changed, when and if more
130+
frames are written.
131+
\end{methoddesc}
132+
133+
\begin{methoddesc}[Wave_write]{setcomptype}{type, name}
134+
Set the compression type and description.
135+
\end{methoddesc}
136+
137+
\begin{methoddesc}[Wave_write]{setparams}{tuple}
138+
The \var{tuple} should be
139+
\code{(\var{nchannels}, \var{sampwidth}, \var{framerate},
140+
\var{nframes}, \var{comptype}, \var{compname})}, with values valid for
141+
the \code{set} methods. Set all parameters.
142+
\end{methoddesc}
143+
144+
\begin{methoddesc}[Wave_write]{tell}{}
145+
Return current position in the file, with the same disclaimer for
146+
the \method{Wave_read.tell} and \method{Wave_read.setpos} methods.
147+
\end{methoddesc}
148+
149+
\begin{methoddesc}[Wave_write]{writeframesraw}{data}
150+
Write audio frames, without correcting \var{nframes}.
151+
\end{methoddesc}
152+
153+
\begin{methoddesc}[Wave_write]{writeframes}{data}
154+
Write audio frames and make sure \var{nframes} is correct.
155+
\end{methoddesc}
156+
157+
\begin{methoddesc}[Wave_write]{close}{}
158+
Make sure \var{nframes} is correct, and close the file.
159+
160+
This method is called upon deletion.
161+
\end{methoddesc}
162+
163+
Note that it is invalid to set any parameters after calling
164+
\method{writeframes()} or \method{writeframesraw()}, and any attempt
165+
to do so will raise an error.

0 commit comments

Comments
 (0)