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!  (Send via email to \email{python-docs@python.org}.)

The idea and original contents for this chapter were taken
from a posting by Fredrik Lundh; the specific contents of this chapter
have been substantially revised.


\section{Frameworks}

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

\begin{description}
\item[\module{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 single module.
\end{description}


\section{Miscellaneous useful utilities}

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

\begin{description}
\item[\module{bdb}]
--- A generic Python debugger base class (used by pdb).

\item[\module{ihooks}]
--- Import hook support (for \refmodule{rexec}; may become obsolete).

\item[\module{platform}]
--- This module tries to retrieve as much platform identifying data as
possible.  It makes this information available via function APIs.
If called from the command line, it prints the platform information
concatenated as single string to \code{sys.stdout}.  The output format
is useable as part of a filename.
\versionadded{2.3}

\item[\module{smtpd}]
--- An SMTP daemon implementation which meets the minimum requirements
for \rfc{821} conformance.
\end{description}


\section{Platform specific modules}

These modules are used to implement the \refmodule{os.path} module,
and are not documented beyond this mention.  There's little need to
document these.

\begin{description}
\item[\module{ntpath}]
--- Implementation on \module{os.path} on Win32, Win64, WinCE, and
OS/2 platforms.

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

\item[\module{bsddb185}]
--- Backwards compatibility module for systems which still use the Berkeley
DB 1.85 module.  It is normally only available on certain BSD Unix-based
systems.  It should never be used directly.
\end{description}


\section{Multimedia}

\begin{description}
\item[\module{audiodev}]
--- Platform-independent API for playing audio data.

\item[\module{linuxaudiodev}]
--- Play audio data on the Linux audio device.  Replaced in Python 2.3
by the \module{ossaudiodev} module.

\item[\module{sunaudio}]
--- Interpret Sun audio headers (may become obsolete or a tool/demo).

\item[\module{toaiff}]
--- Convert "arbitrary" sound files to AIFF files; should probably
become a tool or demo.  Requires the external program \program{sox}.

\item[\module{ossaudiodev}]
--- Play audio data via the Open Sound System API.  This is usable on
Linux, some flavors of BSD, and some commercial \UNIX{} platforms.
\end{description}


\section{Obsolete \label{obsolete-modules}}

These modules are not normally available for import; additional work
must be done to make them available.

Those which are written in Python will be installed into the directory 
\file{lib-old/} installed as part of the standard library.  To use
these, the directory must be added to \code{sys.path}, possibly using
\envvar{PYTHONPATH}.

Obsolete extension modules written in C are not built by default.
Under \UNIX, these must be enabled by uncommenting the appropriate
lines in \file{Modules/Setup} in the build tree and either rebuilding
Python if the modules are statically linked, or building and
installing the shared object if using dynamically-loaded extensions.

% XXX need Windows instructions!

\begin{description}
\item[\module{addpack}]
--- Alternate approach to packages.  Use the built-in package support
instead.

\item[\module{cmp}]
--- File comparison function.  Use the newer \refmodule{filecmp} instead.

\item[\module{cmpcache}]
--- Caching version of the obsolete \module{cmp} module.  Use the
newer \refmodule{filecmp} instead.

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

\item[\module{dircmp}]
--- Class to build directory diff tools on (may become a demo or tool).
\deprecated{2.0}{The \refmodule{filecmp} module replaces
\module{dircmp}.}

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

\item[\module{fmt}]
--- Text formatting abstractions (too slow).

\item[\module{lockfile}]
--- Wrapper around FCNTL file locking (use
\function{fcntl.lockf()}/\function{flock()} instead; see \refmodule{fcntl}).

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

\item[\module{Para}]
--- Helper for \module{fmt}.

\item[\module{poly}]
--- Polynomials.

\item[\module{regex}]
--- Emacs-style regular expression support; may still be used in some
old code (extension module).  Refer to the
\citetitle[http://www.python.org/doc/1.6/lib/module-regex.html]{Python
1.6 Documentation} for documentation.

\item[\module{regsub}]
--- Regular expression based string replacement utilities, for use
with \module{regex} (extension module).  Refer to the
\citetitle[http://www.python.org/doc/1.6/lib/module-regsub.html]{Python
1.6 Documentation} for documentation.

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

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

\item[\module{tzparse}]
--- Parse a timezone specification (unfinished; may disappear in the
future, and does not work when the \envvar{TZ} environment variable is
not set).

\item[\module{util}]
--- Useful functions that don't fit elsewhere.

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

\item[\module{zmod}]
--- Compute properties of mathematical ``fields.''
\end{description}


The following modules are obsolete, but are likely to re-surface as
tools or scripts:

\begin{description}
\item[\module{find}]
--- Find files matching pattern in directory tree.

\item[\module{grep}]
--- \program{grep} implementation in Python.

\item[\module{packmail}]
--- Create a self-unpacking \UNIX{} shell archive.
\end{description}


The following modules were documented in previous versions of this
manual, but are now considered obsolete.  The source for the
documentation is still available as part of the documentation source
archive.

\begin{description}
\item[\module{ni}]
--- Import modules in ``packages.''  Basic package support is now
built in.  The built-in support is very similar to what is provided in
this module.

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

\item[\module{soundex}]
--- Algorithm for collapsing names which sound similar to a shared
key.  The specific algorithm doesn't seem to match any published
algorithm.  (This is an extension module.)
\end{description}


\section{SGI-specific Extension modules}

The following are SGI specific, and may be out of touch with the
current version of reality.

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

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