Linux/Unix > Python Essential Reference, Second Edition > A. The Python Library > The Python Profiler | See All Titles

< BACK | Make Note | Bookmark | CONTINUE >

155117184014003188065099048180054212144238241179195140058238111161105094192221162198121240

### The Python Profiler

This section describes the Python profiler—a tool that can be used to analyze the runtime performance of a program.

#### `profile`

The `profile` module is used to collect profiling information.

    run(command [, filename])

Executes the contents of `command` using the `exec` statement under the profiler. `filename` is the name of a file in which raw profiling data is saved. If omitted, a report such as the following is printed to standard output:

    126 function calls (6 primitive calls) in 5.130 CPU seconds
    Ordered by: standard name
    ncalls   tottime   percall   cumtime   percall   filename:lineno(function)
         1     0.030     0.030     5.070     5.070   <string>:1(?)
     121/1     5.020     0.041     5.020     5.020   book.py:11(process)
         1     0.020     0.020     5.040     5.040   book.py:5(?)
         2     0.000     0.000     0.000     0.000   exceptions.py:101(_ _init_ _)
         1     0.060     0.060     5.130     5.130   profile:0(execfile('book.py'))
         0     0.000     0.000                       profile:0(profiler)

Different parts of the report generated by `run()` are interpreted as follows:

Section | Description
--- | ---
`primitive calls` | Number of nonrecursive function calls
`ncalls` | Total number of calls (including self-recursion)
`tottime` | Time spent in this function (not counting subfunctions)
`percall` | `tottime/ncalls`
`cumtime` | Total time spent in the function
`percall` | `cumtime/(primitive calls)`
`filename:lineno(function)` | Location and name of each function

When there are two numbers in the first column (for example, `"121/1"`), the latter is the number of primitive calls, and the former is the actual number of calls.

##### Notes

- Analysis of saved profile data is performed by the `pstats` module.

- To obtain accurate information, it may be necessary to calibrate the profiler. Please refer to http://www.python.org/doc/lib/profile.html for details.

#### `pstats`

The `pstats` module defines a class `Stats` that’s used to analyze the data saved by the `profile` module.

    Stats(filename)

Reads profiling data from `filename` —a file previously created by the `profile.run()` function. Returns a statistics object that can be used to print reports.

A statistics object `s` has the following methods:

    s.strip_dirs()

Removes leading path information from filenames.

    s.add(filename [, ...])

Accumulates additional profiling information into the current profile. `filename` is the name of a file containing data previously saved by `profile.run()`.

    s.sort_stats(key [, ...])

Sorts statistics according to a series of keys. Each key can be one of the following values:

Key Name | Description
--- | ---
`'calls'` | Call count
`'cumulative'` | Cumulative time
`'file'` | Filename
`'module'` | Filename
`'pcalls'` | Primitive call count
`'line'` | Line number
`'name'` | Function name
`'nfl'` | Name/file/line
`'stdname'` | Standard name
`'time'` | Internal time

Time values and call counts are sorted in descending order. Line numbers and filenames are sorted in ascending order.

    s.print_stats(restriction [, ...])

Prints a profile report to standard output. The order is the same as produced by the last `sort_stats()` method. The arguments are used to eliminate entries in the report. Each restriction can be an integer to select a maximum line count, a decimal to select a percentage of the lines, or a regular expression to pattern-match against the names that are printed.

    s.print_callers(restrictions [, ...])

Prints a list of all functions that called each function in the profile database. The ordering is identical to `print_stats()`. `restrictions` has the same meaning as for `print_stats()`.

    s.print_callees(restrictions [, ...])

Prints a list of a functions that were called by each function. `restrictions` has the same meaning as for `print_stats()`.

##### Note

- If the `pstats` module is run as a script, it launches an interactive profile statistics browser. Type `'help'` for a list of the available commands. This is a new Python 2.1 feature.

| Last updated on 3/28/2002 Python Essential Reference, Second Edition, © 2002 New Riders Publishing

< BACK | Make Note | Bookmark | CONTINUE >

© 2002, O'Reilly & Associates, Inc.