GNU Info
(python2.1-lib.info)Stats Class
The `Stats' Class
-----------------
`Stats' objects have the following methods:
`strip_dirs()'
This method for the `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 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 `strip_dirs()' 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.
`add(filename[, ...])'
This method of the `Stats' class accumulates additional profiling
information into the current profiling object. Its arguments
should refer to filenames created by the corresponding version of
`profile.run()'. Statistics for identically named (re: file,
line, name) functions are automatically accumulated into single
function statistics.
`sort_stats(key[, ...])'
This method modifies the `Stats' object by sorting it according to
the supplied criteria. The argument is typically a string
identifying the basis of a sort (example: `'time'' or `'name'').
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, `sort_stats('name', 'file')'
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
defined:
Valid Arg Meaning
------ -----
'calls' call count
'cumulative' cumulative time
'file' file name
'module' file name
'pcalls' primitive call count
'line' line number
'name' function name
'nfl' name/file/line
'stdname' standard name
'time' internal time
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 `'nfl'' and `'stdname'' 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,
`'nfl'' does a numeric compare of the line numbers. In fact,
`sort_stats('nfl')' is the same as `sort_stats('name', 'file',
'line')'.
For compatibility with the old profiler, the numeric arguments
`-1', `0', `1', and `2' are permitted. They are interpreted as
`'stdname'', `'calls'', `'time'', and `'cumulative'' 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.
`reverse_order()'
This method for the `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 now that ascending vs descending order is properly
selected based on the sort key of choice.
`print_stats([restriction, ...])'
This method for the `Stats' class prints out a report as described
in the `profile.run()' definition.
The order of the printing is based on the last `sort_stats()'
operation done on the object (subject to caveats in `add()' and
`strip_dirs()'.
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 `re' module). If several
restrictions are provided, then they are applied sequentially.
For example:
print_stats(.1, 'foo:')
would first limit the printing to first 10% of list, and then only
print functions that were part of filename `.*foo:'. In contrast,
the command:
print_stats('foo:', .1)
would limit the list to all functions having file names `.*foo:',
and then proceed to only print the first 10% of them.
`print_callers([restriction, ...])'
This method for the `Stats' class prints a list of all functions
that called each function in the profiled database. The ordering
is identical to that provided by `print_stats()', 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.
`print_callees([restriction, ...])'
This method for the `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 `print_callers()'
method.
`ignore()'
_This is deprecated in Python 1.5.1. This is not needed in modern
versions of Python.(1)_
---------- Footnotes ----------
(1) This was once necessary, when Python would print any unused
expression result that was not `None'. The method is still defined for
backward compatibility.
automatically generated by info2www version 1.2.2.9