GNU Info

Info Node: (python2.1-lib.info)Reference Manual

(python2.1-lib.info)Reference Manual


Next: Limitations Prev: Deterministic Profiling Up: Python Profiler
Enter node , (file) or (file)node

Reference Manual
================

Python profiler

The primary entry point for the profiler is the global function
`profile.run()'.  It is typically used to create any profile
information.  The reports are formatted and printed using methods of
the class `pstats.Stats'.  The following is a description of all of
these standard entry points and functions.  For a more in-depth view of
some of the code, consider reading the later section on Profiler
Extensions, which includes discussion of how to derive "better"
profilers from the classes presented, or reading the source code for
these modules.

`run(string[, filename[, ...]])'
     This function takes a single argument that has can be passed to the
     `exec' statement, and an optional file name.  In all cases this
     routine attempts to `exec' its first argument, and gather profiling
     statistics from the execution. If no file name is present, then
     this function automatically prints a simple profiling report,
     sorted by the standard name string (file/line/function-name) that
     is presented in each line.  The following is a typical output from
     such a call:

                main()
                2706 function calls (2004 primitive calls) in 4.504 CPU seconds
          
          Ordered by: standard name
          
          ncalls  tottime  percall  cumtime  percall filename:lineno(function)
               2    0.006    0.003    0.953    0.477 pobject.py:75(save_objects)
            43/3    0.533    0.012    0.749    0.250 pobject.py:99(evaluate)
           ...

     The first line indicates that this profile was generated by the
     call:\ `profile.run('main()')', and hence the exec'ed string is
     `'main()''.  The second line indicates that 2706 calls were
     monitored.  Of those calls, 2004 were "primitive".  We define
     "primitive" to mean that the call was not induced via recursion.
     The next line: `Ordered by: standard name', indicates that the
     text string in the far right column was used to sort the output.
     The column headings include:

    `ncalls'
          for the number of calls,

    `tottime'
          for the total time spent in the given function (and excluding
          time made in calls to sub-functions),

    `percall'
          is the quotient of `tottime' divided by `ncalls'

    `cumtime'
          is the total time spent in this and all subfunctions (i.e.,
          from invocation till exit). This figure is accurate _even_
          for recursive functions.

    `percall'
          is the quotient of `cumtime' divided by primitive calls

    `filename:lineno(function)'
          provides the respective data of each function

     When there are two numbers in the first column (e.g.: `43/3'),
     then the latter is the number of primitive calls, and the former is
     the actual number of calls.  Note that when the function does not
     recurse, these two values are the same, and only the single figure
     is printed.

Analysis of the profiler data is done using this class from the
`pstats' module:

`Stats(filename[, ...])'
     This class constructor creates an instance of a "statistics object"
     from a FILENAME (or set of filenames).  `Stats' objects are
     manipulated by methods, in order to print useful reports.

     The file selected by the above constructor must have been created
     by the corresponding version of `profile'.  To be specific, there
     is _no_ file compatibility guaranteed with future versions of this
     profiler, and there is no compatibility with files produced by
     other profilers (e.g., the old system profiler).

     If several files are provided, all the statistics for identical
     functions will be coalesced, so that an overall view of several
     processes can be considered in a single report.  If additional
     files need to be combined with data in an existing `Stats' object,
     the `add()' method can be used.

Stats Class

automatically generated by info2www version 1.2.2.9