[Python-checkins] python/dist/src/Doc/lib libhotshot.tex,1.3,1.4 libtimeit.tex,1.1,1.2
fdrake@users.sourceforge.net
fdrake@users.sourceforge.net
Tue, 08 Apr 2003 21:06:39 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv18713/lib
Modified Files:
libhotshot.tex libtimeit.tex
Log Message:
Lots of small markup adjustments.
Index: libhotshot.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libhotshot.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** libhotshot.tex 9 Apr 2003 03:03:46 -0000 1.3
--- libhotshot.tex 9 Apr 2003 04:06:37 -0000 1.4
***************
*** 3,31 ****
\declaremodule{standard}{hotshot}
\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.
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.
!
! \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
information).
-
\end{classdesc}
\subsection{Profile Objects \label{hotshot-objects}}
--- 3,31 ----
\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}
! 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 \refmodule{profile} module.
! \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}}
***************
*** 39,44 ****
Close the logfile and terminate the profiler.
\end{methoddesc}
!
! %
\begin{methoddesc}{fileno}{}
Return the file descriptor of the profiler's log file.
--- 39,43 ----
Close the logfile and terminate the profiler.
\end{methoddesc}
!
\begin{methoddesc}{fileno}{}
Return the file descriptor of the profiler's log file.
***************
*** 46,52 ****
\begin{methoddesc}{run}{cmd}
! Profile an exec-compatible string in the script environment.
!
! The globals from the \module{__main__} module are used as
both the globals and locals for the script.
\end{methoddesc}
--- 45,50 ----
\begin{methoddesc}{run}{cmd}
! 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}
***************
*** 54,58 ****
\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
--- 52,55 ----
***************
*** 63,68 ****
\begin{methoddesc}{runctx}{cmd, globals, locals}
! Evaluate an exec-compatible string in a specific environment.
!
The string is compiled before profiling begins.
\end{methoddesc}
--- 60,64 ----
\begin{methoddesc}{runctx}{cmd, globals, locals}
! Evaluate an \keyword{exec}-compatible string in a specific environment.
The string is compiled before profiling begins.
\end{methoddesc}
***************
*** 76,105 ****
\end{methoddesc}
\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}
Stats objects.
\begin{funcdesc}{load}{filename}
! 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 }
\end{seealso}
\subsection{Example Usage \label{hotshot-example}}
! 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")
--- 72,102 ----
\end{methoddesc}
+
\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}
Stats objects.
\begin{funcdesc}{load}{filename}
! Load hotshot data from \var{filename}. Returns an instance
of the \class{pstats.Stats} class.
\end{funcdesc}
\begin{seealso}
! \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
take some time to run, and will produce large output files.
\begin{verbatim}
>>> import hotshot, hotshot.stats, test.pystone
>>> prof = hotshot.Profile("stones.prof")
***************
*** 121,126 ****
.
.
-
\end{verbatim}
-
-
--- 118,120 ----
Index: libtimeit.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libtimeit.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** libtimeit.tex 9 Apr 2003 01:38:53 -0000 1.1
--- libtimeit.tex 9 Apr 2003 04:06:37 -0000 1.2
***************
*** 5,38 ****
\modulesynopsis{Measure the execution time of small code snippets.}
\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 ``Python Cookbook'', published
! by O'Reilly.
! The module interface defines the following public class:
! \begin{classdesc}{Timer}{\optional{stmt='pass'
! \optional{, setup='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).
!
! 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.
! The statements may contain newlines, as long as they don't contain
! multi-line string literals.
! \begin{methoddesc}{print_exc}{\optional{file=None}}
Helper to print a traceback from the timed code.
--- 5,38 ----
\modulesynopsis{Measure the execution time of small code snippets.}
+ \versionadded{2.3}
\index{Benchmarking}
\index{Performance}
! 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.
! The module defines the following public class:
! \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
! \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
! \method{timeit()} method. The \method{repeat()} method is a
! convenience to call \method{timeit()} multiple times and return a list
! of results.
! \end{classdesc}
! \begin{methoddesc}{print_exc}{\optional{file=\constant{None}}}
Helper to print a traceback from the timed code.
***************
*** 49,66 ****
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}.
\end{methoddesc}
! \begin{methoddesc}{repeat}{\optional{repeat=3\optional{, number=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()}.
! Note: 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
--- 49,67 ----
The advantage over the standard traceback is that source lines in the
compiled template will be displayed.
! The optional \var{file} argument directs where the traceback is sent;
! it defaults to \code{sys.stderr}.
\end{methoddesc}
! \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 \method{timeit()}. The second argument
! specifies the \var{number} argument for \function{timeit()}.
! \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
***************
*** 71,86 ****
should look at the entire vector and apply common sense rather than
statistics.
\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.
\end{methoddesc}
! \end{classdesc}
\subsection{Command Line Interface}
--- 72,88 ----
should look at the entire vector and apply common sense rather than
statistics.
+ \end{notice}
\end{methoddesc}
! \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}
!
\subsection{Command Line Interface}
***************
*** 89,93 ****
\begin{verbatim}
! python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
\end{verbatim}
--- 91,95 ----
\begin{verbatim}
! python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
\end{verbatim}
***************
*** 98,150 ****
\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)
\item[-v/--verbose] print raw timing results; repeat for more digits
! 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.
! 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.
! 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.
! 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.
! 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.
\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.
\begin{verbatim}
! \% 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'
100000 loops, best of 3: 4.26 usec per loop
! \% 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'
100000 loops, best of 3: 2.23 usec per loop
\end{verbatim}
--- 100,161 ----
\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
! \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
\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
! \programopt{-s} options are treated similarly.
! 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,
! \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.
! \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'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. \keyword{try}/\keyword{except} to test for
! missing and present object attributes.
\begin{verbatim}
! % 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'
100000 loops, best of 3: 4.26 usec per loop
! % 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'
100000 loops, best of 3: 2.23 usec per loop
\end{verbatim}
***************
*** 154,160 ****
>>> s = """\
... try:
! ... str.__nonzero__
... except AttributeError:
! ... pass
... """
>>> t = timeit.Timer(stmt=s)
--- 165,171 ----
>>> s = """\
... try:
! ... str.__nonzero__
... except AttributeError:
! ... pass
... """
>>> t = timeit.Timer(stmt=s)
***************
*** 169,175 ****
>>> s = """\
... try:
! ... int.__nonzero__
... except AttributeError:
! ... pass
... """
>>> t = timeit.Timer(stmt=s)
--- 180,186 ----
>>> s = """\
... try:
! ... int.__nonzero__
... except AttributeError:
! ... pass
... """
>>> t = timeit.Timer(stmt=s)