From fcd845a7edba3ce1302bf1ea8360aa9b4b387fb3 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Wed, 9 Apr 2003 04:06:37 +0000 Subject: [PATCH] Lots of small markup adjustments. --- Doc/lib/libhotshot.tex | 58 +++++++-------- Doc/lib/libtimeit.tex | 165 ++++++++++++++++++++++------------------- 2 files changed, 114 insertions(+), 109 deletions(-) diff --git a/Doc/lib/libhotshot.tex b/Doc/lib/libhotshot.tex index 9c2513d8c85..05bc067ed1a 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 @@ Add an arbitrary labelled value to the profile output. \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 @@ disabled on the way out. \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 @@ Start the profiler. 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 @@ take some time to run, and will produce large output files. . . . - \end{verbatim} - - diff --git a/Doc/lib/libtimeit.tex b/Doc/lib/libtimeit.tex index 34b21f75bb9..bde25f8f07b 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=}}}} +\begin{classdesc}{Timer}{\optional{stmt=\code{'pass'} + \optional{, setup=\code{'pass'} + \optional{, timer=}}}} 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 @@ Typical use: 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 @@ with your timing accuracy. So the \function{min()} of the result is 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 @@ where the following options are understood: \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 @@ vs. try/except to test for missing and present object attributes. >>> 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 @@ vs. try/except to test for missing and present object attributes. 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)