blob: 5ce9b4ac47f29fc48544b2cea5b99016adad6886 [file] [log] [blame]
Skip Montanarocfd55502003-04-08 19:49:40 +00001#! /usr/bin/env python
2
Guido van Rossum6e31aad2003-03-07 01:33:18 +00003"""Tool for measuring execution time of small code snippets.
Guido van Rossumb3f09d42003-03-05 23:31:58 +00004
Guido van Rossumb7ab6002003-03-06 02:32:19 +00005This module avoids a number of common traps for measuring execution
6times. See also Tim Peters' introduction to the Algorithms chapter in
7the Python Cookbook, published by O'Reilly.
Guido van Rossumb3f09d42003-03-05 23:31:58 +00008
Guido van Rossumb7ab6002003-03-06 02:32:19 +00009Library usage: see the Timer class.
Guido van Rossumb3f09d42003-03-05 23:31:58 +000010
11Command line usage:
Guido van Rossume8577b72003-03-06 03:02:10 +000012 python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement]
Guido van Rossumb3f09d42003-03-05 23:31:58 +000013
14Options:
Guido van Rossumb7ab6002003-03-06 02:32:19 +000015 -n/--number N: how many times to execute 'statement' (default: see below)
Guido van Rossum0070f002003-03-15 12:25:00 +000016 -r/--repeat N: how many times to repeat the timer (default 3)
Guido van Rossum6e31aad2003-03-07 01:33:18 +000017 -s/--setup S: statement to be executed once initially (default 'pass')
Guido van Rossumb3f09d42003-03-05 23:31:58 +000018 -t/--time: use time.time() (default on Unix)
19 -c/--clock: use time.clock() (default on Windows)
Guido van Rossum0070f002003-03-15 12:25:00 +000020 -v/--verbose: print raw timing results; repeat for more digits precision
Guido van Rossume8577b72003-03-06 03:02:10 +000021 -h/--help: print this usage message and exit
Guido van Rossumb3f09d42003-03-05 23:31:58 +000022 statement: statement to be timed (default 'pass')
Guido van Rossumb7ab6002003-03-06 02:32:19 +000023
24A multi-line statement may be given by specifying each line as a
25separate argument; indented lines are possible by enclosing an
Guido van Rossum6e31aad2003-03-07 01:33:18 +000026argument in quotes and using leading spaces. Multiple -s options are
27treated similarly.
Guido van Rossumb7ab6002003-03-06 02:32:19 +000028
29If -n is not given, a suitable number of loops is calculated by trying
30successive powers of 10 until the total time is at least 0.2 seconds.
31
32The difference in default timer function is because on Windows,
33clock() has microsecond granularity but time()'s granularity is 1/60th
34of a second; on Unix, clock() has 1/100th of a second granularity and
35time() is much more precise. On either platform, the default timer
Martin v. Löwis7bdc4842003-09-20 11:09:28 +000036functions measure wall clock time, not the CPU time. This means that
Guido van Rossumb7ab6002003-03-06 02:32:19 +000037other processes running on the same computer may interfere with the
38timing. The best thing to do when accurate timing is necessary is to
Guido van Rossum0070f002003-03-15 12:25:00 +000039repeat the timing a few times and use the best time. The -r option is
40good for this; the default of 3 repetitions is probably enough in most
41cases. On Unix, you can use clock() to measure CPU time.
Guido van Rossume8577b72003-03-06 03:02:10 +000042
43Note: there is a certain baseline overhead associated with executing a
44pass statement. The code here doesn't try to hide it, but you should
Guido van Rossum6e31aad2003-03-07 01:33:18 +000045be aware of it. The baseline overhead can be measured by invoking the
46program without arguments.
47
48The baseline overhead differs between Python versions! Also, to
49fairly compare older Python versions to Python 2.3, you may want to
50use python -O for the older versions to avoid timing SET_LINENO
51instructions.
Guido van Rossumb3f09d42003-03-05 23:31:58 +000052"""
53
Raymond Hettinger816ed1b2004-01-04 03:47:51 +000054import gc
Guido van Rossumb3f09d42003-03-05 23:31:58 +000055import sys
Guido van Rossumb3f09d42003-03-05 23:31:58 +000056import time
Guido van Rossum6e31aad2003-03-07 01:33:18 +000057try:
58 import itertools
59except ImportError:
60 # Must be an older Python version (see timeit() below)
61 itertools = None
Guido van Rossumb3f09d42003-03-05 23:31:58 +000062
63__all__ = ["Timer"]
64
Guido van Rossum538f1d82003-03-14 17:21:00 +000065dummy_src_name = "<timeit-src>"
Guido van Rossumb3f09d42003-03-05 23:31:58 +000066default_number = 1000000
Guido van Rossum0070f002003-03-15 12:25:00 +000067default_repeat = 3
Guido van Rossumb3f09d42003-03-05 23:31:58 +000068
69if sys.platform == "win32":
70 # On Windows, the best timer is time.clock()
71 default_timer = time.clock
72else:
73 # On most other platforms the best timer is time.time()
74 default_timer = time.time
75
Guido van Rossumb7ab6002003-03-06 02:32:19 +000076# Don't change the indentation of the template; the reindent() calls
77# in Timer.__init__() depend on setup being indented 4 spaces and stmt
78# being indented 8 spaces.
Guido van Rossumb3f09d42003-03-05 23:31:58 +000079template = """
Guido van Rossumdd42edc2003-03-21 14:54:19 +000080def inner(_it, _timer):
Guido van Rossumb3f09d42003-03-05 23:31:58 +000081 %(setup)s
Guido van Rossum538f1d82003-03-14 17:21:00 +000082 _t0 = _timer()
Guido van Rossumdd42edc2003-03-21 14:54:19 +000083 for _i in _it:
Guido van Rossumb3f09d42003-03-05 23:31:58 +000084 %(stmt)s
Guido van Rossum538f1d82003-03-14 17:21:00 +000085 _t1 = _timer()
86 return _t1 - _t0
Guido van Rossumb3f09d42003-03-05 23:31:58 +000087"""
88
89def reindent(src, indent):
Guido van Rossumb7ab6002003-03-06 02:32:19 +000090 """Helper to reindent a multi-line statement."""
Guido van Rossume05dcce2003-03-06 13:09:09 +000091 return src.replace("\n", "\n" + " "*indent)
Guido van Rossumb3f09d42003-03-05 23:31:58 +000092
Guido van Rossumd8faa362007-04-27 19:54:29 +000093def _template_func(setup, func):
94 """Create a timer function. Used if the "statement" is a callable."""
95 def inner(_it, _timer):
96 setup()
97 _t0 = _timer()
98 for _i in _it:
99 func()
100 _t1 = _timer()
101 return _t1 - _t0
102 return inner
103
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000104class Timer:
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000105 """Class for timing execution speed of small code snippets.
106
107 The constructor takes a statement to be timed, an additional
108 statement used for setup, and a timer function. Both statements
109 default to 'pass'; the timer function is platform-dependent (see
110 module doc string).
111
112 To measure the execution time of the first statement, use the
113 timeit() method. The repeat() method is a convenience to call
114 timeit() multiple times and return a list of results.
115
116 The statements may contain newlines, as long as they don't contain
117 multi-line string literals.
118 """
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000119
120 def __init__(self, stmt="pass", setup="pass", timer=default_timer):
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000121 """Constructor. See class doc string."""
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000122 self.timer = timer
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000123 ns = {}
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000124 if isinstance(stmt, str):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000125 stmt = reindent(stmt, 8)
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000126 if isinstance(setup, str):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000127 setup = reindent(setup, 4)
128 src = template % {'stmt': stmt, 'setup': setup}
Guido van Rossumd59da4b2007-05-22 18:11:13 +0000129 elif hasattr(setup, '__call__'):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000130 src = template % {'stmt': stmt, 'setup': '_setup()'}
131 ns['_setup'] = setup
132 else:
133 raise ValueError("setup is neither a string nor callable")
134 self.src = src # Save for traceback display
135 code = compile(src, dummy_src_name, "exec")
136 exec(code, globals(), ns)
137 self.inner = ns["inner"]
Guido van Rossumd59da4b2007-05-22 18:11:13 +0000138 elif hasattr(stmt, '__call__'):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000139 self.src = None
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000140 if isinstance(setup, str):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000141 _setup = setup
142 def setup():
143 exec(_setup, globals(), ns)
Guido van Rossumd59da4b2007-05-22 18:11:13 +0000144 elif not hasattr(setup, '__call__'):
Guido van Rossumd8faa362007-04-27 19:54:29 +0000145 raise ValueError("setup is neither a string nor callable")
146 self.inner = _template_func(setup, stmt)
147 else:
148 raise ValueError("stmt is neither a string nor callable")
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000149
Guido van Rossum538f1d82003-03-14 17:21:00 +0000150 def print_exc(self, file=None):
151 """Helper to print a traceback from the timed code.
152
153 Typical use:
154
155 t = Timer(...) # outside the try/except
156 try:
157 t.timeit(...) # or t.repeat(...)
158 except:
159 t.print_exc()
160
161 The advantage over the standard traceback is that source lines
162 in the compiled template will be displayed.
163
164 The optional file argument directs where the traceback is
165 sent; it defaults to sys.stderr.
166 """
167 import linecache, traceback
Guido van Rossumd8faa362007-04-27 19:54:29 +0000168 if self.src is not None:
169 linecache.cache[dummy_src_name] = (len(self.src),
170 None,
171 self.src.split("\n"),
172 dummy_src_name)
173 # else the source is already stored somewhere else
174
Guido van Rossum538f1d82003-03-14 17:21:00 +0000175 traceback.print_exc(file=file)
176
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000177 def timeit(self, number=default_number):
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000178 """Time 'number' executions of the main statement.
179
180 To be precise, this executes the setup statement once, and
181 then returns the time it takes to execute the main statement
182 a number of times, as a float measured in seconds. The
183 argument is the number of times through the loop, defaulting
184 to one million. The main statement, the setup statement and
185 the timer function to be used are passed to the constructor.
186 """
Guido van Rossum6e31aad2003-03-07 01:33:18 +0000187 if itertools:
Guido van Rossumdd42edc2003-03-21 14:54:19 +0000188 it = itertools.repeat(None, number)
Guido van Rossum6e31aad2003-03-07 01:33:18 +0000189 else:
Guido van Rossumdd42edc2003-03-21 14:54:19 +0000190 it = [None] * number
Raymond Hettinger816ed1b2004-01-04 03:47:51 +0000191 gcold = gc.isenabled()
192 gc.disable()
193 timing = self.inner(it, self.timer)
194 if gcold:
195 gc.enable()
196 return timing
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000197
198 def repeat(self, repeat=default_repeat, number=default_number):
Skip Montanarofb2a6cc2003-04-08 19:40:19 +0000199 """Call timeit() a few times.
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000200
Skip Montanarofb2a6cc2003-04-08 19:40:19 +0000201 This is a convenience function that calls the timeit()
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000202 repeatedly, returning a list of results. The first argument
Skip Montanarofb2a6cc2003-04-08 19:40:19 +0000203 specifies how many times to call timeit(), defaulting to 3;
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000204 the second argument specifies the timer argument, defaulting
205 to one million.
Guido van Rossum55735412003-03-06 16:11:17 +0000206
207 Note: it's tempting to calculate mean and standard deviation
208 from the result vector and report these. However, this is not
209 very useful. In a typical case, the lowest value gives a
210 lower bound for how fast your machine can run the given code
211 snippet; higher values in the result vector are typically not
212 caused by variability in Python's speed, but by other
213 processes interfering with your timing accuracy. So the min()
214 of the result is probably the only number you should be
215 interested in. After that, you should look at the entire
216 vector and apply common sense rather than statistics.
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000217 """
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000218 r = []
219 for i in range(repeat):
220 t = self.timeit(number)
221 r.append(t)
222 return r
223
Guido van Rossumd8faa362007-04-27 19:54:29 +0000224def timeit(stmt="pass", setup="pass", timer=default_timer,
225 number=default_number):
226 """Convenience function to create Timer object and call timeit method."""
227 return Timer(stmt, setup, timer).timeit(number)
228
229def repeat(stmt="pass", setup="pass", timer=default_timer,
230 repeat=default_repeat, number=default_number):
231 """Convenience function to create Timer object and call repeat method."""
232 return Timer(stmt, setup, timer).repeat(repeat, number)
233
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000234def main(args=None):
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000235 """Main program, used when run as a script.
236
237 The optional argument specifies the command line to be parsed,
238 defaulting to sys.argv[1:].
239
240 The return value is an exit code to be passed to sys.exit(); it
241 may be None to indicate success.
Guido van Rossum538f1d82003-03-14 17:21:00 +0000242
243 When an exception happens during timing, a traceback is printed to
244 stderr and the return value is 1. Exceptions at other times
245 (including the template compilation) are not caught.
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000246 """
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000247 if args is None:
248 args = sys.argv[1:]
249 import getopt
250 try:
Guido van Rossum0070f002003-03-15 12:25:00 +0000251 opts, args = getopt.getopt(args, "n:s:r:tcvh",
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000252 ["number=", "setup=", "repeat=",
Guido van Rossum0070f002003-03-15 12:25:00 +0000253 "time", "clock", "verbose", "help"])
Guido van Rossumb940e112007-01-10 16:19:56 +0000254 except getopt.error as err:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000255 print(err)
256 print("use -h/--help for command line help")
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000257 return 2
258 timer = default_timer
259 stmt = "\n".join(args) or "pass"
260 number = 0 # auto-determine
Guido van Rossum6e31aad2003-03-07 01:33:18 +0000261 setup = []
Guido van Rossum0070f002003-03-15 12:25:00 +0000262 repeat = default_repeat
263 verbose = 0
264 precision = 3
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000265 for o, a in opts:
266 if o in ("-n", "--number"):
267 number = int(a)
268 if o in ("-s", "--setup"):
Guido van Rossum6e31aad2003-03-07 01:33:18 +0000269 setup.append(a)
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000270 if o in ("-r", "--repeat"):
271 repeat = int(a)
272 if repeat <= 0:
273 repeat = 1
Guido van Rossume8577b72003-03-06 03:02:10 +0000274 if o in ("-t", "--time"):
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000275 timer = time.time
Guido van Rossume8577b72003-03-06 03:02:10 +0000276 if o in ("-c", "--clock"):
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000277 timer = time.clock
Guido van Rossum0070f002003-03-15 12:25:00 +0000278 if o in ("-v", "--verbose"):
279 if verbose:
280 precision += 1
281 verbose += 1
Guido van Rossume8577b72003-03-06 03:02:10 +0000282 if o in ("-h", "--help"):
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000283 print(__doc__, end=' ')
Guido van Rossume8577b72003-03-06 03:02:10 +0000284 return 0
Guido van Rossum6e31aad2003-03-07 01:33:18 +0000285 setup = "\n".join(setup) or "pass"
Raymond Hettinger22952a32003-05-20 04:59:56 +0000286 # Include the current directory, so that local imports work (sys.path
287 # contains the directory of this script, rather than the current
288 # directory)
289 import os
290 sys.path.insert(0, os.curdir)
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000291 t = Timer(stmt, setup, timer)
292 if number == 0:
293 # determine number so that 0.2 <= total time < 2.0
294 for i in range(1, 10):
295 number = 10**i
Guido van Rossum538f1d82003-03-14 17:21:00 +0000296 try:
297 x = t.timeit(number)
298 except:
299 t.print_exc()
300 return 1
Guido van Rossum0070f002003-03-15 12:25:00 +0000301 if verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000302 print("%d loops -> %.*g secs" % (number, precision, x))
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000303 if x >= 0.2:
304 break
Guido van Rossum538f1d82003-03-14 17:21:00 +0000305 try:
306 r = t.repeat(repeat, number)
307 except:
308 t.print_exc()
309 return 1
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000310 best = min(r)
Guido van Rossum0070f002003-03-15 12:25:00 +0000311 if verbose:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000312 print("raw times:", " ".join(["%.*g" % (precision, x) for x in r]))
313 print("%d loops," % number, end=' ')
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000314 usec = best * 1e6 / number
Guido van Rossum57172082003-10-20 23:38:28 +0000315 if usec < 1000:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000316 print("best of %d: %.*g usec per loop" % (repeat, precision, usec))
Guido van Rossum57172082003-10-20 23:38:28 +0000317 else:
318 msec = usec / 1000
319 if msec < 1000:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000320 print("best of %d: %.*g msec per loop" % (repeat, precision, msec))
Guido van Rossum57172082003-10-20 23:38:28 +0000321 else:
322 sec = msec / 1000
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000323 print("best of %d: %.*g sec per loop" % (repeat, precision, sec))
Guido van Rossumb7ab6002003-03-06 02:32:19 +0000324 return None
Guido van Rossumb3f09d42003-03-05 23:31:58 +0000325
326if __name__ == "__main__":
327 sys.exit(main())