--- rest25/library/profile.rst	2008-12-19 16:58:08.000000000 +0900
+++ rest262/library/profile.rst	2009-04-05 05:02:09.000000000 +0900
@@ -23,118 +23,76 @@
 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.
 
-The profiler was written after only programming in Python for 3 weeks. As a
-result, it is probably clumsy code, but I don't know for sure yet 'cause I'm a
-beginner :-).  I did work hard to make the code run fast, so that profiling
-would be a reasonable thing to do.  I tried not to repeat code fragments, but
-I'm sure I did some stuff in really awkward ways at times.  Please send
-suggestions for improvements to: jar@netscape.com.  I won't promise *any*
-support.  ...but I'd appreciate the feedback.
-
+.. _profiler-introduction:
 
 Introduction to the profilers
 =============================
 
-.. _profiler introduction:
-
 .. index::
    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`,
+#. :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:
 
 Instant User's Manual
 =====================
 
 This section is provided for users that "don't want to read the manual." It
 provides a very brief overview, and allows a user to rapidly perform profiling
 on an existing application.
 
 To profile an application with a main entry point of :func:`foo`, you would add
@@ -176,25 +134,25 @@
 The class :class:`Stats` (the above code just created an instance of this class)
 has a variety of methods for manipulating and printing the data that was just
 read into ``p``.  When you ran :func:`cProfile.run` above, what was printed was
 the result of three method calls::
 
    p.strip_dirs().sort_stats(-1).print_stats()
 
 The first method removed the extraneous path from all the module names. The
 second method sorted all the entries according to the standard module/line/name
 string that is printed. The third method printed out all the statistics.  You
 might try the following sort calls:
 
-.. % (this is to comply with the semantics of the old profiler).
+.. (this is to comply with the semantics of the old profiler).
 
 ::
 
    p.sort_stats('name')
    p.print_stats()
 
 The first call will actually sort the list by function name, and the second call
 will print out the statistics.  The following are some interesting calls to
 experiment with::
 
    p.sort_stats('cumulative').print_stats(10)
 
@@ -234,29 +192,29 @@
 
 If you want more functionality, you're going to have to read the manual, or
 guess what the following functions do::
 
    p.print_callees()
    p.add('fooprof')
 
 Invoked as a script, the :mod:`pstats` module is a statistics browser for
 reading and examining profile dumps.  It has a simple line-oriented interface
 (implemented using :mod:`cmd`) and interactive help.
 
 
+.. _deterministic-profiling:
+
 What Is Deterministic Profiling?
 ================================
 
-.. _deterministic profiling:
-
 :dfn:`Deterministic profiling` is meant to reflect the fact that all *function
 call*, *function return*, and *exception* events are monitored, and precise
 timings are made for the intervals between these events (during which time the
 user's code is executing).  In contrast, :dfn:`statistical profiling` (which is
 not done by this module) randomly samples the effective instruction pointer, and
 deduces where time is being spent.  The latter technique traditionally involves
 less overhead (as the code does not need to be instrumented), but provides only
 relative indications of where time is being spent.
 
 In Python, since there is an interpreter active during execution, the presence
 of instrumented code is not required to do deterministic profiling.  Python
 automatically provides a :dfn:`hook` (optional callback) for each event.  In
@@ -286,108 +244,106 @@
 The primary entry point for the profiler is the global function
 :func:`profile.run` (resp. :func:`cProfile.run`). It is typically used to create
 any profile information.  The reports are formatted and printed using methods of
 the class :class:`pstats.Stats`.  The following is a description of all of these
 standard entry points and functions.  For a more in-depth view of some of the
 code, consider reading the later section on Profiler Extensions, which includes
 discussion of how to derive "better" profilers from the classes presented, or
 reading the source code for these modules.
 
 
 .. function:: run(command[, filename])
 
-   This function takes a single argument that has can be passed to the
-   :keyword:`exec` statement, and an optional file name.  In all cases this routine
-   attempts to :keyword:`exec` its first argument, and gather profiling statistics
-   from the execution. If no file name is present, then this function automatically
-   prints a simple profiling report, sorted by the standard name string (file/line
-   /function-name) that is presented in each line.  The following is a typical
-   output from such a call::
+   This function takes a single argument that can be passed to the
+   :keyword:`exec` statement, and an optional file name.  In all cases this
+   routine attempts to :keyword:`exec` its first argument, and gather profiling
+   statistics from the execution. If no file name is present, then this function
+   automatically prints a simple profiling report, sorted by the standard name
+   string (file/line/function-name) that is presented in each line.  The
+   following is a typical output from such a call::
 
             2706 function calls (2004 primitive calls) in 4.504 CPU seconds
 
       Ordered by: standard name
 
       ncalls  tottime  percall  cumtime  percall filename:lineno(function)
            2    0.006    0.003    0.953    0.477 pobject.py:75(save_objects)
         43/3    0.533    0.012    0.749    0.250 pobject.py:99(evaluate)
        ...
 
    The first line indicates that 2706 calls were monitored.  Of those calls, 2004
    were :dfn:`primitive`.  We define :dfn:`primitive` to mean that the call was not
    induced via recursion. The next line: ``Ordered by: standard name``, indicates
    that the text string in the far right column was used to sort the output. The
    column headings include:
 
-   ncalls 
+   ncalls
       for the number of calls,
 
-   tottime 
+   tottime
       for the total time spent in the given function (and excluding time made in calls
       to sub-functions),
 
-   percall 
+   percall
       is the quotient of ``tottime`` divided by ``ncalls``
 
-   cumtime 
+   cumtime
       is the total time spent in this and all subfunctions (from invocation till
       exit). This figure is accurate *even* for recursive functions.
 
-   percall 
+   percall
       is the quotient of ``cumtime`` divided by primitive calls
 
-   filename:lineno(function) 
+   filename:lineno(function)
       provides the respective data of each function
 
    When there are two numbers in the first column (for example, ``43/3``), then the
    latter is the number of primitive calls, and the former is the actual number of
    calls.  Note that when the function does not recurse, these two values are the
    same, and only the single figure is printed.
 
 
 .. function:: runctx(command, globals, locals[, filename])
 
    This function is similar to :func:`run`, with added arguments to supply the
    globals and locals dictionaries for the *command* string.
 
 Analysis of the profiler data is done using the :class:`Stats` class.
 
 .. note::
 
    The :class:`Stats` class is defined in the :mod:`pstats` module.
 
-.. module:: pstats
-
 
-.. % now switch modules....
-.. % (This \stmodindex use may be hard to change ;-( )
+.. module:: pstats
+   :synopsis: Statistics object for use with the profiler.
 
 
 .. class:: Stats(filename[, stream=sys.stdout[, ...]])
 
    This class constructor creates an instance of a "statistics object" from a
    *filename* (or set of filenames).  :class:`Stats` objects are manipulated by
    methods, in order to print useful reports.  You may specify an alternate output
    stream by giving the keyword argument, ``stream``.
 
    The file selected by the above constructor must have been created by the
    corresponding version of :mod:`profile` or :mod:`cProfile`.  To be specific,
    there is *no* file compatibility guaranteed with future versions of this
    profiler, and there is no compatibility with files produced by other profilers.
    If several files are provided, all the statistics for identical functions will
    be coalesced, so that an overall view of several processes can be considered in
    a single report.  If additional files need to be combined with data in an
    existing :class:`Stats` object, the :meth:`add` method can be used.
 
-   .. % (such as the old system profiler).
+   .. (such as the old system profiler).
 
    .. versionchanged:: 2.5
       The *stream* parameter was added.
 
 
 .. _profile-stats:
 
 The :class:`Stats` Class
 ------------------------
 
 :class:`Stats` objects have the following methods:
 
@@ -470,35 +426,34 @@
    means that the embedded line numbers get compared in an odd way.  For example,
    lines 3, 20, and 40 would (if the file names were the same) appear in the string
    order 20, 3 and 40.  In contrast, ``'nfl'`` does a numeric compare of the line
    numbers.  In fact, ``sort_stats('nfl')`` is the same as ``sort_stats('name',
    'file', 'line')``.
 
    For backward-compatibility reasons, the numeric arguments ``-1``, ``0``, ``1``,
    and ``2`` are permitted.  They are interpreted as ``'stdname'``, ``'calls'``,
    ``'time'``, and ``'cumulative'`` respectively.  If this old style format
    (numeric) is used, only one sort key (the numeric key) will be used, and
    additional arguments will be silently ignored.
 
-   .. % For compatibility with the old profiler,
+   .. For compatibility with the old profiler,
 
 
 .. method:: Stats.reverse_order()
 
    This method for the :class:`Stats` class reverses the ordering of the basic list
    within the object.  Note that by default ascending vs descending order is
    properly selected based on the sort key of choice.
 
-   .. % This method is provided primarily for
-   .. % compatibility with the old profiler.
+   .. This method is provided primarily for compatibility with the old profiler.
 
 
 .. method:: Stats.print_stats([restriction, ...])
 
    This method for the :class:`Stats` class prints out a report as described in the
    :func:`profile.run` definition.
 
    The order of the printing is based on the last :meth:`sort_stats` operation done
    on the object (subject to caveats in :meth:`add` and :meth:`strip_dirs`).
 
    The arguments provided (if any) can be used to limit the list down to the
    significant entries.  Initially, the list is taken to be the complete set of
@@ -520,30 +475,30 @@
    would limit the list to all functions having file names :file:`.\*foo:`, and
    then proceed to only print the first 10% of them.
 
 
 .. method:: Stats.print_callers([restriction, ...])
 
    This method for the :class:`Stats` class prints a list of all functions that
    called each function in the profiled database.  The ordering is identical to
    that provided by :meth:`print_stats`, and the definition of the restricting
    argument is also identical.  Each caller is reported on its own line.  The
    format differs slightly depending on the profiler that produced the stats:
 
-* With :mod:`profile`, a number is shown in parentheses after each caller to
-     show how many times this specific call was made.  For convenience, a second non-
-     parenthesized number repeats the cumulative time spent in the function at the
-     right.
+   * With :mod:`profile`, a number is shown in parentheses after each caller to
+     show how many times this specific call was made.  For convenience, a second
+     non-parenthesized number repeats the cumulative time spent in the function
+     at the right.
 
-* With :mod:`cProfile`, each caller is preceeded by three numbers: the number of
+   * With :mod:`cProfile`, each caller is preceded by three numbers: the number of
      times this specific call was made, and the total and cumulative times spent in
      the current function while it was invoked by this specific caller.
 
 
 .. method:: Stats.print_callees([restriction, ...])
 
    This method for the :class:`Stats` class prints a list of all function that were
    called by the indicated function.  Aside from this reversal of direction of
    calls (re: called vs was called by), the arguments and ordering are identical to
    the :meth:`print_callers` method.
 
 
@@ -616,29 +571,29 @@
 
    # 2. Apply computed bias to a specific Profile instance.
    pr = profile.Profile()
    pr.bias = your_computed_bias
 
    # 3. Specify computed bias in instance constructor.
    pr = profile.Profile(bias=your_computed_bias)
 
 If you have a choice, you are better off choosing a smaller constant, and then
 your results will "less often" show up as negative in profile statistics.
 
 
+.. _profiler-extensions:
+
 Extensions --- Deriving Better Profilers
 ========================================
 
-.. _profiler extensions:
-
 The :class:`Profile` class of both modules, :mod:`profile` and :mod:`cProfile`,
 were written so that derived classes could be developed to extend the profiler.
 The details are not described here, as doing this successfully requires an
 expert understanding of how the :class:`Profile` class works internally.  Study
 the source code of the module carefully if you want to pursue this.
 
 If all you want to do is change how current time is determined (for example, to
 force use of wall-clock time or elapsed process time), pass the timing function
 you want to the :class:`Profile` class constructor::
 
    pr = profile.Profile(your_time_func)
 
