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