Reading and displaying profile data¶

TheStats class is the primary interface for working with profiledata. It can read statistics from files or directly from aProfile object.

Load statistics from a file and print a basic report:

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

TheStats object provides methods for sorting and filtering thedata before printing. For example, to see the ten functions with the highestcumulative time:

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

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

frompstatsimportSortKey# Functions that consume the most cumulative timep.sort_stats(SortKey.CUMULATIVE).print_stats(10)# Functions that consume the most time in their own codep.sort_stats(SortKey.TIME).print_stats(10)# Functions sorted by namep.sort_stats(SortKey.NAME).print_stats()

p.print_stats(.1)

p.print_stats('init')

# 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)

p.print_callers()

p.print_callees()

# Load multiple files at oncep=pstats.Stats('run1.prof','run2.prof','run3.prof')# Or add files incrementallyp=pstats.Stats('run1.prof')p.add('run2.prof')p.add('run3.prof')

TheStats class¶

classpstats.Stats(*filenames_or_profile,stream=sys.stdout)¶

Create a statistics object from profile data.

The arguments can be filenames (strings or path-like objects) orProfile objects. If multiple sources areprovided, their statistics are combined.

Thestream argument specifies where output fromprint_stats() andrelated methods is written. It defaults tosys.stdout.

The profile data format is specific to the Python version that created it.There is no compatibility guarantee between Python versions or betweendifferent profilers.

strip_dirs()¶

Remove leading path information from all filenames.

This method modifies the object in place and returns it for methodchaining. After stripping, the statistics are considered to be inrandom order.

If stripping causes two functions to become indistinguishable (samefilename, line number, and function name), their statistics arecombined into a single entry.

add(*filenames)¶

Add profiling data from additional files.

The files must have been created by the same profiler type. Statisticsfor identical functions are accumulated.

dump_stats(filename)¶

Save the current statistics to a file.

The file is created if it does not exist and overwritten if it does.The saved data can be loaded by creating a newStats object.

sort_stats(*keys)¶

Sort the statistics according to the specified criteria.

Each key can be a string or aSortKey enum member. Whenmultiple keys are provided, later keys break ties in earlier keys.

UsingSortKey enum members is preferred over strings as itprovides better error checking:

frompstatsimportSortKeyp.sort_stats(SortKey.CUMULATIVE)

Valid sort keys:

String	Enum	Meaning
'calls'	SortKey.CALLS	call count
'cumulative'	SortKey.CUMULATIVE	cumulative time
'cumtime'	N/A	cumulative time
'file'	N/A	file name
'filename'	SortKey.FILENAME	file name
'module'	N/A	file name
'ncalls'	N/A	call count
'pcalls'	SortKey.PCALLS	primitive call count
'line'	SortKey.LINE	line number
'name'	SortKey.NAME	function name
'nfl'	SortKey.NFL	name/file/line
'stdname'	SortKey.STDNAME	standard name
'time'	SortKey.TIME	internal time
'tottime'	N/A	internal time

All sorts on statistics are in descending order (most time consumingfirst), while name, file, and line number sorts are ascending(alphabetical).

The difference betweenSortKey.NFL andSortKey.STDNAME is thatNFL sorts line numbers numerically while STDNAME sorts them as strings.sort_stats(SortKey.NFL) is equivalent tosort_stats(SortKey.NAME,SortKey.FILENAME,SortKey.LINE).

For backward compatibility, the numeric arguments-1,0,1,and2 are also accepted, meaning'stdname','calls','time', and'cumulative' respectively.

Added in version 3.7:TheSortKey enum.

reverse_order()¶

Reverse the current sort order.

By default, the sort direction is chosen appropriately for the sort key(descending for time-based keys, ascending for name-based keys). Thismethod inverts that choice.

print_stats(*restrictions)¶

Print a report of the profiling statistics.

The output includes a header line summarizing the data, followed by atable of function statistics sorted according to the lastsort_stats() call.

Restrictions filter the output. Each restriction is either:

• An integer: limits output to that many entries

• A float between 0.0 and 1.0: selects that fraction of entries

• A string: matches function names via regular expression

Restrictions are applied sequentially. For example:

print_stats(.1,'foo:')

First limits to the top 10%, then filters to functions matching ‘foo:’.

print_callers(*restrictions)¶

Print the callers of each function in the statistics.

For each function in the filtered results, shows which functions calledit and how often.

Withprofiling.tracing (orcProfile), each caller lineshows three numbers: the number of calls from that caller, and thetotal and cumulative times for those specific calls.

Accepts the same restriction arguments asprint_stats().

print_callees(*restrictions)¶

Print the functions called by each function in the statistics.

This is the inverse ofprint_callers(), showing which functionseach listed function called.

Accepts the same restriction arguments asprint_stats().

get_stats_profile()¶

Return aStatsProfile object containing the statistics.

The returned object provides programmatic access to the profile data,with function names mapped toFunctionProfile objectscontaining timing and call count information.

Added in version 3.9.

classpstats.SortKey¶

An enumeration of valid sort keys forStats.sort_stats().

CALLS¶

Sort by call count.

CUMULATIVE¶

Sort by cumulative time.

FILENAME¶

Sort by file name.

LINE¶

Sort by line number.

NAME¶

Sort by function name.

NFL¶

Sort by name, then file, then line number (numeric line sort).

PCALLS¶

Sort by primitive (non-recursive) call count.

STDNAME¶

Sort by standard name (string-based line sort).

TIME¶

Sort by internal time (time in function excluding subcalls).

Command-line interface¶

Thepstats module can be invoked as a script to interactively browseprofile data:

python-mpstatsprofile_output.prof

This opens a line-oriented interface (built oncmd) for examining thestatistics. Typehelp at the prompt for available commands.