#3865: add note about benchmarking with profilers, and move licensing stuff to bottom of document.

Doc/library/profile.rst

@@ -9,29 +9,6 @@ The Python Profilers
 .. module:: profile
    :synopsis: Python source profiler.
 
-.. index:: single: InfoSeek Corporation
-
-Copyright © 1994, by InfoSeek Corporation, all rights reserved.
-
-Written by James Roskind. [#]_
-
-Permission to use, copy, modify, and distribute this Python software and its
-associated documentation for any purpose (subject to the restriction in the
-following sentence) without fee is hereby granted, provided that the above
-copyright notice appears in all copies, and that both that copyright notice and
-this permission notice appear in supporting documentation, and that the name of
-InfoSeek not be used in advertising or publicity pertaining to distribution of
-the software without specific, written prior permission.  This permission is
-explicitly restricted to the copying and modification of the software to remain
-in Python, compiled Python, or other languages (such as C) wherein the modified
-or derived code is exclusively imported into a Python module.
-
-INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
-INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT
-SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
-DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
-WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
-OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 .. _profiler-introduction:
 
@@ -42,33 +19,38 @@ 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:`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.
+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 two different profilers:
 
-#. :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.
+1. :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.
 
-#. :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.
+2. :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.
 
 The :mod:`profile` and :mod:`cProfile` modules export the same interface, so
 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.
+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.
+
+.. note::
+
+   The profiler modules are designed to provide an execution profile for a given
+   program, not for benchmarking purposes (for that, there is :mod:`timeit` for
+   resonably accurate results).  This particularly applies to benchmarking
+   Python code against C code: the profilers introduce overhead for Python code,
+   but not for C-level functions, and so the C code would seem faster than any
+   Python one.
 
 
 .. _profile-instant:
@@ -608,8 +590,26 @@ The resulting profiler will then call :func:`your_time_func`.
    best results with a custom timer, it might be necessary to hard-code it in the C
    source of the internal :mod:`_lsprof` module.
 
-.. rubric:: Footnotes
 
-.. [#] Updated and converted to LaTeX by Guido van Rossum. Further updated by Armin
-   Rigo to integrate the documentation for the new :mod:`cProfile` module of Python
-   2.5.
+Copyright and License Notices
+=============================
+
+Copyright © 1994, by InfoSeek Corporation, all rights reserved.
+
+Permission to use, copy, modify, and distribute this Python software and its
+associated documentation for any purpose (subject to the restriction in the
+following sentence) without fee is hereby granted, provided that the above
+copyright notice appears in all copies, and that both that copyright notice and
+this permission notice appear in supporting documentation, and that the name of
+InfoSeek not be used in advertising or publicity pertaining to distribution of
+the software without specific, written prior permission.  This permission is
+explicitly restricted to the copying and modification of the software to remain
+in Python, compiled Python, or other languages (such as C) wherein the modified
+or derived code is exclusively imported into a Python module.
+
+INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT
+SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
+DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
+OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.