]>
Commit | Line | Data |
---|---|---|
4710c53d | 1 | #! /usr/bin/env python\r |
2 | \r | |
3 | """Tool for measuring execution time of small code snippets.\r | |
4 | \r | |
5 | This module avoids a number of common traps for measuring execution\r | |
6 | times. See also Tim Peters' introduction to the Algorithms chapter in\r | |
7 | the Python Cookbook, published by O'Reilly.\r | |
8 | \r | |
9 | Library usage: see the Timer class.\r | |
10 | \r | |
11 | Command line usage:\r | |
12 | python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [--] [statement]\r | |
13 | \r | |
14 | Options:\r | |
15 | -n/--number N: how many times to execute 'statement' (default: see below)\r | |
16 | -r/--repeat N: how many times to repeat the timer (default 3)\r | |
17 | -s/--setup S: statement to be executed once initially (default 'pass')\r | |
18 | -t/--time: use time.time() (default on Unix)\r | |
19 | -c/--clock: use time.clock() (default on Windows)\r | |
20 | -v/--verbose: print raw timing results; repeat for more digits precision\r | |
21 | -h/--help: print this usage message and exit\r | |
22 | --: separate options from statement, use when statement starts with -\r | |
23 | statement: statement to be timed (default 'pass')\r | |
24 | \r | |
25 | A multi-line statement may be given by specifying each line as a\r | |
26 | separate argument; indented lines are possible by enclosing an\r | |
27 | argument in quotes and using leading spaces. Multiple -s options are\r | |
28 | treated similarly.\r | |
29 | \r | |
30 | If -n is not given, a suitable number of loops is calculated by trying\r | |
31 | successive powers of 10 until the total time is at least 0.2 seconds.\r | |
32 | \r | |
33 | The difference in default timer function is because on Windows,\r | |
34 | clock() has microsecond granularity but time()'s granularity is 1/60th\r | |
35 | of a second; on Unix, clock() has 1/100th of a second granularity and\r | |
36 | time() is much more precise. On either platform, the default timer\r | |
37 | functions measure wall clock time, not the CPU time. This means that\r | |
38 | other processes running on the same computer may interfere with the\r | |
39 | timing. The best thing to do when accurate timing is necessary is to\r | |
40 | repeat the timing a few times and use the best time. The -r option is\r | |
41 | good for this; the default of 3 repetitions is probably enough in most\r | |
42 | cases. On Unix, you can use clock() to measure CPU time.\r | |
43 | \r | |
44 | Note: there is a certain baseline overhead associated with executing a\r | |
45 | pass statement. The code here doesn't try to hide it, but you should\r | |
46 | be aware of it. The baseline overhead can be measured by invoking the\r | |
47 | program without arguments.\r | |
48 | \r | |
49 | The baseline overhead differs between Python versions! Also, to\r | |
50 | fairly compare older Python versions to Python 2.3, you may want to\r | |
51 | use python -O for the older versions to avoid timing SET_LINENO\r | |
52 | instructions.\r | |
53 | """\r | |
54 | \r | |
55 | import gc\r | |
56 | import sys\r | |
57 | import time\r | |
58 | try:\r | |
59 | import itertools\r | |
60 | except ImportError:\r | |
61 | # Must be an older Python version (see timeit() below)\r | |
62 | itertools = None\r | |
63 | \r | |
64 | __all__ = ["Timer"]\r | |
65 | \r | |
66 | dummy_src_name = "<timeit-src>"\r | |
67 | default_number = 1000000\r | |
68 | default_repeat = 3\r | |
69 | \r | |
70 | if sys.platform == "win32":\r | |
71 | # On Windows, the best timer is time.clock()\r | |
72 | default_timer = time.clock\r | |
73 | else:\r | |
74 | # On most other platforms the best timer is time.time()\r | |
75 | default_timer = time.time\r | |
76 | \r | |
77 | # Don't change the indentation of the template; the reindent() calls\r | |
78 | # in Timer.__init__() depend on setup being indented 4 spaces and stmt\r | |
79 | # being indented 8 spaces.\r | |
80 | template = """\r | |
81 | def inner(_it, _timer):\r | |
82 | %(setup)s\r | |
83 | _t0 = _timer()\r | |
84 | for _i in _it:\r | |
85 | %(stmt)s\r | |
86 | _t1 = _timer()\r | |
87 | return _t1 - _t0\r | |
88 | """\r | |
89 | \r | |
90 | def reindent(src, indent):\r | |
91 | """Helper to reindent a multi-line statement."""\r | |
92 | return src.replace("\n", "\n" + " "*indent)\r | |
93 | \r | |
94 | def _template_func(setup, func):\r | |
95 | """Create a timer function. Used if the "statement" is a callable."""\r | |
96 | def inner(_it, _timer, _func=func):\r | |
97 | setup()\r | |
98 | _t0 = _timer()\r | |
99 | for _i in _it:\r | |
100 | _func()\r | |
101 | _t1 = _timer()\r | |
102 | return _t1 - _t0\r | |
103 | return inner\r | |
104 | \r | |
105 | class Timer:\r | |
106 | """Class for timing execution speed of small code snippets.\r | |
107 | \r | |
108 | The constructor takes a statement to be timed, an additional\r | |
109 | statement used for setup, and a timer function. Both statements\r | |
110 | default to 'pass'; the timer function is platform-dependent (see\r | |
111 | module doc string).\r | |
112 | \r | |
113 | To measure the execution time of the first statement, use the\r | |
114 | timeit() method. The repeat() method is a convenience to call\r | |
115 | timeit() multiple times and return a list of results.\r | |
116 | \r | |
117 | The statements may contain newlines, as long as they don't contain\r | |
118 | multi-line string literals.\r | |
119 | """\r | |
120 | \r | |
121 | def __init__(self, stmt="pass", setup="pass", timer=default_timer):\r | |
122 | """Constructor. See class doc string."""\r | |
123 | self.timer = timer\r | |
124 | ns = {}\r | |
125 | if isinstance(stmt, basestring):\r | |
126 | stmt = reindent(stmt, 8)\r | |
127 | if isinstance(setup, basestring):\r | |
128 | setup = reindent(setup, 4)\r | |
129 | src = template % {'stmt': stmt, 'setup': setup}\r | |
130 | elif hasattr(setup, '__call__'):\r | |
131 | src = template % {'stmt': stmt, 'setup': '_setup()'}\r | |
132 | ns['_setup'] = setup\r | |
133 | else:\r | |
134 | raise ValueError("setup is neither a string nor callable")\r | |
135 | self.src = src # Save for traceback display\r | |
136 | code = compile(src, dummy_src_name, "exec")\r | |
137 | exec code in globals(), ns\r | |
138 | self.inner = ns["inner"]\r | |
139 | elif hasattr(stmt, '__call__'):\r | |
140 | self.src = None\r | |
141 | if isinstance(setup, basestring):\r | |
142 | _setup = setup\r | |
143 | def setup():\r | |
144 | exec _setup in globals(), ns\r | |
145 | elif not hasattr(setup, '__call__'):\r | |
146 | raise ValueError("setup is neither a string nor callable")\r | |
147 | self.inner = _template_func(setup, stmt)\r | |
148 | else:\r | |
149 | raise ValueError("stmt is neither a string nor callable")\r | |
150 | \r | |
151 | def print_exc(self, file=None):\r | |
152 | """Helper to print a traceback from the timed code.\r | |
153 | \r | |
154 | Typical use:\r | |
155 | \r | |
156 | t = Timer(...) # outside the try/except\r | |
157 | try:\r | |
158 | t.timeit(...) # or t.repeat(...)\r | |
159 | except:\r | |
160 | t.print_exc()\r | |
161 | \r | |
162 | The advantage over the standard traceback is that source lines\r | |
163 | in the compiled template will be displayed.\r | |
164 | \r | |
165 | The optional file argument directs where the traceback is\r | |
166 | sent; it defaults to sys.stderr.\r | |
167 | """\r | |
168 | import linecache, traceback\r | |
169 | if self.src is not None:\r | |
170 | linecache.cache[dummy_src_name] = (len(self.src),\r | |
171 | None,\r | |
172 | self.src.split("\n"),\r | |
173 | dummy_src_name)\r | |
174 | # else the source is already stored somewhere else\r | |
175 | \r | |
176 | traceback.print_exc(file=file)\r | |
177 | \r | |
178 | def timeit(self, number=default_number):\r | |
179 | """Time 'number' executions of the main statement.\r | |
180 | \r | |
181 | To be precise, this executes the setup statement once, and\r | |
182 | then returns the time it takes to execute the main statement\r | |
183 | a number of times, as a float measured in seconds. The\r | |
184 | argument is the number of times through the loop, defaulting\r | |
185 | to one million. The main statement, the setup statement and\r | |
186 | the timer function to be used are passed to the constructor.\r | |
187 | """\r | |
188 | if itertools:\r | |
189 | it = itertools.repeat(None, number)\r | |
190 | else:\r | |
191 | it = [None] * number\r | |
192 | gcold = gc.isenabled()\r | |
193 | gc.disable()\r | |
194 | timing = self.inner(it, self.timer)\r | |
195 | if gcold:\r | |
196 | gc.enable()\r | |
197 | return timing\r | |
198 | \r | |
199 | def repeat(self, repeat=default_repeat, number=default_number):\r | |
200 | """Call timeit() a few times.\r | |
201 | \r | |
202 | This is a convenience function that calls the timeit()\r | |
203 | repeatedly, returning a list of results. The first argument\r | |
204 | specifies how many times to call timeit(), defaulting to 3;\r | |
205 | the second argument specifies the timer argument, defaulting\r | |
206 | to one million.\r | |
207 | \r | |
208 | Note: it's tempting to calculate mean and standard deviation\r | |
209 | from the result vector and report these. However, this is not\r | |
210 | very useful. In a typical case, the lowest value gives a\r | |
211 | lower bound for how fast your machine can run the given code\r | |
212 | snippet; higher values in the result vector are typically not\r | |
213 | caused by variability in Python's speed, but by other\r | |
214 | processes interfering with your timing accuracy. So the min()\r | |
215 | of the result is probably the only number you should be\r | |
216 | interested in. After that, you should look at the entire\r | |
217 | vector and apply common sense rather than statistics.\r | |
218 | """\r | |
219 | r = []\r | |
220 | for i in range(repeat):\r | |
221 | t = self.timeit(number)\r | |
222 | r.append(t)\r | |
223 | return r\r | |
224 | \r | |
225 | def timeit(stmt="pass", setup="pass", timer=default_timer,\r | |
226 | number=default_number):\r | |
227 | """Convenience function to create Timer object and call timeit method."""\r | |
228 | return Timer(stmt, setup, timer).timeit(number)\r | |
229 | \r | |
230 | def repeat(stmt="pass", setup="pass", timer=default_timer,\r | |
231 | repeat=default_repeat, number=default_number):\r | |
232 | """Convenience function to create Timer object and call repeat method."""\r | |
233 | return Timer(stmt, setup, timer).repeat(repeat, number)\r | |
234 | \r | |
235 | def main(args=None):\r | |
236 | """Main program, used when run as a script.\r | |
237 | \r | |
238 | The optional argument specifies the command line to be parsed,\r | |
239 | defaulting to sys.argv[1:].\r | |
240 | \r | |
241 | The return value is an exit code to be passed to sys.exit(); it\r | |
242 | may be None to indicate success.\r | |
243 | \r | |
244 | When an exception happens during timing, a traceback is printed to\r | |
245 | stderr and the return value is 1. Exceptions at other times\r | |
246 | (including the template compilation) are not caught.\r | |
247 | """\r | |
248 | if args is None:\r | |
249 | args = sys.argv[1:]\r | |
250 | import getopt\r | |
251 | try:\r | |
252 | opts, args = getopt.getopt(args, "n:s:r:tcvh",\r | |
253 | ["number=", "setup=", "repeat=",\r | |
254 | "time", "clock", "verbose", "help"])\r | |
255 | except getopt.error, err:\r | |
256 | print err\r | |
257 | print "use -h/--help for command line help"\r | |
258 | return 2\r | |
259 | timer = default_timer\r | |
260 | stmt = "\n".join(args) or "pass"\r | |
261 | number = 0 # auto-determine\r | |
262 | setup = []\r | |
263 | repeat = default_repeat\r | |
264 | verbose = 0\r | |
265 | precision = 3\r | |
266 | for o, a in opts:\r | |
267 | if o in ("-n", "--number"):\r | |
268 | number = int(a)\r | |
269 | if o in ("-s", "--setup"):\r | |
270 | setup.append(a)\r | |
271 | if o in ("-r", "--repeat"):\r | |
272 | repeat = int(a)\r | |
273 | if repeat <= 0:\r | |
274 | repeat = 1\r | |
275 | if o in ("-t", "--time"):\r | |
276 | timer = time.time\r | |
277 | if o in ("-c", "--clock"):\r | |
278 | timer = time.clock\r | |
279 | if o in ("-v", "--verbose"):\r | |
280 | if verbose:\r | |
281 | precision += 1\r | |
282 | verbose += 1\r | |
283 | if o in ("-h", "--help"):\r | |
284 | print __doc__,\r | |
285 | return 0\r | |
286 | setup = "\n".join(setup) or "pass"\r | |
287 | # Include the current directory, so that local imports work (sys.path\r | |
288 | # contains the directory of this script, rather than the current\r | |
289 | # directory)\r | |
290 | import os\r | |
291 | sys.path.insert(0, os.curdir)\r | |
292 | t = Timer(stmt, setup, timer)\r | |
293 | if number == 0:\r | |
294 | # determine number so that 0.2 <= total time < 2.0\r | |
295 | for i in range(1, 10):\r | |
296 | number = 10**i\r | |
297 | try:\r | |
298 | x = t.timeit(number)\r | |
299 | except:\r | |
300 | t.print_exc()\r | |
301 | return 1\r | |
302 | if verbose:\r | |
303 | print "%d loops -> %.*g secs" % (number, precision, x)\r | |
304 | if x >= 0.2:\r | |
305 | break\r | |
306 | try:\r | |
307 | r = t.repeat(repeat, number)\r | |
308 | except:\r | |
309 | t.print_exc()\r | |
310 | return 1\r | |
311 | best = min(r)\r | |
312 | if verbose:\r | |
313 | print "raw times:", " ".join(["%.*g" % (precision, x) for x in r])\r | |
314 | print "%d loops," % number,\r | |
315 | usec = best * 1e6 / number\r | |
316 | if usec < 1000:\r | |
317 | print "best of %d: %.*g usec per loop" % (repeat, precision, usec)\r | |
318 | else:\r | |
319 | msec = usec / 1000\r | |
320 | if msec < 1000:\r | |
321 | print "best of %d: %.*g msec per loop" % (repeat, precision, msec)\r | |
322 | else:\r | |
323 | sec = msec / 1000\r | |
324 | print "best of %d: %.*g sec per loop" % (repeat, precision, sec)\r | |
325 | return None\r | |
326 | \r | |
327 | if __name__ == "__main__":\r | |
328 | sys.exit(main())\r |