\end{description}
-\section{Instant Users Manual}
+\section{Instant Users Manual \label{profile-instant}}
This section is provided for users that ``don't want to read the
manual.'' It provides a very brief overview, and allows a user to
import profile
profile.run('foo()')
\end{verbatim}
-%
+
The above action would cause \samp{foo()} to be run, and a series of
informative lines (the profile) to be printed. The above approach is
most useful when working with the interpreter. If you would like to
import profile
profile.run('foo()', 'fooprof')
\end{verbatim}
-%
+
The file \file{profile.py} can also be invoked as
a script to profile another script. For example:
import pstats
p = pstats.Stats('fooprof')
\end{verbatim}
-%
+
The class \class{Stats} (the above code just created an instance of
this class) has a variety of methods for manipulating and printing the
data that was just read into \samp{p}. When you ran
\begin{verbatim}
p.strip_dirs().sort_stats(-1).print_stats()
\end{verbatim}
-%
+
The first method removed the extraneous path from all the module
names. The second method sorted all the entries according to the
standard module/line/name string that is printed (this is to comply
p.sort_stats('name')
p.print_stats()
\end{verbatim}
-%
+
The first call will actually sort the list by function name, and the
second call will print out the statistics. The following are some
interesting calls to experiment with:
\begin{verbatim}
p.sort_stats('cumulative').print_stats(10)
\end{verbatim}
-%
+
This sorts the profile by cumulative time in a function, and then only
prints the ten most significant lines. If you want to understand what
algorithms are taking time, the above line is what you would use.
\begin{verbatim}
p.sort_stats('time').print_stats(10)
\end{verbatim}
-%
+
to sort according to time spent within each function, and then print
the statistics for the top ten functions.
\begin{verbatim}
p.sort_stats('file').print_stats('__init__')
\end{verbatim}
-%
+
This will sort all the statistics by file name, and then print out
statistics for only the class init methods ('cause they are spelled
with \samp{__init__} in them). As one final example, you could try:
\begin{verbatim}
p.sort_stats('time', 'cum').print_stats(.5, 'init')
\end{verbatim}
-%
+
This line sorts statistics with a primary key of time, and a secondary
key of cumulative time, and then prints out some of the statistics.
To be specific, the list is first culled down to 50\% (re: \samp{.5})
p.print_callees()
p.add('fooprof')
\end{verbatim}
-%
+
\section{What Is Deterministic Profiling?}
\nodename{Deterministic Profiling}
\section{Reference Manual}
-\declaremodule{standard}{profile}
-\modulesynopsis{None}
+\declaremodule{standard}{profile}
+\modulesynopsis{Python profiler}
\module{pstats} module:
% now switch modules....
+% (This \stmodindex use may be hard to change ;-( )
\stmodindex{pstats}
\begin{classdesc}{Stats}{filename\optional{, ...}}
\end{classdesc}
-\subsection{The \module{Stats} Class}
+\subsection{The \class{Stats} Class \label{profile-stats}}
-\setindexsubitem{(Stats method)}
+\class{Stats} objects have the following methods:
-\begin{methoddesc}{strip_dirs}{}
+\begin{methoddesc}[Stats]{strip_dirs}{}
This method for the \class{Stats} class removes all leading path
information from file names. It is very useful in reducing the size
of the printout to fit within (close to) 80 columns. This method
\end{methoddesc}
-\begin{methoddesc}{add}{filename\optional{, ...}}
+\begin{methoddesc}[Stats]{add}{filename\optional{, ...}}
This method of the \class{Stats} class accumulates additional
profiling information into the current profiling object. Its
arguments should refer to filenames created by the corresponding
single function statistics.
\end{methoddesc}
-\begin{methoddesc}{sort_stats}{key\optional{, ...}}
+\begin{methoddesc}[Stats]{sort_stats}{key\optional{, ...}}
This method modifies the \class{Stats} object by sorting it according
to the supplied criteria. The argument is typically a string
identifying the basis of a sort (example: \code{'time'} or
\end{methoddesc}
-\begin{methoddesc}{reverse_order}{}
+\begin{methoddesc}[Stats]{reverse_order}{}
This method for the \class{Stats} class reverses the ordering of the basic
list within the object. This method is provided primarily for
compatibility with the old profiler. Its utility is questionable
the sort key of choice.
\end{methoddesc}
-\begin{methoddesc}{print_stats}{restriction\optional{, ...}}
+\begin{methoddesc}[Stats]{print_stats}{restriction\optional{, ...}}
This method for the \class{Stats} class prints out a report as described
in the \function{profile.run()} definition.
\end{methoddesc}
-\begin{methoddesc}{print_callers}{restrictions\optional{, ...}}
+\begin{methoddesc}[Stats]{print_callers}{restrictions\optional{, ...}}
This method for the \class{Stats} class prints a list of all functions
that called each function in the profiled database. The ordering is
identical to that provided by \method{print_stats()}, and the definition
is the cumulative time spent in the function at the right.
\end{methoddesc}
-\begin{methoddesc}{print_callees}{restrictions\optional{, ...}}
+\begin{methoddesc}[Stats]{print_callees}{restrictions\optional{, ...}}
This method for the \class{Stats} class prints a list of all function
that were called by the indicated function. Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and
ordering are identical to the \method{print_callers()} method.
\end{methoddesc}
-\begin{methoddesc}{ignore}{}
+\begin{methoddesc}[Stats]{ignore}{}
\deprecated{1.5.1}{This is not needed in modern versions of
Python.\footnote{
This was once necessary, when Python would print any unused expression
\end{methoddesc}
-\section{Limitations}
+\section{Limitations \label{profile-limits}}
There are two fundamental limitations on this profiler. The first is
that it relies on the Python interpreter to dispatch \dfn{call},
After the profiler is calibrated, it will be more accurate (in a least
square sense), but it will sometimes produce negative numbers (when
call counts are exceptionally low, and the gods of probability work
-against you :-). ) Do \emph{NOT} be alarmed by negative numbers in
+against you :-). ) Do \emph{not} be alarmed by negative numbers in
the profile. They should \emph{only} appear if you have calibrated
your profiler, and the results are actually better than without
calibration.
-\section{Calibration}
+\section{Calibration \label{profile-calibration}}
The profiler class has a hard coded constant that is added to each
event handling time to compensate for the overhead of calling the time
constant :-).
-\subsection{OldProfile Class}
+\subsection{OldProfile Class \label{profile-old}}
The following derived profiler simulates the old style profiler,
providing errant results on recursive functions. The reason for the
self.stats[nor_func] = nc, nc, tt, ct, nor_callers
\end{verbatim}
-\subsection{HotProfile Class}
+\subsection{HotProfile Class \label{profile-HotProfile}}
This profiler is the fastest derived profile example. It does not
calculate caller-callee relationships, and does not calculate
projects / thirdparty / Python / cpython.git / commitdiff
