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{python-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{Tkinter}]
  19 --- Interface to Tcl/Tk for graphical user interfaces; Fredrik Lundh
  20 is working on this one!  See
  21 \citetitle[http://www.pythonware.com/library.htm]{An Introduction to
  22 Tkinter} at \url{http://www.pythonware.com/library.htm} for on-line
  23 reference material.
  24
  25 \item[\module{Tkdnd}]
  26 --- Drag-and-drop support for \module{Tkinter}.
  27
  28 \item[\module{turtle}]
  29 --- Turtle graphics in a Tk window.
  30
  31 \item[\module{test}]
  32 --- Regression testing framework.  This is used for the Python
  33 regression test, but is useful for other Python libraries as well.
  34 This is a package rather than a single module.
  35 \end{description}
  36
  37
  38 \section{Miscellaneous useful utilities}
  39
  40 Some of these are very old and/or not very robust; marked with ``hmm.''
  41
  42 \begin{description}
  43 \item[\module{bdb}]
  44 --- A generic Python debugger base class (used by pdb).
  45
  46 \item[\module{ihooks}]
  47 --- Import hook support (for \refmodule{rexec}; may become obsolete).
  48
  49 \item[\module{tzparse}]
  50 --- Parse a timezone specification (unfinished; may disappear in the
  51 future).
  52 \end{description}
  53
  54
  55 \section{Platform specific modules}
  56
  57 These modules are used to implement the \refmodule{os.path} module,
  58 and are not documented beyond this mention.  There's little need to
  59 document these.
  60
  61 \begin{description}
  62 \item[\module{dospath}]
  63 --- Implementation of \module{os.path} on MS-DOS.
  64
  65 \item[\module{ntpath}]
  66 --- Implementation on \module{os.path} on Win32, Win64, WinCE, and
  67 OS/2 platforms.
  68
  69 \item[\module{posixpath}]
  70 --- Implementation on \module{os.path} on \POSIX.
  71 \end{description}
  72
  73
  74 \section{Multimedia}
  75
  76 \begin{description}
  77 \item[\module{audiodev}]
  78 --- Platform-independent API for playing audio data.
  79
  80 \item[\module{sunaudio}]
  81 --- Interpret Sun audio headers (may become obsolete or a tool/demo).
  82
  83 \item[\module{toaiff}]
  84 --- Convert "arbitrary" sound files to AIFF files; should probably
  85 become a tool or demo.  Requires the external program \program{sox}.
  86 \end{description}
  87
  88
  89 \section{Obsolete \label{obsolete-modules}}
  90
  91 These modules are not normally available for import; additional work
  92 must be done to make them available.
  93
  94 Those which are written in Python will be installed into the directory
  95 \file{lib-old/} installed as part of the standard library.  To use
  96 these, the directory must be added to \code{sys.path}, possibly using
  97 \envvar{PYTHONPATH}.
  98
  99 Obsolete extension modules written in C are not built by default.
 100 Under \UNIX, these must be enabled by uncommenting the appropriate
 101 lines in \file{Modules/Setup} in the build tree and either rebuilding
 102 Python if the modules are statically linked, or building and
 103 installing the shared object if using dynamically-loaded extensions.
 104
 105 % XXX need Windows instructions!
 106
 107 \begin{description}
 108 \item[\module{addpack}]
 109 --- Alternate approach to packages.  Use the built-in package support
 110 instead.
 111
 112 \item[\module{cmp}]
 113 --- File comparison function.  Use the newer \refmodule{filecmp} instead.
 114
 115 \item[\module{cmpcache}]
 116 --- Caching version of the obsolete \module{cmp} module.  Use the
 117 newer \refmodule{filecmp} instead.
 118
 119 \item[\module{codehack}]
 120 --- Extract function name or line number from a function
 121 code object (these are now accessible as attributes:
 122 \member{co.co_name}, \member{func.func_name},
 123 \member{co.co_firstlineno}).
 124
 125 \item[\module{dircmp}]
 126 --- Class to build directory diff tools on (may become a demo or tool).
 127 \deprecated{2.0}{The \refmodule{filecmp} module replaces
 128 \module{dircmp}.}
 129
 130 \item[\module{dump}]
 131 --- Print python code that reconstructs a variable.
 132
 133 \item[\module{fmt}]
 134 --- Text formatting abstractions (too slow).
 135
 136 \item[\module{lockfile}]
 137 --- Wrapper around FCNTL file locking (use
 138 \function{fcntl.lockf()}/\function{flock()} instead; see \refmodule{fcntl}).
 139
 140 \item[\module{newdir}]
 141 --- New \function{dir()} function (the standard \function{dir()} is
 142 now just as good).
 143
 144 \item[\module{Para}]
 145 --- Helper for \module{fmt}.
 146
 147 \item[\module{poly}]
 148 --- Polynomials.
 149
 150 \item[\module{regex}]
 151 --- Emacs-style regular expression support; may still be used in some
 152 old code (extension module).  Refer to the
 153 \citetitle[http://www.python.org/doc/1.6/lib/module-regex.html]{Python
 154 1.6 Documentation} for documentation.
 155
 156 \item[\module{regsub}]
 157 --- Regular expression based string replacement utilities, for use
 158 with \module{regex} (extension module).  Refer to the
 159 \citetitle[http://www.python.org/doc/1.6/lib/module-regsub.html]{Python
 160 1.6 Documentation} for documentation.
 161
 162 \item[\module{tb}]
 163 --- Print tracebacks, with a dump of local variables (use
 164 \function{pdb.pm()} or \refmodule{traceback} instead).
 165
 166 \item[\module{timing}]
 167 --- Measure time intervals to high resolution (use
 168 \function{time.clock()} instead).  (This is an extension module.)
 169
 170 \item[\module{util}]
 171 --- Useful functions that don't fit elsewhere.
 172
 173 \item[\module{whatsound}]
 174 --- Recognize sound files; use \refmodule{sndhdr} instead.
 175
 176 \item[\module{zmod}]
 177 --- Compute properties of mathematical ``fields.''
 178 \end{description}
 179
 180
 181 The following modules are obsolete, but are likely to re-surface as
 182 tools or scripts:
 183
 184 \begin{description}
 185 \item[\module{find}]
 186 --- Find files matching pattern in directory tree.
 187
 188 \item[\module{grep}]
 189 --- \program{grep} implementation in Python.
 190
 191 \item[\module{packmail}]
 192 --- Create a self-unpacking \UNIX{} shell archive.
 193 \end{description}
 194
 195
 196 The following modules were documented in previous versions of this
 197 manual, but are now considered obsolete.  The source for the
 198 documentation is still available as part of the documentation source
 199 archive.
 200
 201 \begin{description}
 202 \item[\module{ni}]
 203 --- Import modules in ``packages.''  Basic package support is now
 204 built in.  The built-in support is very similar to what is provided in
 205 this module.
 206
 207 \item[\module{rand}]
 208 --- Old interface to the random number generator.
 209
 210 \item[\module{soundex}]
 211 --- Algorithm for collapsing names which sound similar to a shared
 212 key.  The specific algorithm doesn't seem to match any published
 213 algorithm.  (This is an extension module.)
 214 \end{description}
 215
 216
 217 \section{SGI-specific Extension modules}
 218
 219 The following are SGI specific, and may be out of touch with the
 220 current version of reality.
 221
 222 \begin{description}
 223 \item[\module{cl}]
 224 --- Interface to the SGI compression library.
 225
 226 \item[\module{sv}]
 227 --- Interface to the ``simple video'' board on SGI Indigo
 228 (obsolete hardware).
 229 \end{description}