| .. _pstats-module: |
| |
| ******************************************** |
| :mod:`pstats` --- Statistics for profilers |
| ******************************************** |
| |
| .. module:: pstats |
| :synopsis: Statistics object for analyzing profiler output. |
| |
| **Source code:** :source:`Lib/pstats.py` |
| |
| -------------- |
| |
| The :mod:`pstats` module provides tools for reading, manipulating, and |
| displaying profiling statistics generated by Python's profilers. It reads |
| output from both :mod:`profiling.tracing` (deterministic profiler) and |
| :mod:`profiling.sampling` (statistical profiler). |
| |
| |
| Reading and displaying profile data |
| =================================== |
| |
| The :class:`Stats` class is the primary interface for working with profile |
| data. It can read statistics from files or directly from a |
| :class:`~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 :class:`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 :class:`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 :meth:`~Stats.strip_dirs` method removes directory paths from filenames, |
| making the output more compact. The :meth:`~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 :meth:`~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 :meth:`~Stats.print_callers` method shows which functions called each |
| displayed function:: |
| |
| p.print_callers() |
| |
| The :meth:`~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 :meth:`~Stats.print_stats`. |
| |
| |
| Combining multiple profiles |
| --------------------------- |
| |
| Statistics from multiple profiling runs can be combined into a single |
| :class:`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 :class:`!Stats` class |
| ========================= |
| |
| .. class:: Stats(*filenames_or_profile, stream=sys.stdout) |
| |
| Create a statistics object from profile data. |
| |
| The arguments can be filenames (strings or path-like objects) or |
| :class:`~profiling.tracing.Profile` objects. If multiple sources are |
| provided, their statistics are combined. |
| |
| The *stream* argument specifies where output from :meth:`print_stats` and |
| related methods is written. It defaults to :data:`sys.stdout`. |
| |
| 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. |
| |
| .. method:: strip_dirs() |
| |
| Remove leading path information from all filenames. |
| |
| This method modifies the object in place and returns it for method |
| chaining. After stripping, the statistics are considered to be in |
| random order. |
| |
| If stripping causes two functions to become indistinguishable (same |
| filename, line number, and function name), their statistics are |
| combined into a single entry. |
| |
| .. method:: add(*filenames) |
| |
| Add profiling data from additional files. |
| |
| The files must have been created by the same profiler type. Statistics |
| for identical functions are accumulated. |
| |
| .. method:: 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 new :class:`Stats` object. |
| |
| .. method:: sort_stats(*keys) |
| |
| Sort the statistics according to the specified criteria. |
| |
| Each key can be a string or a :class:`SortKey` enum member. When |
| multiple keys are provided, later keys break ties in earlier keys. |
| |
| Using :class:`SortKey` enum members is preferred over strings as it |
| provides better error checking:: |
| |
| from pstats import SortKey |
| p.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 consuming |
| first), while name, file, and line number sorts are ascending |
| (alphabetical). |
| |
| The difference between ``SortKey.NFL`` and ``SortKey.STDNAME`` is that |
| NFL sorts line numbers numerically while STDNAME sorts them as strings. |
| ``sort_stats(SortKey.NFL)`` is equivalent to |
| ``sort_stats(SortKey.NAME, SortKey.FILENAME, SortKey.LINE)``. |
| |
| For backward compatibility, the numeric arguments ``-1``, ``0``, ``1``, |
| and ``2`` are also accepted, meaning ``'stdname'``, ``'calls'``, |
| ``'time'``, and ``'cumulative'`` respectively. |
| |
| .. versionadded:: 3.7 |
| The :class:`SortKey` enum. |
| |
| .. method:: 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). This |
| method inverts that choice. |
| |
| .. method:: print_stats(*restrictions) |
| |
| Print a report of the profiling statistics. |
| |
| The output includes a header line summarizing the data, followed by a |
| table of function statistics sorted according to the last |
| :meth:`sort_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:'. |
| |
| .. method:: print_callers(*restrictions) |
| |
| Print the callers of each function in the statistics. |
| |
| For each function in the filtered results, shows which functions called |
| it and how often. |
| |
| With :mod:`profiling.tracing` (or ``cProfile``), each caller line |
| shows three numbers: the number of calls from that caller, and the |
| total and cumulative times for those specific calls. |
| |
| Accepts the same restriction arguments as :meth:`print_stats`. |
| |
| .. method:: print_callees(*restrictions) |
| |
| Print the functions called by each function in the statistics. |
| |
| This is the inverse of :meth:`print_callers`, showing which functions |
| each listed function called. |
| |
| Accepts the same restriction arguments as :meth:`print_stats`. |
| |
| .. method:: get_stats_profile() |
| |
| Return a ``StatsProfile`` object containing the statistics. |
| |
| The returned object provides programmatic access to the profile data, |
| with function names mapped to ``FunctionProfile`` objects |
| containing timing and call count information. |
| |
| .. versionadded:: 3.9 |
| |
| |
| .. class:: SortKey |
| |
| An enumeration of valid sort keys for :meth:`Stats.sort_stats`. |
| |
| .. attribute:: CALLS |
| |
| Sort by call count. |
| |
| .. attribute:: CUMULATIVE |
| |
| Sort by cumulative time. |
| |
| .. attribute:: FILENAME |
| |
| Sort by file name. |
| |
| .. attribute:: LINE |
| |
| Sort by line number. |
| |
| .. attribute:: NAME |
| |
| Sort by function name. |
| |
| .. attribute:: NFL |
| |
| Sort by name, then file, then line number (numeric line sort). |
| |
| .. attribute:: PCALLS |
| |
| Sort by primitive (non-recursive) call count. |
| |
| .. attribute:: STDNAME |
| |
| Sort by standard name (string-based line sort). |
| |
| .. attribute:: TIME |
| |
| Sort by internal time (time in function excluding subcalls). |
| |
| |
| .. _pstats-cli: |
| |
| Command-line interface |
| ====================== |
| |
| The :mod:`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 :mod:`cmd`) for examining the |
| statistics. Type ``help`` at the prompt for available commands. |
| |
| |
| .. seealso:: |
| |
| :mod:`profiling` |
| Overview of Python profiling tools. |
| |
| :mod:`profiling.tracing` |
| Deterministic tracing profiler. |
| |
| :mod:`profiling.sampling` |
| Statistical sampling profiler. |
