Lots of small markup adjustments.
diff --git a/Doc/lib/libhotshot.tex b/Doc/lib/libhotshot.tex
index 9c2513d..05bc067 100644
--- a/Doc/lib/libhotshot.tex
+++ b/Doc/lib/libhotshot.tex
@@ -2,31 +2,31 @@
High performance logging profiler}
\declaremodule{standard}{hotshot}
+\modulesynopsis{High performance logging profiler, mostly written in C.}
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
\sectionauthor{Anthony Baxter}{anthony@interlink.com.au}
-
\versionadded{2.2}
-\modulesynopsis{High performance logging profiler, mostly written in C.}
-
-This module provides a nicer interface to the \code{_hotshot} C module.
+This module provides a nicer interface to the \module{_hotshot} C module.
Hotshot is a replacement for the existing \refmodule{profile} module. As it's
-written mostly in C, it should result in a much smaller performance impact
-than the existing profile module.
+written mostly in C, it should result in a much smaller performance impact
+than the existing \refmodule{profile} module.
-\begin{classdesc}{Profile}{logfile, \optional{, lineevents=0, linetimings=1}}
-
-The profiler object. The argument \var{logfile} is the name of a log file
-to use for logged profile data. The argument \var{lineevents} specifies whether
-to generate events for every source line, or just on function call/return. It
-defaults to 0 (only log function call/return). The argument \var{linetimings}
-specifies whether to record timing information. It defaults to 1 (store timing
+\begin{classdesc}{Profile}{logfile\optional{,
+ lineevents\code{=0}\optional{,
+ linetimings\code{=1}}}}
+The profiler object. The argument \var{logfile} is the name of a log
+file to use for logged profile data. The argument \var{lineevents}
+specifies whether to generate events for every source line, or just on
+function call/return. It defaults to \code{0} (only log function
+call/return). The argument \var{linetimings} specifies whether to
+record timing information. It defaults to \code{1} (store timing
information).
-
\end{classdesc}
+
\subsection{Profile Objects \label{hotshot-objects}}
Profile objects have the following methods:
@@ -38,22 +38,19 @@
\begin{methoddesc}{close}{}
Close the logfile and terminate the profiler.
\end{methoddesc}
-
-%
+
\begin{methoddesc}{fileno}{}
Return the file descriptor of the profiler's log file.
\end{methoddesc}
\begin{methoddesc}{run}{cmd}
-Profile an exec-compatible string in the script environment.
-
-The globals from the \module{__main__} module are used as
+Profile an \keyword{exec}-compatible string in the script environment.
+The globals from the \refmodule[main]{__main__} module are used as
both the globals and locals for the script.
\end{methoddesc}
\begin{methoddesc}{runcall}{func, *args, **keywords}
Profile a single call of a callable.
-
Additional positional and keyword arguments may be passed
along; the result of the call is returned, and exceptions are
allowed to propogate cleanly, while ensuring that profiling is
@@ -62,8 +59,7 @@
\begin{methoddesc}{runctx}{cmd, globals, locals}
-Evaluate an exec-compatible string in a specific environment.
-
+Evaluate an \keyword{exec}-compatible string in a specific environment.
The string is compiled before profiling begins.
\end{methoddesc}
@@ -75,32 +71,33 @@
Stop the profiler.
\end{methoddesc}
-\subsection{Using hotshot data}
-\declaremodule{standard}{hotshot.stats}
+\subsection{Using hotshot data}
+
+\declaremodule{standard}{hotshot.stats}
\modulesynopsis{Statistical analysis for Hotshot}
\versionadded{2.2}
-This module loads hotshot profiling data into the standard \module{pstats}
+This module loads hotshot profiling data into the standard \module{pstats}
Stats objects.
\begin{funcdesc}{load}{filename}
-Load hotshot data from \var{filename}. Returns an instance
+Load hotshot data from \var{filename}. Returns an instance
of the \class{pstats.Stats} class.
\end{funcdesc}
\begin{seealso}
- \seemodule{profile}{The profile module's \class{Stats} class }
+ \seemodule{profile}{The \module{profile} module's \class{Stats} class}
\end{seealso}
+
\subsection{Example Usage \label{hotshot-example}}
-Note that this example runs the python "benchmark" pystones. It can
+Note that this example runs the python ``benchmark'' pystones. It can
take some time to run, and will produce large output files.
\begin{verbatim}
-
>>> import hotshot, hotshot.stats, test.pystone
>>> prof = hotshot.Profile("stones.prof")
>>> benchtime, stones = prof.runcall(test.pystone.pystones)
@@ -120,7 +117,4 @@
.
.
.
-
\end{verbatim}
-
-
diff --git a/Doc/lib/libtimeit.tex b/Doc/lib/libtimeit.tex
index 34b21f7..bde25f8 100644
--- a/Doc/lib/libtimeit.tex
+++ b/Doc/lib/libtimeit.tex
@@ -4,36 +4,36 @@
\declaremodule{standard}{timeit}
\modulesynopsis{Measure the execution time of small code snippets.}
+\versionadded{2.3}
\index{Benchmarking}
\index{Performance}
-\versionadded{2.3}
+This module provides a simple way to time small bits of Python code.
+It has both command line as well as callable interfaces. It avoids a
+number of common traps for measuring execution times. See also Tim
+Peters' introduction to the ``Algorithms'' chapter in the
+\citetitle{Python Cookbook}, published by O'Reilly.
-This module provides a simple way to time small bits of Python code. It has
-both command line as well as callable interfaces. It avoids a number of
-common traps for measuring execution times. See also Tim Peters'
-introduction to the Algorithms chapter in the ``Python Cookbook'', published
-by O'Reilly.
+The module defines the following public class:
-The module interface defines the following public class:
-
-\begin{classdesc}{Timer}{\optional{stmt='pass'
- \optional{, setup='pass'
- \optional{, timer=<timer function>}}}}
+\begin{classdesc}{Timer}{\optional{stmt=\code{'pass'}
+ \optional{, setup=\code{'pass'}
+ \optional{, timer=<timer function>}}}}
Class for timing execution speed of small code snippets.
-The constructor takes a statement to be timed, an additional statement used
-for setup, and a timer function. Both statements default to 'pass'; the
-timer function is platform-dependent (see the module doc string).
+The constructor takes a statement to be timed, an additional statement
+used for setup, and a timer function. Both statements default to
+\code{'pass'}; the timer function is platform-dependent (see the
+module doc string). The statements may contain newlines, as long as
+they don't contain multi-line string literals.
-To measure the execution time of the first statement, use the timeit()
-method. The repeat() method is a convenience to call timeit() multiple
-times and return a list of results.
+To measure the execution time of the first statement, use the
+\method{timeit()} method. The \method{repeat()} method is a
+convenience to call \method{timeit()} multiple times and return a list
+of results.
+\end{classdesc}
-The statements may contain newlines, as long as they don't contain
-multi-line string literals.
-
-\begin{methoddesc}{print_exc}{\optional{file=None}}
+\begin{methoddesc}{print_exc}{\optional{file=\constant{None}}}
Helper to print a traceback from the timed code.
Typical use:
@@ -48,20 +48,21 @@
The advantage over the standard traceback is that source lines in the
compiled template will be displayed.
-
-The optional file argument directs where the traceback is sent; it defaults
-to \code{sys.stderr}.
+The optional \var{file} argument directs where the traceback is sent;
+it defaults to \code{sys.stderr}.
\end{methoddesc}
-\begin{methoddesc}{repeat}{\optional{repeat=3\optional{, number=1000000}}}
+\begin{methoddesc}{repeat}{\optional{repeat\code{=3}\optional{,
+ number\code{=1000000}}}}
Call \method{timeit()} a few times.
-This is a convenience function that calls the \method{timeit()} repeatedly,
-returning a list of results. The first argument specifies how many times to
-call \function{timeit()}. The second argument specifies the \code{number}
-argument for \function{timeit()}.
+This is a convenience function that calls the \method{timeit()}
+repeatedly, returning a list of results. The first argument specifies
+how many times to call \method{timeit()}. The second argument
+specifies the \var{number} argument for \function{timeit()}.
-Note: it's tempting to calculate mean and standard deviation from the result
+\begin{notice}
+It's tempting to calculate mean and standard deviation from the result
vector and report these. However, this is not very useful. In a typical
case, the lowest value gives a lower bound for how fast your machine can run
the given code snippet; higher values in the result vector are typically not
@@ -70,25 +71,26 @@
probably the only number you should be interested in. After that, you
should look at the entire vector and apply common sense rather than
statistics.
+\end{notice}
\end{methoddesc}
-\begin{methoddesc}{timeit}{\optional{number=1000000}}
-Time \code{number} executions of the main statement.
-
-To be precise, this executes the setup statement once, and then returns the
-time it takes to execute the main statement a number of times, as a float
-measured in seconds. The argument is the number of times through the loop,
-defaulting to one million. The main statement, the setup statement and the
-timer function to be used are passed to the constructor.
+\begin{methoddesc}{timeit}{\optional{number\code{=1000000}}}
+Time \var{number} executions of the main statement.
+This executes the setup statement once, and then
+returns the time it takes to execute the main statement a number of
+times, measured in seconds as a float. The argument is the number of
+times through the loop, defaulting to one million. The main
+statement, the setup statement and the timer function to be used are
+passed to the constructor.
\end{methoddesc}
-\end{classdesc}
+
\subsection{Command Line Interface}
When called as a program from the command line, the following form is used:
\begin{verbatim}
- python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
+python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
\end{verbatim}
where the following options are understood:
@@ -97,55 +99,64 @@
\item[-n N/--number=N] how many times to execute 'statement'
\item[-r N/--repeat=N] how many times to repeat the timer (default 3)
\item[-s S/--setup=S] statement to be executed once initially (default
-'pass')
-\item[-t/--time] use time.time() (default on all platforms but Windows)
-\item[-c/--clock] use time.clock() (default on Windows)
+\code{'pass'})
+\item[-t/--time] use \function{time.time()}
+(default on all platforms but Windows)
+\item[-c/--clock] use \function{time.clock()} (default on Windows)
\item[-v/--verbose] print raw timing results; repeat for more digits
-precision
+precision
\item[-h/--help] print a short usage message and exit
\end{description}
-A multi-line statement may be given by specifying each line as a separate
-statement argument; indented lines are possible by enclosing an argument in
-quotes and using leading spaces. Multiple -s options are treated similarly.
+A multi-line statement may be given by specifying each line as a
+separate statement argument; indented lines are possible by enclosing
+an argument in quotes and using leading spaces. Multiple
+\programopt{-s} options are treated similarly.
-If -n is not given, a suitable number of loops is calculated by trying
-successive powers of 10 until the total time is at least 0.2 seconds.
+If \programopt{-n} is not given, a suitable number of loops is
+calculated by trying successive powers of 10 until the total time is
+at least 0.2 seconds.
-The default timer function is platform dependent. On Windows, clock() has
-microsecond granularity but time()'s granularity is 1/60th of a second; on
-Unix, clock() has 1/100th of a second granularity and time() is much more
-precise. On either platform, the default timer functions measures wall
-clock time, not the CPU time. This means that other processes running on
-the same computer may interfere with the timing. The best thing to do when
-accurate timing is necessary is to repeat the timing a few times and use the
-best time. The -r option is good for this; the default of 3 repetitions is
-probably enough in most cases. On Unix, you can use clock() to measure CPU
-time.
+The default timer function is platform dependent. On Windows,
+\function{time.clock()} has microsecond granularity but
+\function{time.time()}'s granularity is 1/60th of a second; on \UNIX,
+\function{time.clock()} has 1/100th of a second granularity and
+\function{time.time()} is much more precise. On either platform, the
+default timer functions measures wall clock time, not the CPU time.
+This means that other processes running on the same computer may
+interfere with the timing. The best thing to do when accurate timing
+is necessary is to repeat the timing a few times and use the best
+time. The \programopt{-r} option is good for this; the default of 3
+repetitions is probably enough in most cases. On \UNIX, you can use
+\function{time.clock()} to measure CPU time.
-Note: there is a certain baseline overhead associated with executing a pass
-statement. The code here doesn't try to hide it, but you should be aware of
-it. The baseline overhead can be measured by invoking the program without
-arguments.
+\begin{notice}
+ There is a certain baseline overhead associated with executing a
+ pass statement. The code here doesn't try to hide it, but you
+ should be aware of it. The baseline overhead can be measured by
+ invoking the program without arguments.
+\end{notice}
-The baseline overhead differs between Python versions! Also, to fairly
-compare older Python versions to Python 2.3, you may want to use python -O
-for the older versions to avoid timing SET_LINENO instructions.
+The baseline overhead differs between Python versions! Also, to
+fairly compare older Python versions to Python 2.3, you may want to
+use Python's \programopt{-O} option for the older versions to avoid
+timing \code{SET_LINENO} instructions.
\subsection{Examples}
-Here are two example sessions (one using the command line, one using the
-module interface) that compare the cost of using \function{hasattr()}
-vs. try/except to test for missing and present object attributes.
+Here are two example sessions (one using the command line, one using
+the module interface) that compare the cost of using
+\function{hasattr()} vs. \keyword{try}/\keyword{except} to test for
+missing and present object attributes.
\begin{verbatim}
-\% timeit.py 'try:' ' str.__nonzero__' 'except AttributeError:' ' pass'
+% timeit.py 'try:' ' str.__nonzero__' 'except AttributeError:' ' pass'
100000 loops, best of 3: 15.7 usec per loop
-\% timeit.py 'if hasattr(str, "__nonzero__"): pass'
+% timeit.py 'if hasattr(str, "__nonzero__"): pass'
100000 loops, best of 3: 4.26 usec per loop
-\% timeit.py 'try:' ' int.__nonzero__' 'except AttributeError:' ' pass'
+% timeit.py 'try:' ' int.__nonzero__' 'except AttributeError:' ' pass'
1000000 loops, best of 3: 1.43 usec per loop
-\% timeit.py 'if hasattr(int, "__nonzero__"): pass'
+% timeit.py 'if hasattr(int, "__nonzero__"): pass'
100000 loops, best of 3: 2.23 usec per loop
\end{verbatim}
@@ -153,9 +164,9 @@
>>> import timeit
>>> s = """\
... try:
-... str.__nonzero__
+... str.__nonzero__
... except AttributeError:
-... pass
+... pass
... """
>>> t = timeit.Timer(stmt=s)
>>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)
@@ -168,9 +179,9 @@
4.85 usec/pass
>>> s = """\
... try:
-... int.__nonzero__
+... int.__nonzero__
... except AttributeError:
-... pass
+... pass
... """
>>> t = timeit.Timer(stmt=s)
>>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000)