<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>10.5.1 The Stats Class </TITLE>
<META NAME="description" CONTENT="10.5.1 The Stats Class ">
<META NAME="keywords" CONTENT="lib">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="lib.css">
<LINK REL="previous" HREF="module-profile.html">
<LINK REL="up" HREF="module-profile.html">
<LINK REL="next" HREF="profile-limits.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="profile-limits.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="module-profile.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="module-profile.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="profile-limits.html">10.6 Limitations</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="module-profile.html">10.5 Reference Manual</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="module-profile.html">10.5 Reference Manual</A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0012510000000000000000"></A>
<BR>
10.5.1 The <tt class=class>Stats</tt> Class 
</H2>

<P>
<tt class=class>Stats</tt> objects have the following methods:

<P>
<dl><dt><b><a name="l2h-1571"><tt class=method>strip_dirs</tt></a></b> ()
<dd>
This method for the <tt class=class>Stats</tt> 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
modifies the object, and the stripped information is lost.  After
performing a strip operation, the object is considered to have its
entries in a ``random'' order, as it was just after object
initialization and loading.  If <tt class=method>strip_dirs()</tt> causes two
function names to be indistinguishable (i.e., they are on the same
line of the same filename, and have the same function name), then the
statistics for these two entries are accumulated into a single entry.
</dl>

<P>
<dl><dt><b><a name="l2h-1572"><tt class=method>add</tt></a></b> (<var>filename</var><big>[</big><var>, ...</var><big>]</big>)
<dd>
This method of the <tt class=class>Stats</tt> class accumulates additional
profiling information into the current profiling object.  Its
arguments should refer to filenames created by the corresponding
version of <tt class=function>profile.run()</tt>.  Statistics for identically named
(re: file, line, name) functions are automatically accumulated into
single function statistics.
</dl>

<P>
<dl><dt><b><a name="l2h-1573"><tt class=method>sort_stats</tt></a></b> (<var>key</var><big>[</big><var>, ...</var><big>]</big>)
<dd>
This method modifies the <tt class=class>Stats</tt> object by sorting it according
to the supplied criteria.  The argument is typically a string
identifying the basis of a sort (example: <tt>'time'</tt> or
<tt>'name'</tt>).

<P>
When more than one key is provided, then additional keys are used as
secondary criteria when the there is equality in all keys selected
before them.  For example, "<tt class=samp>sort_stats('name', 'file')</tt>" will sort
all the entries according to their function name, and resolve all ties
(identical function names) by sorting by file name.

<P>
Abbreviations can be used for any key names, as long as the
abbreviation is unambiguous.  The following are the keys currently
defined: 

<P>
<table border align=center>
  <thead>
    <tr bgcolor="#99CCFF">
      <th align=left><b>Valid Arg</b></th>
      <th align=left><b>Meaning</b></th>
    </thead>
  <tbody valign=baseline>
    <tr><td valign=baseline><code>'calls'</code></td>
        <td>call count&nbsp;</td>
    <tr><td valign=baseline><code>'cumulative'</code></td>
        <td>cumulative time&nbsp;</td>
    <tr><td valign=baseline><code>'file'</code></td>
        <td>file name&nbsp;</td>
    <tr><td valign=baseline><code>'module'</code></td>
        <td>file name&nbsp;</td>
    <tr><td valign=baseline><code>'pcalls'</code></td>
        <td>primitive call count&nbsp;</td>
    <tr><td valign=baseline><code>'line'</code></td>
        <td>line number&nbsp;</td>
    <tr><td valign=baseline><code>'name'</code></td>
        <td>function name&nbsp;</td>
    <tr><td valign=baseline><code>'nfl'</code></td>
        <td>name/file/line&nbsp;</td>
    <tr><td valign=baseline><code>'stdname'</code></td>
        <td>standard name&nbsp;</td>
    <tr><td valign=baseline><code>'time'</code></td>
        <td>internal time&nbsp;</td></tbody>
</table>

<P>
Note that all sorts on statistics are in descending order (placing
most time consuming items first), where as name, file, and line number
searches are in ascending order (i.e., alphabetical). The subtle
distinction between <tt>'nfl'</tt> and <tt>'stdname'</tt> is that the
standard name is a sort of the name as printed, which means that the
embedded line numbers get compared in an odd way.  For example, lines
3, 20, and 40 would (if the file names were the same) appear in the
string order 20, 3 and 40.  In contrast, <tt>'nfl'</tt> does a numeric
compare of the line numbers.  In fact, <tt>sort_stats('nfl')</tt> is the
same as <tt>sort_stats('name', 'file', 'line')</tt>.

<P>
For compatibility with the old profiler, the numeric arguments
<tt>-1</tt>, <tt>0</tt>, <tt>1</tt>, and <tt>2</tt> are permitted.  They are
interpreted as <tt>'stdname'</tt>, <tt>'calls'</tt>, <tt>'time'</tt>, and
<tt>'cumulative'</tt> respectively.  If this old style format (numeric)
is used, only one sort key (the numeric key) will be used, and
additional arguments will be silently ignored.
</dl>

<P>
<dl><dt><b><a name="l2h-1574"><tt class=method>reverse_order</tt></a></b> ()
<dd>
This method for the <tt class=class>Stats</tt> 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
now that ascending vs descending order is properly selected based on
the sort key of choice.
</dl>

<P>
<dl><dt><b><a name="l2h-1575"><tt class=method>print_stats</tt></a></b> (<var>restriction</var><big>[</big><var>, ...</var><big>]</big>)
<dd>
This method for the <tt class=class>Stats</tt> class prints out a report as described
in the <tt class=function>profile.run()</tt> definition.

<P>
The order of the printing is based on the last <tt class=method>sort_stats()</tt>
operation done on the object (subject to caveats in <tt class=method>add()</tt> and
<tt class=method>strip_dirs()</tt>.

<P>
The arguments provided (if any) can be used to limit the list down to
the significant entries.  Initially, the list is taken to be the
complete set of profiled functions.  Each restriction is either an
integer (to select a count of lines), or a decimal fraction between
0.0 and 1.0 inclusive (to select a percentage of lines), or a regular
expression (to pattern match the standard name that is printed; as of
Python 1.5b1, this uses the Perl-style regular expression syntax
defined by the <tt class=module><a href="module-re.html">re</a></tt> module).  If several restrictions are
provided, then they are applied sequentially.  For example:

<P>
<dl><dd><pre class=verbatim>
print_stats(.1, 'foo:')
</pre></dl>

<P>
would first limit the printing to first 10% of list, and then only
print functions that were part of filename "<tt class=samp>.*foo:</tt>".  In
contrast, the command:

<P>
<dl><dd><pre class=verbatim>
print_stats('foo:', .1)
</pre></dl>

<P>
would limit the list to all functions having file names "<tt class=samp>.*foo:</tt>",
and then proceed to only print the first 10% of them.
</dl>

<P>
<dl><dt><b><a name="l2h-1576"><tt class=method>print_callers</tt></a></b> (<var>restrictions</var><big>[</big><var>, ...</var><big>]</big>)
<dd>
This method for the <tt class=class>Stats</tt> class prints a list of all functions
that called each function in the profiled database.  The ordering is
identical to that provided by <tt class=method>print_stats()</tt>, and the definition
of the restricting argument is also identical.  For convenience, a
number is shown in parentheses after each caller to show how many
times this specific call was made.  A second non-parenthesized number
is the cumulative time spent in the function at the right.
</dl>

<P>
<dl><dt><b><a name="l2h-1577"><tt class=method>print_callees</tt></a></b> (<var>restrictions</var><big>[</big><var>, ...</var><big>]</big>)
<dd>
This method for the <tt class=class>Stats</tt> 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 <tt class=method>print_callers()</tt> method.
</dl>

<P>
<dl><dt><b><a name="l2h-1578"><tt class=method>ignore</tt></a></b> ()
<dd>
<b>Deprecated since release 1.5.1.</b>
This is not needed in modern versions of
Python.<A NAME="tex2html16"
 HREF="#foot19833"><SUP>10.2</SUP></A><p>
</dl>

<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot19833">...
Python.</A><A NAME="foot19833"
 HREF="profile-stats.html#tex2html16"><SUP>10.2</SUP></A>
<DD>
  This was once necessary, when Python would print any unused expression
  result that was not <tt>None</tt>.  The method is still defined for
  backward compatibility.

</DL><p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="profile-limits.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="module-profile.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="module-profile.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="profile-limits.html">10.6 Limitations</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="module-profile.html">10.5 Reference Manual</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="module-profile.html">10.5 Reference Manual</A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
