1 files changed, 125 insertions, 0 deletions
diff --git a/Doc/lib/libtrace.tex b/Doc/lib/libtrace.tex
new file mode 100644
index 0000000..2465aac
--- /dev/null
+++ b/Doc/lib/libtrace.tex
@@ -0,0 +1,125 @@
+\section{\module{trace} ---
+         Trace or track Python statement execution}
+
+\declaremodule{standard}{trace}
+\modulesynopsis{Trace or track Python statement execution.}
+
+The \module{trace} module allows you to trace program execution, generate
+annotated statement coverage listings, print caller/callee relationships and
+list functions executed during a program run.  It can be used in another
+program or from the command line.
+
+\subsection{Command Line Usage\label{trace-cli}}
+
+The \module{trace} module can be invoked from the command line.  It can be
+as simple as
+
+\begin{verbatim}
+python -m trace --count somefile.py ...
+\end{verbatim}
+
+The above will generate annotated listings of all Python modules imported
+during the execution of \file{somefile.py}.
+
+The following command-line arguments are supported:
+
+\begin{description}
+\item[\longprogramopt{trace}, \programopt{-t}]
+Display lines as they are executed.
+
+\item[\longprogramopt{count}, \programopt{-c}]
+Produce a set of  annotated listing files upon program
+completion that shows how many times each statement was executed.
+
+\item[\longprogramopt{report}, \programopt{-r}]
+Produce an annotated list from an earlier program run that
+used the \longprogramopt{count} and \longprogramopt{file} arguments.
+
+\item[\longprogramopt{no-report}, \programopt{-R}]
+Do not generate annotated listings.  This is useful if you intend to make
+several runs with \longprogramopt{count} then produce a single set
+of annotated listings at the end.
+
+\item[\longprogramopt{listfuncs}, \programopt{-l}]
+List the functions executed by running the program.
+
+\item[\longprogramopt{trackcalls}, \programopt{-T}]
+Generate calling relationships exposed by running the program.
+
+\item[\longprogramopt{file}, \programopt{-f}]
+Name a file containing (or to contain) counts.
+
+\item[\longprogramopt{coverdir}, \programopt{-C}]
+Name a directory in which to save annotated listing files.
+
+\item[\longprogramopt{missing}, \programopt{-m}]
+When generating annotated listings, mark lines which
+were not executed with `\code{>>>>>>}'.
+
+\item[\longprogramopt{summary}, \programopt{-s}]
+When using \longprogramopt{count} or \longprogramopt{report}, write a
+brief summary to stdout for each file processed.
+
+\item[\longprogramopt{ignore-module}]
+Ignore the named module and its submodules (if it is
+a package).  May be given multiple times.
+
+\item[\longprogramopt{ignore-dir}]
+Ignore all modules and packages in the named directory
+and subdirectories.  May be given multiple times.
+\end{description}
+
+\subsection{Programming Interface\label{trace-api}}
+
+\begin{classdesc}{Trace}{\optional{count=1\optional{, trace=1\optional{,
+                         countfuncs=0\optional{, countcallers=0\optional{,
+                         ignoremods=()\optional{, ignoredirs=()\optional{,
+                         infile=None\optional{, outfile=None}}}}}}}}}
+Create an object to trace execution of a single statement or expression.
+All parameters are optional.  \var{count} enables counting of line numbers.
+\var{trace} enables line execution tracing.  \var{countfuncs} enables
+listing of the functions called during the run.  \var{countcallers} enables
+call relationship tracking.  \var{ignoremods} is a list of modules or
+packages to ignore.  \var{ignoredirs} is a list of directories whose modules
+or packages should be ignored.  \var{infile} is the file from which to read
+stored count information.  \var{outfile} is a file in which to write updated
+count information.
+\end{classdesc}
+
+\begin{methoddesc}[Trace]{run}{cmd}
+Run \var{cmd} under control of the Trace object with the current tracing
+parameters.
+\end{methoddesc}
+
+\begin{methoddesc}[Trace]{runctx}{cmd\optional{, globals=None\optional{,
+                                  locals=None}}}
+Run \var{cmd} under control of the Trace object with the current tracing
+parameters in the defined global and local environments.  If not defined,
+\var{globals} and \var{locals} default to empty dictionaries.
+\end{methoddesc}
+
+\begin{methoddesc}[Trace]{runfunc}{func, *args, **kwds}
+Call \var{func} with the given arguments under control of the
+\class{Trace} object with the current tracing parameters.
+\end{methoddesc}
+
+This is a simple example showing the use of this module:
+
+\begin{verbatim}
+import sys
+import trace
+
+# create a Trace object, telling it what to ignore, and whether to
+# do tracing or line-counting or both.
+tracer = trace.Trace(
+    ignoredirs=[sys.prefix, sys.exec_prefix],
+    trace=0,
+    count=1)
+
+# run the new command using the given tracer
+tracer.run('main()')
+
+# make a report, placing output in /tmp
+r = tracer.results()
+r.write_results(show_missing=True, coverdir="/tmp")
+\end{verbatim}