blob: a85fa3e30b6fb5e4b68ef33175d93d0db17bb837 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001
2:mod:`timeit` --- Measure execution time of small code snippets
3===============================================================
4
5.. module:: timeit
6 :synopsis: Measure the execution time of small code snippets.
7
8
Georg Brandl116aa622007-08-15 14:28:22 +00009.. index::
10 single: Benchmarking
11 single: Performance
12
13This module provides a simple way to time small bits of Python code. It has both
14command line as well as callable interfaces. It avoids a number of common traps
15for measuring execution times. See also Tim Peters' introduction to the
16"Algorithms" chapter in the Python Cookbook, published by O'Reilly.
17
18The module defines the following public class:
19
20
21.. class:: Timer([stmt='pass' [, setup='pass' [, timer=<timer function>]]])
22
23 Class for timing execution speed of small code snippets.
24
25 The constructor takes a statement to be timed, an additional statement used for
26 setup, and a timer function. Both statements default to ``'pass'``; the timer
Benjamin Peterson0289b152009-06-28 17:22:03 +000027 function is platform-dependent (see the module doc string). *stmt* and *setup*
28 may also contain multiple statements separated by ``;`` or newlines, as long as
29 they don't contain multi-line string literals.
Georg Brandl116aa622007-08-15 14:28:22 +000030
31 To measure the execution time of the first statement, use the :meth:`timeit`
32 method. The :meth:`repeat` method is a convenience to call :meth:`timeit`
33 multiple times and return a list of results.
34
Georg Brandl55ac8f02007-09-01 13:51:09 +000035 The *stmt* and *setup* parameters can also take objects that are callable
36 without arguments. This will embed calls to them in a timer function that
37 will then be executed by :meth:`timeit`. Note that the timing overhead is a
38 little larger in this case because of the extra function calls.
Georg Brandl116aa622007-08-15 14:28:22 +000039
40
41.. method:: Timer.print_exc([file=None])
42
43 Helper to print a traceback from the timed code.
44
45 Typical use::
46
47 t = Timer(...) # outside the try/except
48 try:
49 t.timeit(...) # or t.repeat(...)
50 except:
51 t.print_exc()
52
53 The advantage over the standard traceback is that source lines in the compiled
54 template will be displayed. The optional *file* argument directs where the
55 traceback is sent; it defaults to ``sys.stderr``.
56
57
58.. method:: Timer.repeat([repeat=3 [, number=1000000]])
59
60 Call :meth:`timeit` a few times.
61
62 This is a convenience function that calls the :meth:`timeit` repeatedly,
63 returning a list of results. The first argument specifies how many times to
64 call :meth:`timeit`. The second argument specifies the *number* argument for
65 :func:`timeit`.
66
67 .. note::
68
69 It's tempting to calculate mean and standard deviation from the result vector
70 and report these. However, this is not very useful. In a typical case, the
71 lowest value gives a lower bound for how fast your machine can run the given
72 code snippet; higher values in the result vector are typically not caused by
73 variability in Python's speed, but by other processes interfering with your
74 timing accuracy. So the :func:`min` of the result is probably the only number
75 you should be interested in. After that, you should look at the entire vector
76 and apply common sense rather than statistics.
77
78
79.. method:: Timer.timeit([number=1000000])
80
81 Time *number* executions of the main statement. This executes the setup
82 statement once, and then returns the time it takes to execute the main statement
83 a number of times, measured in seconds as a float. The argument is the number
84 of times through the loop, defaulting to one million. The main statement, the
85 setup statement and the timer function to be used are passed to the constructor.
86
87 .. note::
88
Christian Heimesd8654cf2007-12-02 15:22:16 +000089 By default, :meth:`timeit` temporarily turns off :term:`garbage collection`
90 during the timing. The advantage of this approach is that it makes
91 independent timings more comparable. This disadvantage is that GC may be
92 an important component of the performance of the function being measured.
93 If so, GC can be re-enabled as the first statement in the *setup* string.
94 For example::
Georg Brandl116aa622007-08-15 14:28:22 +000095
96 timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
97
Georg Brandl116aa622007-08-15 14:28:22 +000098
Georg Brandle6bcc912008-05-12 18:05:20 +000099The module also defines two convenience functions:
Georg Brandl116aa622007-08-15 14:28:22 +0000100
101.. function:: repeat(stmt[, setup[, timer[, repeat=3 [, number=1000000]]]])
102
103 Create a :class:`Timer` instance with the given statement, setup code and timer
104 function and run its :meth:`repeat` method with the given repeat count and
105 *number* executions.
106
Georg Brandl116aa622007-08-15 14:28:22 +0000107
108.. function:: timeit(stmt[, setup[, timer[, number=1000000]]])
109
110 Create a :class:`Timer` instance with the given statement, setup code and timer
111 function and run its :meth:`timeit` method with *number* executions.
112
Georg Brandl116aa622007-08-15 14:28:22 +0000113
114Command Line Interface
115----------------------
116
117When called as a program from the command line, the following form is used::
118
119 python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
120
121where the following options are understood:
122
123-n N/:option:`--number=N`
124 how many times to execute 'statement'
125
126-r N/:option:`--repeat=N`
127 how many times to repeat the timer (default 3)
128
129-s S/:option:`--setup=S`
130 statement to be executed once initially (default ``'pass'``)
131
132-t/:option:`--time`
133 use :func:`time.time` (default on all platforms but Windows)
134
135-c/:option:`--clock`
136 use :func:`time.clock` (default on Windows)
137
138-v/:option:`--verbose`
139 print raw timing results; repeat for more digits precision
140
141-h/:option:`--help`
142 print a short usage message and exit
143
144A multi-line statement may be given by specifying each line as a separate
145statement argument; indented lines are possible by enclosing an argument in
146quotes and using leading spaces. Multiple :option:`-s` options are treated
147similarly.
148
149If :option:`-n` is not given, a suitable number of loops is calculated by trying
150successive powers of 10 until the total time is at least 0.2 seconds.
151
152The default timer function is platform dependent. On Windows,
153:func:`time.clock` has microsecond granularity but :func:`time.time`'s
154granularity is 1/60th of a second; on Unix, :func:`time.clock` has 1/100th of a
155second granularity and :func:`time.time` is much more precise. On either
156platform, the default timer functions measure wall clock time, not the CPU time.
157This means that other processes running on the same computer may interfere with
158the timing. The best thing to do when accurate timing is necessary is to repeat
159the timing a few times and use the best time. The :option:`-r` option is good
160for this; the default of 3 repetitions is probably enough in most cases. On
161Unix, you can use :func:`time.clock` to measure CPU time.
162
163.. note::
164
165 There is a certain baseline overhead associated with executing a pass statement.
166 The code here doesn't try to hide it, but you should be aware of it. The
167 baseline overhead can be measured by invoking the program without arguments.
168
169The baseline overhead differs between Python versions! Also, to fairly compare
170older Python versions to Python 2.3, you may want to use Python's :option:`-O`
171option for the older versions to avoid timing ``SET_LINENO`` instructions.
172
173
174Examples
175--------
176
177Here are two example sessions (one using the command line, one using the module
178interface) that compare the cost of using :func:`hasattr` vs.
179:keyword:`try`/:keyword:`except` to test for missing and present object
180attributes. ::
181
182 % timeit.py 'try:' ' str.__bool__' 'except AttributeError:' ' pass'
183 100000 loops, best of 3: 15.7 usec per loop
184 % timeit.py 'if hasattr(str, "__bool__"): pass'
185 100000 loops, best of 3: 4.26 usec per loop
186 % timeit.py 'try:' ' int.__bool__' 'except AttributeError:' ' pass'
187 1000000 loops, best of 3: 1.43 usec per loop
188 % timeit.py 'if hasattr(int, "__bool__"): pass'
189 100000 loops, best of 3: 2.23 usec per loop
190
191::
192
193 >>> import timeit
194 >>> s = """\
195 ... try:
196 ... str.__bool__
197 ... except AttributeError:
198 ... pass
199 ... """
200 >>> t = timeit.Timer(stmt=s)
Collin Winterc79461b2007-09-01 23:34:30 +0000201 >>> print("%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000))
Georg Brandl116aa622007-08-15 14:28:22 +0000202 17.09 usec/pass
203 >>> s = """\
204 ... if hasattr(str, '__bool__'): pass
205 ... """
206 >>> t = timeit.Timer(stmt=s)
Collin Winterc79461b2007-09-01 23:34:30 +0000207 >>> print("%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000))
Georg Brandl116aa622007-08-15 14:28:22 +0000208 4.85 usec/pass
209 >>> s = """\
210 ... try:
211 ... int.__bool__
212 ... except AttributeError:
213 ... pass
214 ... """
215 >>> t = timeit.Timer(stmt=s)
Collin Winterc79461b2007-09-01 23:34:30 +0000216 >>> print("%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000))
Georg Brandl116aa622007-08-15 14:28:22 +0000217 1.97 usec/pass
218 >>> s = """\
219 ... if hasattr(int, '__bool__'): pass
220 ... """
221 >>> t = timeit.Timer(stmt=s)
Collin Winterc79461b2007-09-01 23:34:30 +0000222 >>> print("%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000))
Georg Brandl116aa622007-08-15 14:28:22 +0000223 3.15 usec/pass
224
225To give the :mod:`timeit` module access to functions you define, you can pass a
226``setup`` parameter which contains an import statement::
227
228 def test():
229 "Stupid test function"
Collin Winterc79461b2007-09-01 23:34:30 +0000230 L = [i for i in range(100)]
Georg Brandl116aa622007-08-15 14:28:22 +0000231
232 if __name__=='__main__':
233 from timeit import Timer
234 t = Timer("test()", "from __main__ import test")
Collin Winterc79461b2007-09-01 23:34:30 +0000235 print(t.timeit())
Georg Brandl116aa622007-08-15 14:28:22 +0000236