Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

markup fixes, cleanup

This commit is contained in:
Fred Drake 2006-04-26 05:15:41 +00:00
parent d845e53b5b
commit 2afbf96f53
2 changed files with 67 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Doc/Makefile.deps
View File

@ -180,6 +180,7 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
lib/libprofile.tex \ lib/libprofile.tex \
lib/libhotshot.tex \ lib/libhotshot.tex \
lib/libtimeit.tex \ lib/libtimeit.tex \
lib/libtrace.tex \
lib/libcgi.tex \ lib/libcgi.tex \
lib/libcgitb.tex \ lib/libcgitb.tex \
lib/liburllib.tex \ lib/liburllib.tex \

104
Doc/lib/libtrace.tex
View File

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