`!pstats` --- Statistics for profilers

Source code: Lib/pstats.py

The !pstats module provides tools for reading, manipulating, and displaying profiling statistics generated by Python's profilers. It reads output from both profiling.tracing (deterministic profiler) and profiling.sampling (statistical profiler).

Reading and displaying profile data

The Stats class is the primary interface for working with profile data. It can read statistics from files or directly from a ~profiling.tracing.Profile object.

Load statistics from a file and print a basic report:

import pstats

p = pstats.Stats('profile_output.prof')
p.print_stats()

The Stats object provides methods for sorting and filtering the data before printing. For example, to see the ten functions with the highest cumulative time:

from pstats import SortKey

p = pstats.Stats('profile_output.prof')
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

Working with statistics

The Stats class supports method chaining, making it convenient to perform multiple operations:

p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()

The ~Stats.strip_dirs method removes directory paths from filenames, making the output more compact. The ~Stats.sort_stats method accepts various keys to control the sort order.

Different sort keys highlight different aspects of performance:

from pstats import SortKey

# Functions that consume the most cumulative time
p.sort_stats(SortKey.CUMULATIVE).print_stats(10)

# Functions that consume the most time in their own code
p.sort_stats(SortKey.TIME).print_stats(10)

# Functions sorted by name
p.sort_stats(SortKey.NAME).print_stats()

Filtering output

The ~Stats.print_stats method accepts restrictions that filter which functions are displayed. Restrictions can be integers (limiting the count), floats between 0 and 1 (selecting a percentage), or strings (matching function names via regular expression).

Print only the top 10%:

p.print_stats(.1)

Print only functions whose names contain "init":

p.print_stats('init')

Combine restrictions (they apply sequentially):

# Top 10%, then only those containing "init"
p.print_stats(.1, 'init')

# Functions in files matching "foo:", limited to top 50%
p.sort_stats(SortKey.FILENAME).print_stats('foo:', .5)

Analyzing call relationships

The ~Stats.print_callers method shows which functions called each displayed function:

p.print_callers()

The ~Stats.print_callees method shows the opposite relationship, listing which functions each displayed function called:

p.print_callees()

Both methods accept the same restriction arguments as ~Stats.print_stats.

Combining multiple profiles

Statistics from multiple profiling runs can be combined into a single Stats object:

# Load multiple files at once
p = pstats.Stats('run1.prof', 'run2.prof', 'run3.prof')

# Or add files incrementally
p = pstats.Stats('run1.prof')
p.add('run2.prof')
p.add('run3.prof')

When files are combined, statistics for identical functions (same file, line, and name) are accumulated, giving an aggregate view across all profiling runs.

The !Stats class

from pstats import SortKey
p.sort_stats(SortKey.CUMULATIVE)

print_stats(.1, 'foo:')

Command-line interface

The !pstats module can be invoked as a script to interactively browse profile data:

python -m pstats profile_output.prof

This opens a line-oriented interface (built on cmd) for examining the statistics. Type help at the prompt for available commands.