[Python-checkins] r45671 - python/trunk/Doc/lib/lib.tex python/trunk/Doc/lib/libtrace.tex (original) (raw)
skip.montanaro python-checkins at python.org
Sun Apr 23 21:14:28 CEST 2006
- Previous message: [Python-checkins] r45670 - python/trunk/Lib/optparse.py
- Next message: [Python-checkins] r45672 - python/trunk/Doc/lib/libtrace.tex
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Author: skip.montanaro Date: Sun Apr 23 21:14:27 2006 New Revision: 45671
Added: python/trunk/Doc/lib/libtrace.tex (contents, props changed) Modified: python/trunk/Doc/lib/lib.tex Log: first cut at trace module doc
Modified: python/trunk/Doc/lib/lib.tex
--- python/trunk/Doc/lib/lib.tex (original) +++ python/trunk/Doc/lib/lib.tex Sun Apr 23 21:14:27 2006 @@ -360,7 +360,7 @@ \input{libprofile} % The Python Profiler \input{libhotshot} % unmaintained C profiler \input{libtimeit}
+\input{libtrace}
% ============= % PYTHON ENGINE
Added: python/trunk/Doc/lib/libtrace.tex
--- (empty file) +++ python/trunk/Doc/lib/libtrace.tex Sun Apr 23 21:14:27 2006 @@ -0,0 +1,95 @@ +\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}
- +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 somefile.py.
- +\subsection{Command Line Arguments}
- +\begin{description} +\item[--trace, -t]{Display lines as they are executed.} +\item[--count, -c]{Produce a set of annotated listing files upon program +completion that shows how many times each statement was executed.} +\item[--report, -r]{Produce an annotated list from an earlier program run that +used the \code{--count} and \code{--file} arguments.} +\item[--no-report, -R]{Do not generate annotated listings. This is useful +if you intend to make several runs with \code{--count} then produce a single +set of annotated listings at the end.} +\item[--listfuncs, -l]{List the functions executed by running the program.} +\item[--trackcalls, -T]{Generate calling relationships exposed by running the +program.} +\item[--file, -f]{Name a file containing (or to contain) counts.} +\item[--coverdir, -C]{Name a directory in which to save annotated listing +files.} +\item[--missing, -m]{When generating annotated listings, mark lines which +were not executed with \code{>>>>>>}.} +\item[--summary -s]{When using \code{--count} or \code{--report}, write a +brief summary to stdout for each file processed.} +\item[--ignore-module]{Ignore the named module and its submodules (if it is +a package). May be given multiple times.} +\item[--ignore-dir]{Ignore all modules and packages in the named directory +and subdirectories. May be given multiple times.} +\end{description}
- +\subsection{Program Usage}
- +\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 \code{cmd} under control of the Trace object with the current tracing +parameters. +\end{methoddesc}
- +\begin{methoddesc}[Trace]{run}{cmd\optional{,globals=None\optional{,locals=None}}} +Run \code{cmd} under control of the Trace object with the current tracing +parameters in the defined global and local environments. If not defined, +\code{globals} and \code{locals} default to empty dictionaries. +\end{methoddesc}
- +\begin{methoddesc}[Trace]{runfunc}{func, *args, **kwds} +Call \code{function} with the given arguments under control of the Trace +object with the current tracing parameters. +\end{methoddesc}
- +\subsubsection{Example}
- +\begin{verbatim} +# create a Trace object, telling it what to ignore, and whether to
+# do tracing or line-counting or both. +trace = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,], trace=0, + count=1) +# run the new command using the given trace +trace.run('main()') +# make a report, telling it where you want output +r = trace.results() +r.write_results(show_missing=True) +\end{verbatim}
- Previous message: [Python-checkins] r45670 - python/trunk/Lib/optparse.py
- Next message: [Python-checkins] r45672 - python/trunk/Doc/lib/libtrace.tex
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]