<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"prev" href=
"module-profile.html" />
<link rel=
"parent" href=
"module-profile.html" />
<link rel=
"next" href=
"profile-limits.html" />
<meta name='aesop' content='information'
/>
<title>10.5.1 The Stats Class
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"10.5 Reference Manual"
href=
"module-profile.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"10.5 Reference Manual"
href=
"module-profile.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"10.6 Limitations"
href=
"profile-limits.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-profile.html">10.5 Reference Manual
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-profile.html">10.5 Reference Manual
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"profile-limits.html">10.6 Limitations
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION0012510000000000000000"></A><A NAME=
"profile-stats"></A>
10.5.1 The
<tt class=
"class">Stats
</tt> Class
<tt class=
"class">Stats
</tt> objects have the following methods:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3112' xml:id='l2h-
3112'
class=
"method">strip_dirs
</tt></b>(
</nobr></td>
<td><var></var>)
</td></tr></table></dt>
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 (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><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3113' xml:id='l2h-
3113'
class=
"method">add
</tt></b>(
</nobr></td>
<td><var>filename
</var><big>[
</big><var>, ...
</var><big>]
</big><var></var>)
</td></tr></table></dt>
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><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3114' xml:id='l2h-
3114'
class=
"method">dump_stats
</tt></b>(
</nobr></td>
<td><var>filename
</var>)
</td></tr></table></dt>
Save the data loaded into the
<tt class=
"class">Stats
</tt> object to a file named
<var>filename
</var>. The file is created if it does not exist, and is
overwritten if it already exists. This is equivalent to the method of
the same name on the
<tt class=
"class">profile.Profile
</tt> class.
<span class=
"versionnote">New in version
2.3.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3115' xml:id='l2h-
3115'
class=
"method">sort_stats
</tt></b>(
</nobr></td>
<td><var>key
</var><big>[
</big><var>, ...
</var><big>]
</big><var></var>)
</td></tr></table></dt>
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:
<code>'time'
</code> or
When more than one key is provided, then additional keys are used as
secondary criteria when there is equality in all keys selected
before them. For example,
<code>sort_stats('name', 'file')
</code> will sort
all the entries according to their function name, and resolve all ties
(identical function names) by sorting by file name.
Abbreviations can be used for any key names, as long as the
abbreviation is unambiguous. The following are the keys currently
<div class=
"center"><table class=
"realtable">
<th class=
"left" >Valid Arg
</th>
<th class=
"left" >Meaning
</th>
<tr><td class=
"left" valign=
"baseline"><code>'calls'
</code></td>
<td class=
"left" >call count
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'cumulative'
</code></td>
<td class=
"left" >cumulative time
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'file'
</code></td>
<td class=
"left" >file name
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'module'
</code></td>
<td class=
"left" >file name
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'pcalls'
</code></td>
<td class=
"left" >primitive call count
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'line'
</code></td>
<td class=
"left" >line number
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'name'
</code></td>
<td class=
"left" >function name
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'nfl'
</code></td>
<td class=
"left" >name/file/line
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'stdname'
</code></td>
<td class=
"left" >standard name
</td></tr>
<tr><td class=
"left" valign=
"baseline"><code>'time'
</code></td>
<td class=
"left" >internal time
</td></tr></tbody>
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 (alphabetical). The subtle
distinction between
<code>'nfl'
</code> and
<code>'stdname'
</code> 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,
<code>'nfl'
</code> does a numeric
compare of the line numbers. In fact,
<code>sort_stats('nfl')
</code> is the
same as
<code>sort_stats('name', 'file', 'line')
</code>.
For compatibility with the old profiler, the numeric arguments
<code>-
1</code>,
<code>0</code>,
<code>1</code>, and
<code>2</code> are permitted. They are
interpreted as
<code>'stdname'
</code>,
<code>'calls'
</code>,
<code>'time'
</code>, and
<code>'cumulative'
</code> 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><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3116' xml:id='l2h-
3116'
class=
"method">reverse_order
</tt></b>(
</nobr></td>
<td><var></var>)
</td></tr></table></dt>
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
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3117' xml:id='l2h-
3117'
class=
"method">print_stats
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>restriction, ...
</var><big>]
</big><var></var>)
</td></tr></table></dt>
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.
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>).
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:
<div class=
"verbatim"><pre>
would first limit the printing to first
10% of list, and then only
print functions that were part of filename
<span class=
"file">.*foo:
</span>. In
<div class=
"verbatim"><pre>
would limit the list to all functions having file names
<span class=
"file">.*foo:
</span>,
and then proceed to only print the first
10% of them.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3118' xml:id='l2h-
3118'
class=
"method">print_callers
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>restriction, ...
</var><big>]
</big><var></var>)
</td></tr></table></dt>
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><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3119' xml:id='l2h-
3119'
class=
"method">print_callees
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>restriction, ...
</var><big>]
</big><var></var>)
</td></tr></table></dt>
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><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3120' xml:id='l2h-
3120'
class=
"method">ignore
</tt></b>(
</nobr></td>
<td><var></var>)
</td></tr></table></dt>
<div class=
"versionnote"><b>Deprecated since release
1.5.1.
</b>
This is not needed in modern versions of
Python.
<A NAME=
"tex2html51" HREF=
"#foot46380"><SUP>10.2</SUP></A></div><p></p>
<BR><HR><H4>Footnotes
</H4>
<DT><A NAME=
"foot46380">...
href=
"profile-stats.html#tex2html51"><SUP>10.2</SUP></A></DT>
This was once necessary, when Python would print any unused expression
result that was not
<code>None
</code>. The method is still defined for
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"10.5 Reference Manual"
href=
"module-profile.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"10.5 Reference Manual"
href=
"module-profile.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"10.6 Limitations"
href=
"profile-limits.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-profile.html">10.5 Reference Manual
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-profile.html">10.5 Reference Manual
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"profile-limits.html">10.6 Limitations
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-SAM / blob