Doc/lib/libundoc.tex

\chapter{Undocumented Modules}
\label{undoc}

Here's a quick listing of modules that are currently undocumented, but
that should be documented.  Feel free to contribute documentation for
them!  (The idea and original contents for this chapter were taken
from a posting by Fredrik Lundh; I have revised some modules' status.)


\section{Frameworks}

Frameworks tend to be harder to document, but are well worth the
effort spent.

\begin{description}
\item[Tkinter.py]
--- Interface to Tcl/Tk for graphical user interfaces;
Fredrik Lundh is working on this one!  See \emph{An Introduction to
Tkinter} at
\url{http://www.pythonware.com/library/tkinter/introduction} for
on-line reference material.

\item[Tkdnd.py]
--- Drag-and-drop support for \module{Tkinter}.

\item[CGIHTTPServer.py]
--- CGI-savvy HTTP Server

\item[SimpleHTTPServer.py]
--- Simple HTTP Server

\item[test]
--- Regression testing framework.  This is used for the Python
regression test, but is useful for other Python libraries as well.
This is a package rather than a module.
\end{description}


\section{Miscellaneous useful utilities}

Some of these are very old and/or not very robust; marked with ``hmm''.

\begin{description}
\item[cmp.py]
--- Efficiently compare files

\item[cmpcache.py]
--- Efficiently compare files (uses statcache)

\item[dircache.py]
--- like os.listdir, but caches results

\item[dircmp.py]
--- class to build directory diff tools on

\item[linecache.py]
--- Cache lines from files (used by pdb)

\item[pipes.py]
--- Conversion pipeline templates (hmm)

\item[statcache.py]
--- Maintain a cache of file stats

\item[pty.py]
--- Pseudo terminal utilities

\item[tty.py]
--- Terminal utilities

\item[bdb.py]
--- A generic Python debugger base class (used by pdb)

\item[wdb.py]
--- A primitive windowing debugger based on STDWIN.

\item[ihooks.py]
--- Import hook support (for rexec)
\end{description}


\section{Platform specific modules}


These modules are used to implement the \refmodule{os.path} module, and
are not documented beyond this mention.

\begin{description}
\item[dospath.py]
--- implementation of \module{os.path} on MS-DOS

\item[ntpath.py]
--- implementation on \module{os.path} on 32-bit Windows

\item[posixpath.py]
--- implementation on \module{os.path} on \POSIX{}
\end{description}


\section{Multimedia}

\begin{description}
\item[audiodev.py]
--- Plays audio files

\item[sunau.py]
--- parse Sun and NeXT audio files

\item[sunaudio.py]
--- interpret sun audio headers

\item[toaiff.py]
--- Convert "arbitrary" sound files to AIFF files

\item[wave.py]
--- parse WAVE files
\end{description}


\section{Oddities}

These modules are probably also obsolete, or just not very useful.

\begin{description}
\item[dump.py]
--- Print python code that reconstructs a variable

\item[find.py]
--- find files matching pattern in directory tree

\item[fpformat.py]
--- General floating point formatting functions ---
interesting demonstration of how to do this without using the \C{}
library

\item[grep.py]
--- grep

\item[mutex.py]
--- Mutual exclusion --- for use with module sched

\item[packmail.py]
--- create a self-unpacking \UNIX{} shell archive

\item[sched.py]
--- event scheduler class

\item[tzparse.py]
--- Parse a timezone specification (unfinished)
\end{description}


\section{Obsolete}

These modules are not on the standard module search path;
\indexiii{module}{search}{path}
but are available in the directory \file{lib-old/} installed  under
\file{\textrm{\$prefix}/lib/python1.5/}. % $ <-- bow to font lock
To use any of these modules, add that directory to \code{sys.path},
possibly using \envvar{PYTHONPATH}.

\begin{description}
\item[newdir.py]
--- New dir() function (the standard dir() is now just as good)

\item[addpack.py]
--- standard support for "packages"

\item[codehack.py]
--- Extract function name or line number from a function
code object (these are now accessible as attributes: co.co_name,
func.func_name, co.co_firstlineno).

\item[fmt.py]
--- text formatting abstractions (too slow)

\item[Para.py]
--- helper for fmt.py

\item[lockfile.py]
--- wrapper around FCNTL file locking (use
\function{fcntl.lockf()}/\function{flock()} intead)

\item[poly.py]
--- Polynomials

\item[tb.py]
--- Print tracebacks, with a dump of local variables (use
\function{pdb.pm()} or \refmodule{traceback} instead)

\item[timingmodule]
--- Measure time intervals to high resolution (use
\function{time.clock()} instead).  (This is an extension module.)

\item[util.py]
--- Useful functions that don't fit elsewhere.

\item[whatsound.py]
--- Recognize sound files; use \refmodule{sndhdr} instead.

\item[zmod.py]
--- Compute properties of mathematical "fields"
\end{description}

The following modules were documented in previous versions of this
manual, but are now considered obsolete:

\begin{description}
\item[ni]
--- Import modules in ``packages.''  Basic package support is now
built in.

\item[rand]
--- Old interface to the random number generator.

\item[soundex]
--- Algorithm for collapsing names which sound similar to a shared
key.  (This is an extension module.)
\end{description}


\section{Extension modules}

\begin{description}
\item[cursesmodule.c]
--- Curses interface.

\item[dlmodule.c]
---  A highly experimental and dangerous device for calling
arbitrary \C{} functions in arbitrary shared libraries.

\item[newmodule.c]
--- Tommy Burnette's \module{new} module (creates new empty objects of
certain kinds) --- dangerous.

\item[nismodule.c]
--- NIS (a.k.a. Sun's Yellow Pages) interface.

\item[stdwinmodule.c]
--- Interface to STDWIN (an old, unsupported
platform-independent GUI package).  Obsolete; use Tkinter for a
platform-independent GUI instead.
\end{description}

The following are SGI specific:

\begin{description}
\item[clmodule.c]
--- Interface to the SGI compression library.

\item[svmodule.c]
--- Interface to the ``simple video'' board on SGI Indigo
(obsolete hardware).
\end{description}