diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst index 5bc6319bec4..4c0ba1552b8 100644 --- a/Doc/library/profile.rst +++ b/Doc/library/profile.rst @@ -41,82 +41,49 @@ Introduction to the profilers single: deterministic profiling single: profiling, deterministic -A :dfn:`profiler` is a program that describes the run time performance of a -program, providing a variety of statistics. This documentation describes the -profiler functionality provided in the modules :mod:`profile` and :mod:`pstats`. -This profiler provides :dfn:`deterministic profiling` of any Python programs. -It also provides a series of report generation tools to allow users to rapidly +A :dfn:`profiler` is a program that describes the run time performance +of a program, providing a variety of statistics. This documentation +describes the profiler functionality provided in the modules +:mod:`cProfile`, :mod:`profile` and :mod:`pstats`. This profiler +provides :dfn:`deterministic profiling` of Python programs. It also +provides a series of report generation tools to allow users to rapidly examine the results of a profile operation. The Python standard library provides three different profilers: -#. :mod:`profile`, a pure Python module, described in the sequel. Copyright © - 1994, by InfoSeek Corporation. - - .. versionchanged:: 2.4 - also reports the time spent in calls to built-in functions and methods. - -#. :mod:`cProfile`, a module written in C, with a reasonable overhead that makes - it suitable for profiling long-running programs. Based on :mod:`lsprof`, - contributed by Brett Rosen and Ted Czotter. +#. :mod:`cProfile` is recommended for most users; it's a C extension + with reasonable overhead + that makes it suitable for profiling long-running programs. + Based on :mod:`lsprof`, + contributed by Brett Rosen and Ted Czotter. .. versionadded:: 2.5 -#. :mod:`hotshot`, a C module focusing on minimizing the overhead while - profiling, at the expense of long data post-processing times. +#. :mod:`profile`, a pure Python module whose interface is imitated by + :mod:`cProfile`. Adds significant overhead to profiled programs. + If you're trying to extend + the profiler in some way, the task might be easier with this module. + Copyright © 1994, by InfoSeek Corporation. + + .. versionchanged:: 2.4 + Now also reports the time spent in calls to built-in functions and methods. + +#. :mod:`hotshot` was an experimental C module that focused on minimizing + the overhead of profiling, at the expense of longer data + post-processing times. It is no longer maintained and may be + dropped in a future version of Python. + .. versionchanged:: 2.5 - the results should be more meaningful than in the past: the timing core + The results should be more meaningful than in the past: the timing core contained a critical bug. The :mod:`profile` and :mod:`cProfile` modules export the same interface, so -they are mostly interchangeables; :mod:`cProfile` has a much lower overhead but -is not so far as well-tested and might not be available on all systems. +they are mostly interchangeable; :mod:`cProfile` has a much lower overhead but +is newer and might not be available on all systems. :mod:`cProfile` is really a compatibility layer on top of the internal -:mod:`_lsprof` module. The :mod:`hotshot` module is reserved to specialized -usages. - -.. \section{How Is This Profiler Different From The Old Profiler?} - \nodename{Profiler Changes} - - (This section is of historical importance only; the old profiler - discussed here was last seen in Python 1.1.) - - The big changes from old profiling module are that you get more - information, and you pay less CPU time. It's not a trade-off, it's a - trade-up. - - To be specific: - - \begin{description} - - \item[Bugs removed:] - Local stack frame is no longer molested, execution time is now charged - to correct functions. - - \item[Accuracy increased:] - Profiler execution time is no longer charged to user's code, - calibration for platform is supported, file reads are not done \emph{by} - profiler \emph{during} profiling (and charged to user's code!). - - \item[Speed increased:] - Overhead CPU cost was reduced by more than a factor of two (perhaps a - factor of five), lightweight profiler module is all that must be - loaded, and the report generating module (\module{pstats}) is not needed - during profiling. - - \item[Recursive functions support:] - Cumulative times in recursive functions are correctly calculated; - recursive entries are counted. - - \item[Large growth in report generating UI:] - Distinct profiles runs can be added together forming a comprehensive - report; functions that import statistics take arbitrary lists of - files; sorting criteria is now based on keywords (instead of 4 integer - options); reports shows what functions were profiled as well as what - profile file was referenced; output format has been improved. - - \end{description} +:mod:`_lsprof` module. The :mod:`hotshot` module is reserved for specialized +usage. .. _profile-instant: