"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 "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 "strip_dirs()" method removes directory paths from filenames,
making the output more compact. The "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 "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 "print_callers()" method shows which functions called each
displayed function:

   p.print_callers()

The "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 "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
=================

class pstats.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
   "Profile" objects. If multiple sources are provided, their
   statistics are combined.

   The *stream* argument specifies where output from "print_stats()"
   and related methods is written. It defaults to "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.

   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.

   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.

   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 "Stats"
      object.

   sort_stats(*keys)

      Sort the statistics according to the specified criteria.

      Each key can be a string or a "SortKey" enum member. When
      multiple keys are provided, later keys break ties in earlier
      keys.

      Using "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.

      Added in version 3.7: The "SortKey" 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). This method inverts that choice.

   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
      "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:'.

   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 "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 "print_stats()".

   print_callees(*restrictions)

      Print the functions called by each function in the statistics.

      This is the inverse of "print_callers()", showing which
      functions each listed function called.

      Accepts the same restriction arguments as "print_stats()".

   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.

      Added in version 3.9.

class pstats.SortKey

   An enumeration of valid sort keys for "Stats.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
======================

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.

See also:

  "profiling"
     Overview of Python profiling tools.

  "profiling.tracing"
     Deterministic tracing profiler.

  "profiling.sampling"
     Statistical sampling profiler.
