Files
FootPrint/Python/pythoncore-3.15-64/Doc/html/library/pstats.html
T

764 lines
51 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="pstats — Statistics for profilers" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/pstats.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="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.traci..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="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.traci..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>pstats — Statistics for profilers &#8212; Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="timeit — Measure execution time of small code snippets" href="timeit.html" />
<link rel="prev" title="profiling.sampling — Statistical profiler" href="profiling.sampling.html" />
<link rel="canonical" href="https://docs.python.org/3/library/pstats.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers</a><ul>
<li><a class="reference internal" href="#reading-and-displaying-profile-data">Reading and displaying profile data</a><ul>
<li><a class="reference internal" href="#working-with-statistics">Working with statistics</a></li>
<li><a class="reference internal" href="#filtering-output">Filtering output</a></li>
<li><a class="reference internal" href="#analyzing-call-relationships">Analyzing call relationships</a></li>
<li><a class="reference internal" href="#combining-multiple-profiles">Combining multiple profiles</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-stats-class">The <code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code> class</a></li>
<li><a class="reference internal" href="#command-line-interface">Command-line interface</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="profiling.sampling.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code> — Statistical profiler</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="timeit.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">timeit</span></code> — Measure execution time of small code snippets</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/pstats.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/pstats.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="timeit.html" title="timeit — Measure execution time of small code snippets"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="profiling.sampling.html" title="profiling.sampling — Statistical profiler"
accesskey="P">previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="debug.html" accesskey="U">Debugging and profiling</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-pstats">
<span id="pstats-statistics-for-profilers"></span><span id="pstats-module"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers<a class="headerlink" href="#module-pstats" title="Link to this heading"></a></h1>
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Lib/pstats.py">Lib/pstats.py</a></p>
<hr class="docutils" />
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> module provides tools for reading, manipulating, and
displaying profiling statistics generated by Python’s profilers. It reads
output from both <a class="reference internal" href="profiling.tracing.html#module-profiling.tracing" title="profiling.tracing: Deterministic tracing profiler for Python programs."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code></a> (deterministic profiler) and
<a class="reference internal" href="profiling.sampling.html#module-profiling.sampling" title="profiling.sampling: Statistical sampling profiler for Python processes."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code></a> (statistical profiler).</p>
<section id="reading-and-displaying-profile-data">
<h2>Reading and displaying profile data<a class="headerlink" href="#reading-and-displaying-profile-data" title="Link to this heading"></a></h2>
<p>The <a class="reference internal" href="#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code></a> class is the primary interface for working with profile
data. It can read statistics from files or directly from a
<a class="reference internal" href="profiling.tracing.html#profiling.tracing.Profile" title="profiling.tracing.Profile"><code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code></a> object.</p>
<p>Load statistics from a file and print a basic report:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">pstats</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'profile_output.prof'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">print_stats</span><span class="p">()</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code></a> object provides methods for sorting and filtering the
data before printing. For example, to see the ten functions with the highest
cumulative time:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">pstats</span><span class="w"> </span><span class="kn">import</span> <span class="n">SortKey</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'profile_output.prof'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">CUMULATIVE</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
<section id="working-with-statistics">
<h3>Working with statistics<a class="headerlink" href="#working-with-statistics" title="Link to this heading"></a></h3>
<p>The <a class="reference internal" href="#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code></a> class supports method chaining, making it convenient to
perform multiple operations:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'restats'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">strip_dirs</span><span class="p">()</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">()</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#pstats.Stats.strip_dirs" title="pstats.Stats.strip_dirs"><code class="xref py py-meth docutils literal notranslate"><span class="pre">strip_dirs()</span></code></a> method removes directory paths from filenames,
making the output more compact. The <a class="reference internal" href="#pstats.Stats.sort_stats" title="pstats.Stats.sort_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sort_stats()</span></code></a> method accepts
various keys to control the sort order.</p>
<p>Different sort keys highlight different aspects of performance:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">pstats</span><span class="w"> </span><span class="kn">import</span> <span class="n">SortKey</span>
<span class="c1"># Functions that consume the most cumulative time</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">CUMULATIVE</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="c1"># Functions that consume the most time in their own code</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">TIME</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="c1"># Functions sorted by name</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">NAME</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="filtering-output">
<h3>Filtering output<a class="headerlink" href="#filtering-output" title="Link to this heading"></a></h3>
<p>The <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a> 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).</p>
<p>Print only the top 10%:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mf">.1</span><span class="p">)</span>
</pre></div>
</div>
<p>Print only functions whose names contain “init”:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="s1">'init'</span><span class="p">)</span>
</pre></div>
</div>
<p>Combine restrictions (they apply sequentially):</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Top 10%, then only those containing "init"</span>
<span class="n">p</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="mf">.1</span><span class="p">,</span> <span class="s1">'init'</span><span class="p">)</span>
<span class="c1"># Functions in files matching "foo:", limited to top 50%</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">FILENAME</span><span class="p">)</span><span class="o">.</span><span class="n">print_stats</span><span class="p">(</span><span class="s1">'foo:'</span><span class="p">,</span> <span class="mf">.5</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="analyzing-call-relationships">
<h3>Analyzing call relationships<a class="headerlink" href="#analyzing-call-relationships" title="Link to this heading"></a></h3>
<p>The <a class="reference internal" href="#pstats.Stats.print_callers" title="pstats.Stats.print_callers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_callers()</span></code></a> method shows which functions called each
displayed function:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span><span class="o">.</span><span class="n">print_callers</span><span class="p">()</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#pstats.Stats.print_callees" title="pstats.Stats.print_callees"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_callees()</span></code></a> method shows the opposite relationship,
listing which functions each displayed function called:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">p</span><span class="o">.</span><span class="n">print_callees</span><span class="p">()</span>
</pre></div>
</div>
<p>Both methods accept the same restriction arguments as <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a>.</p>
</section>
<section id="combining-multiple-profiles">
<h3>Combining multiple profiles<a class="headerlink" href="#combining-multiple-profiles" title="Link to this heading"></a></h3>
<p>Statistics from multiple profiling runs can be combined into a single
<a class="reference internal" href="#pstats.Stats" title="pstats.Stats"><code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code></a> object:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Load multiple files at once</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'run1.prof'</span><span class="p">,</span> <span class="s1">'run2.prof'</span><span class="p">,</span> <span class="s1">'run3.prof'</span><span class="p">)</span>
<span class="c1"># Or add files incrementally</span>
<span class="n">p</span> <span class="o">=</span> <span class="n">pstats</span><span class="o">.</span><span class="n">Stats</span><span class="p">(</span><span class="s1">'run1.prof'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s1">'run2.prof'</span><span class="p">)</span>
<span class="n">p</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s1">'run3.prof'</span><span class="p">)</span>
</pre></div>
</div>
<p>When files are combined, statistics for identical functions (same file, line,
and name) are accumulated, giving an aggregate view across all profiling runs.</p>
</section>
</section>
<section id="the-stats-class">
<h2>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code> class<a class="headerlink" href="#the-stats-class" title="Link to this heading"></a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="pstats.Stats">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pstats.</span></span><span class="sig-name descname"><span class="pre">Stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">filenames_or_profile</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stream</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">sys.stdout</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats" title="Link to this definition"></a></dt>
<dd><p>Create a statistics object from profile data.</p>
<p>The arguments can be filenames (strings or path-like objects) or
<a class="reference internal" href="profiling.tracing.html#profiling.tracing.Profile" title="profiling.tracing.Profile"><code class="xref py py-class docutils literal notranslate"><span class="pre">Profile</span></code></a> objects. If multiple sources are
provided, their statistics are combined.</p>
<p>The <em>stream</em> argument specifies where output from <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a> and
related methods is written. It defaults to <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a>.</p>
<p>The profile data format is specific to the Python version that created it.
There is no compatibility guarantee between Python versions or between
different profilers.</p>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.strip_dirs">
<span class="sig-name descname"><span class="pre">strip_dirs</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.strip_dirs" title="Link to this definition"></a></dt>
<dd><p>Remove leading path information from all filenames.</p>
<p>This method modifies the object in place and returns it for method
chaining. After stripping, the statistics are considered to be in
random order.</p>
<p>If stripping causes two functions to become indistinguishable (same
filename, line number, and function name), their statistics are
combined into a single entry.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.add">
<span class="sig-name descname"><span class="pre">add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">filenames</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.add" title="Link to this definition"></a></dt>
<dd><p>Add profiling data from additional files.</p>
<p>The files must have been created by the same profiler type. Statistics
for identical functions are accumulated.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.dump_stats">
<span class="sig-name descname"><span class="pre">dump_stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.dump_stats" title="Link to this definition"></a></dt>
<dd><p>Save the current statistics to a file.</p>
<p>The file is created if it does not exist and overwritten if it does.
The saved data can be loaded by creating a new <code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code> object.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.sort_stats">
<span class="sig-name descname"><span class="pre">sort_stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">keys</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.sort_stats" title="Link to this definition"></a></dt>
<dd><p>Sort the statistics according to the specified criteria.</p>
<p>Each key can be a string or a <a class="reference internal" href="#pstats.SortKey" title="pstats.SortKey"><code class="xref py py-class docutils literal notranslate"><span class="pre">SortKey</span></code></a> enum member. When
multiple keys are provided, later keys break ties in earlier keys.</p>
<p>Using <a class="reference internal" href="#pstats.SortKey" title="pstats.SortKey"><code class="xref py py-class docutils literal notranslate"><span class="pre">SortKey</span></code></a> enum members is preferred over strings as it
provides better error checking:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">pstats</span><span class="w"> </span><span class="kn">import</span> <span class="n">SortKey</span>
<span class="n">p</span><span class="o">.</span><span class="n">sort_stats</span><span class="p">(</span><span class="n">SortKey</span><span class="o">.</span><span class="n">CUMULATIVE</span><span class="p">)</span>
</pre></div>
</div>
<p>Valid sort keys:</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>String</p></th>
<th class="head"><p>Enum</p></th>
<th class="head"><p>Meaning</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'calls'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.CALLS</span></code></p></td>
<td><p>call count</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'cumulative'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.CUMULATIVE</span></code></p></td>
<td><p>cumulative time</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'cumtime'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>cumulative time</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'file'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>file name</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'filename'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.FILENAME</span></code></p></td>
<td><p>file name</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'module'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>file name</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'ncalls'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>call count</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'pcalls'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.PCALLS</span></code></p></td>
<td><p>primitive call count</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'line'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.LINE</span></code></p></td>
<td><p>line number</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'name'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.NAME</span></code></p></td>
<td><p>function name</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'nfl'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.NFL</span></code></p></td>
<td><p>name/file/line</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'stdname'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.STDNAME</span></code></p></td>
<td><p>standard name</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'time'</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SortKey.TIME</span></code></p></td>
<td><p>internal time</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'tottime'</span></code></p></td>
<td><p>N/A</p></td>
<td><p>internal time</p></td>
</tr>
</tbody>
</table>
<p>All sorts on statistics are in descending order (most time consuming
first), while name, file, and line number sorts are ascending
(alphabetical).</p>
<p>The difference between <code class="docutils literal notranslate"><span class="pre">SortKey.NFL</span></code> and <code class="docutils literal notranslate"><span class="pre">SortKey.STDNAME</span></code> is that
NFL sorts line numbers numerically while STDNAME sorts them as strings.
<code class="docutils literal notranslate"><span class="pre">sort_stats(SortKey.NFL)</span></code> is equivalent to
<code class="docutils literal notranslate"><span class="pre">sort_stats(SortKey.NAME,</span> <span class="pre">SortKey.FILENAME,</span> <span class="pre">SortKey.LINE)</span></code>.</p>
<p>For backward compatibility, the numeric arguments <code class="docutils literal notranslate"><span class="pre">-1</span></code>, <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code>,
and <code class="docutils literal notranslate"><span class="pre">2</span></code> are also accepted, meaning <code class="docutils literal notranslate"><span class="pre">'stdname'</span></code>, <code class="docutils literal notranslate"><span class="pre">'calls'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'time'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'cumulative'</span></code> respectively.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.7: </span>The <a class="reference internal" href="#pstats.SortKey" title="pstats.SortKey"><code class="xref py py-class docutils literal notranslate"><span class="pre">SortKey</span></code></a> enum.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.reverse_order">
<span class="sig-name descname"><span class="pre">reverse_order</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.reverse_order" title="Link to this definition"></a></dt>
<dd><p>Reverse the current sort order.</p>
<p>By default, the sort direction is chosen appropriately for the sort key
(descending for time-based keys, ascending for name-based keys). This
method inverts that choice.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.print_stats">
<span class="sig-name descname"><span class="pre">print_stats</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">restrictions</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.print_stats" title="Link to this definition"></a></dt>
<dd><p>Print a report of the profiling statistics.</p>
<p>The output includes a header line summarizing the data, followed by a
table of function statistics sorted according to the last
<a class="reference internal" href="#pstats.Stats.sort_stats" title="pstats.Stats.sort_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sort_stats()</span></code></a> call.</p>
<p>Restrictions filter the output. Each restriction is either:</p>
<ul class="simple">
<li><p>An integer: limits output to that many entries</p></li>
<li><p>A float between 0.0 and 1.0: selects that fraction of entries</p></li>
<li><p>A string: matches function names via regular expression</p></li>
</ul>
<p>Restrictions are applied sequentially. For example:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">print_stats</span><span class="p">(</span><span class="mf">.1</span><span class="p">,</span> <span class="s1">'foo:'</span><span class="p">)</span>
</pre></div>
</div>
<p>First limits to the top 10%, then filters to functions matching ‘foo:’.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.print_callers">
<span class="sig-name descname"><span class="pre">print_callers</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">restrictions</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.print_callers" title="Link to this definition"></a></dt>
<dd><p>Print the callers of each function in the statistics.</p>
<p>For each function in the filtered results, shows which functions called
it and how often.</p>
<p>With <a class="reference internal" href="profiling.tracing.html#module-profiling.tracing" title="profiling.tracing: Deterministic tracing profiler for Python programs."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code></a> (or <code class="docutils literal notranslate"><span class="pre">cProfile</span></code>), each caller line
shows three numbers: the number of calls from that caller, and the
total and cumulative times for those specific calls.</p>
<p>Accepts the same restriction arguments as <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.print_callees">
<span class="sig-name descname"><span class="pre">print_callees</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">restrictions</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.print_callees" title="Link to this definition"></a></dt>
<dd><p>Print the functions called by each function in the statistics.</p>
<p>This is the inverse of <a class="reference internal" href="#pstats.Stats.print_callers" title="pstats.Stats.print_callers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_callers()</span></code></a>, showing which functions
each listed function called.</p>
<p>Accepts the same restriction arguments as <a class="reference internal" href="#pstats.Stats.print_stats" title="pstats.Stats.print_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_stats()</span></code></a>.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="pstats.Stats.get_stats_profile">
<span class="sig-name descname"><span class="pre">get_stats_profile</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pstats.Stats.get_stats_profile" title="Link to this definition"></a></dt>
<dd><p>Return a <code class="docutils literal notranslate"><span class="pre">StatsProfile</span></code> object containing the statistics.</p>
<p>The returned object provides programmatic access to the profile data,
with function names mapped to <code class="docutils literal notranslate"><span class="pre">FunctionProfile</span></code> objects
containing timing and call count information.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.9.</span></p>
</div>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py" id="pstats.SortKey">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pstats.</span></span><span class="sig-name descname"><span class="pre">SortKey</span></span><a class="headerlink" href="#pstats.SortKey" title="Link to this definition"></a></dt>
<dd><p>An enumeration of valid sort keys for <a class="reference internal" href="#pstats.Stats.sort_stats" title="pstats.Stats.sort_stats"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Stats.sort_stats()</span></code></a>.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.CALLS">
<span class="sig-name descname"><span class="pre">CALLS</span></span><a class="headerlink" href="#pstats.SortKey.CALLS" title="Link to this definition"></a></dt>
<dd><p>Sort by call count.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.CUMULATIVE">
<span class="sig-name descname"><span class="pre">CUMULATIVE</span></span><a class="headerlink" href="#pstats.SortKey.CUMULATIVE" title="Link to this definition"></a></dt>
<dd><p>Sort by cumulative time.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.FILENAME">
<span class="sig-name descname"><span class="pre">FILENAME</span></span><a class="headerlink" href="#pstats.SortKey.FILENAME" title="Link to this definition"></a></dt>
<dd><p>Sort by file name.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.LINE">
<span class="sig-name descname"><span class="pre">LINE</span></span><a class="headerlink" href="#pstats.SortKey.LINE" title="Link to this definition"></a></dt>
<dd><p>Sort by line number.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.NAME">
<span class="sig-name descname"><span class="pre">NAME</span></span><a class="headerlink" href="#pstats.SortKey.NAME" title="Link to this definition"></a></dt>
<dd><p>Sort by function name.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.NFL">
<span class="sig-name descname"><span class="pre">NFL</span></span><a class="headerlink" href="#pstats.SortKey.NFL" title="Link to this definition"></a></dt>
<dd><p>Sort by name, then file, then line number (numeric line sort).</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.PCALLS">
<span class="sig-name descname"><span class="pre">PCALLS</span></span><a class="headerlink" href="#pstats.SortKey.PCALLS" title="Link to this definition"></a></dt>
<dd><p>Sort by primitive (non-recursive) call count.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.STDNAME">
<span class="sig-name descname"><span class="pre">STDNAME</span></span><a class="headerlink" href="#pstats.SortKey.STDNAME" title="Link to this definition"></a></dt>
<dd><p>Sort by standard name (string-based line sort).</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="pstats.SortKey.TIME">
<span class="sig-name descname"><span class="pre">TIME</span></span><a class="headerlink" href="#pstats.SortKey.TIME" title="Link to this definition"></a></dt>
<dd><p>Sort by internal time (time in function excluding subcalls).</p>
</dd></dl>
</dd></dl>
</section>
<section id="command-line-interface">
<span id="pstats-cli"></span><h2>Command-line interface<a class="headerlink" href="#command-line-interface" title="Link to this heading"></a></h2>
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> module can be invoked as a script to interactively browse
profile data:</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pstats</span> <span class="n">profile_output</span><span class="o">.</span><span class="n">prof</span>
</pre></div>
</div>
<p>This opens a line-oriented interface (built on <a class="reference internal" href="cmd.html#module-cmd" title="cmd: Build line-oriented command interpreters."><code class="xref py py-mod docutils literal notranslate"><span class="pre">cmd</span></code></a>) for examining the
statistics. Type <code class="docutils literal notranslate"><span class="pre">help</span></code> at the prompt for available commands.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<dl class="simple">
<dt><a class="reference internal" href="profiling.html#module-profiling" title="profiling: Python profiling tools for performance analysis."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling</span></code></a></dt><dd><p>Overview of Python profiling tools.</p>
</dd>
<dt><a class="reference internal" href="profiling.tracing.html#module-profiling.tracing" title="profiling.tracing: Deterministic tracing profiler for Python programs."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.tracing</span></code></a></dt><dd><p>Deterministic tracing profiler.</p>
</dd>
<dt><a class="reference internal" href="profiling.sampling.html#module-profiling.sampling" title="profiling.sampling: Statistical sampling profiler for Python processes."><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code></a></dt><dd><p>Statistical sampling profiler.</p>
</dd>
</dl>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers</a><ul>
<li><a class="reference internal" href="#reading-and-displaying-profile-data">Reading and displaying profile data</a><ul>
<li><a class="reference internal" href="#working-with-statistics">Working with statistics</a></li>
<li><a class="reference internal" href="#filtering-output">Filtering output</a></li>
<li><a class="reference internal" href="#analyzing-call-relationships">Analyzing call relationships</a></li>
<li><a class="reference internal" href="#combining-multiple-profiles">Combining multiple profiles</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-stats-class">The <code class="xref py py-class docutils literal notranslate"><span class="pre">Stats</span></code> class</a></li>
<li><a class="reference internal" href="#command-line-interface">Command-line interface</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="profiling.sampling.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">profiling.sampling</span></code> — Statistical profiler</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="timeit.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">timeit</span></code> — Measure execution time of small code snippets</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "library/pstats.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/pstats.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="timeit.html" title="timeit — Measure execution time of small code snippets"
>next</a> |</li>
<li class="right" >
<a href="profiling.sampling.html" title="profiling.sampling — Statistical profiler"
>previous</a> |</li>
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> &#187;</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0 Documentation</a> &#187;
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="debug.html" >Debugging and profiling</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">pstats</span></code> — Statistics for profilers</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
&copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Oct 09, 2026 (11:35 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>