Doc/lib/libundoc.tex

   1 \chapter{Undocumented Modules \label{undoc}}
   2
   3 Here's a quick listing of modules that are currently undocumented, but
   4 that should be documented.  Feel free to contribute documentation for
   5 them!  (Send via email to \email{docs@python.org}.)
   6
   7 The idea and original contents for this chapter were taken
   8 from a posting by Fredrik Lundh; the specific contents of this chapter
   9 have been substantially revised.
  10
  11
  12 \section{Frameworks}
  13
  14 Frameworks tend to be harder to document, but are well worth the
  15 effort spent.
  16
  17 \begin{description}
  18 \item[\module{test}]
  19 --- Regression testing framework.  This is used for the Python
  20 regression test, but is useful for other Python libraries as well.
  21 This is a package rather than a single module.
  22 \end{description}
  23
  24
  25 \section{Miscellaneous useful utilities}
  26
  27 Some of these are very old and/or not very robust; marked with ``hmm.''
  28
  29 \begin{description}
  30 \item[\module{bdb}]
  31 --- A generic Python debugger base class (used by pdb).
  32
  33 \item[\module{ihooks}]
  34 --- Import hook support (for \refmodule{rexec}; may become obsolete).
  35
  36 \item[\module{platform}]
  37 --- This module tries to retrieve as much platform identifying data as
  38 possible.  It makes this information available via function APIs.
  39 If called from the command line, it prints the platform information
  40 concatenated as single string to \code{sys.stdout}.  The output format
  41 is useable as part of a filename.
  42 \versionadded{2.3}
  43
  44 \item[\module{smtpd}]
  45 --- An SMTP daemon implementation which meets the minimum requirements
  46 for \rfc{821} conformance.
  47 \end{description}
  48
  49
  50 \section{Platform specific modules}
  51
  52 These modules are used to implement the \refmodule{os.path} module,
  53 and are not documented beyond this mention.  There's little need to
  54 document these.
  55
  56 \begin{description}
  57 \item[\module{ntpath}]
  58 --- Implementation of \module{os.path} on Win32, Win64, WinCE, and
  59 OS/2 platforms.
  60
  61 \item[\module{posixpath}]
  62 --- Implementation of \module{os.path} on \POSIX.
  63
  64 \item[\module{bsddb185}]
  65 --- Backwards compatibility module for systems which still use the Berkeley
  66 DB 1.85 module.  It is normally only available on certain BSD Unix-based
  67 systems.  It should never be used directly.
  68 \end{description}
  69
  70
  71 \section{Multimedia}
  72
  73 \begin{description}
  74 \item[\module{audiodev}]
  75 --- Platform-independent API for playing audio data.
  76
  77 \item[\module{linuxaudiodev}]
  78 --- Play audio data on the Linux audio device.  Replaced in Python 2.3
  79 by the \module{ossaudiodev} module.
  80
  81 \item[\module{sunaudio}]
  82 --- Interpret Sun audio headers (may become obsolete or a tool/demo).
  83
  84 \item[\module{toaiff}]
  85 --- Convert "arbitrary" sound files to AIFF files; should probably
  86 become a tool or demo.  Requires the external program \program{sox}.
  87
  88 \item[\module{ossaudiodev}]
  89 --- Play audio data via the Open Sound System API.  This is usable on
  90 Linux, some flavors of BSD, and some commercial \UNIX{} platforms.
  91 \end{description}
  92
  93
  94 \section{Obsolete \label{obsolete-modules}}
  95
  96 These modules are not normally available for import; additional work
  97 must be done to make them available.
  98
  99 Those which are written in Python will be installed into the directory
 100 \file{lib-old/} installed as part of the standard library.  To use
 101 these, the directory must be added to \code{sys.path}, possibly using
 102 \envvar{PYTHONPATH}.
 103
 104 Obsolete extension modules written in C are not built by default.
 105 Under \UNIX, these must be enabled by uncommenting the appropriate
 106 lines in \file{Modules/Setup} in the build tree and either rebuilding
 107 Python if the modules are statically linked, or building and
 108 installing the shared object if using dynamically-loaded extensions.
 109
 110 % XXX need Windows instructions!
 111
 112 \begin{description}
 113 \item[\module{addpack}]
 114 --- Alternate approach to packages.  Use the built-in package support
 115 instead.
 116
 117 \item[\module{cmp}]
 118 --- File comparison function.  Use the newer \refmodule{filecmp} instead.
 119
 120 \item[\module{cmpcache}]
 121 --- Caching version of the obsolete \module{cmp} module.  Use the
 122 newer \refmodule{filecmp} instead.
 123
 124 \item[\module{codehack}]
 125 --- Extract function name or line number from a function
 126 code object (these are now accessible as attributes:
 127 \member{co.co_name}, \member{func.func_name},
 128 \member{co.co_firstlineno}).
 129
 130 \item[\module{dircmp}]
 131 --- Class to build directory diff tools on (may become a demo or tool).
 132 \deprecated{2.0}{The \refmodule{filecmp} module replaces
 133 \module{dircmp}.}
 134
 135 \item[\module{dump}]
 136 --- Print python code that reconstructs a variable.
 137
 138 \item[\module{fmt}]
 139 --- Text formatting abstractions (too slow).
 140
 141 \item[\module{lockfile}]
 142 --- Wrapper around FCNTL file locking (use
 143 \function{fcntl.lockf()}/\function{flock()} instead; see \refmodule{fcntl}).
 144
 145 \item[\module{newdir}]
 146 --- New \function{dir()} function (the standard \function{dir()} is
 147 now just as good).
 148
 149 \item[\module{Para}]
 150 --- Helper for \module{fmt}.
 151
 152 \item[\module{poly}]
 153 --- Polynomials.
 154
 155 \item[\module{regex}]
 156 --- Emacs-style regular expression support; may still be used in some
 157 old code (extension module).  Refer to the
 158 \citetitle[http://www.python.org/doc/1.6/lib/module-regex.html]{Python
 159 1.6 Documentation} for documentation.
 160
 161 \item[\module{regsub}]
 162 --- Regular expression based string replacement utilities, for use
 163 with \module{regex} (extension module).  Refer to the
 164 \citetitle[http://www.python.org/doc/1.6/lib/module-regsub.html]{Python
 165 1.6 Documentation} for documentation.
 166
 167 \item[\module{tb}]
 168 --- Print tracebacks, with a dump of local variables (use
 169 \function{pdb.pm()} or \refmodule{traceback} instead).
 170
 171 \item[\module{timing}]
 172 --- Measure time intervals to high resolution (use
 173 \function{time.clock()} instead).  (This is an extension module.)
 174
 175 \item[\module{tzparse}]
 176 --- Parse a timezone specification (unfinished; may disappear in the
 177 future, and does not work when the \envvar{TZ} environment variable is
 178 not set).
 179
 180 \item[\module{util}]
 181 --- Useful functions that don't fit elsewhere.
 182
 183 \item[\module{whatsound}]
 184 --- Recognize sound files; use \refmodule{sndhdr} instead.
 185
 186 \item[\module{zmod}]
 187 --- Compute properties of mathematical ``fields.''
 188 \end{description}
 189
 190
 191 The following modules are obsolete, but are likely to re-surface as
 192 tools or scripts:
 193
 194 \begin{description}
 195 \item[\module{find}]
 196 --- Find files matching pattern in directory tree.
 197
 198 \item[\module{grep}]
 199 --- \program{grep} implementation in Python.
 200
 201 \item[\module{packmail}]
 202 --- Create a self-unpacking \UNIX{} shell archive.
 203 \end{description}
 204
 205
 206 The following modules were documented in previous versions of this
 207 manual, but are now considered obsolete.  The source for the
 208 documentation is still available as part of the documentation source
 209 archive.
 210
 211 \begin{description}
 212 \item[\module{ni}]
 213 --- Import modules in ``packages.''  Basic package support is now
 214 built in.  The built-in support is very similar to what is provided in
 215 this module.
 216
 217 \item[\module{rand}]
 218 --- Old interface to the random number generator.
 219
 220 \item[\module{soundex}]
 221 --- Algorithm for collapsing names which sound similar to a shared
 222 key.  The specific algorithm doesn't seem to match any published
 223 algorithm.  (This is an extension module.)
 224 \end{description}
 225
 226
 227 \section{SGI-specific Extension modules}
 228
 229 The following are SGI specific, and may be out of touch with the
 230 current version of reality.
 231
 232 \begin{description}
 233 \item[\module{cl}]
 234 --- Interface to the SGI compression library.
 235
 236 \item[\module{sv}]
 237 --- Interface to the ``simple video'' board on SGI Indigo
 238 (obsolete hardware).
 239 \end{description}