Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 1 | """Framework for measuring execution time for small code snippets. |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 2 | |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 3 | This module avoids a number of common traps for measuring execution |
| 4 | times. See also Tim Peters' introduction to the Algorithms chapter in |
| 5 | the Python Cookbook, published by O'Reilly. |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 6 | |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 7 | Library usage: see the Timer class. |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 8 | |
| 9 | Command line usage: |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 10 | python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement] |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 11 | |
| 12 | Options: |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 13 | -n/--number N: how many times to execute 'statement' (default: see below) |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 14 | -r/--repeat N: how many times to repeat the timer (default 1) |
| 15 | -s/--setup S: statements executed once before 'statement' (default 'pass') |
| 16 | -t/--time: use time.time() (default on Unix) |
| 17 | -c/--clock: use time.clock() (default on Windows) |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 18 | -h/--help: print this usage message and exit |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 19 | statement: statement to be timed (default 'pass') |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 20 | |
| 21 | A multi-line statement may be given by specifying each line as a |
| 22 | separate argument; indented lines are possible by enclosing an |
| 23 | argument in quotes and using leading spaces. |
| 24 | |
| 25 | If -n is not given, a suitable number of loops is calculated by trying |
| 26 | successive powers of 10 until the total time is at least 0.2 seconds. |
| 27 | |
| 28 | The difference in default timer function is because on Windows, |
| 29 | clock() has microsecond granularity but time()'s granularity is 1/60th |
| 30 | of a second; on Unix, clock() has 1/100th of a second granularity and |
| 31 | time() is much more precise. On either platform, the default timer |
| 32 | functions measures wall clock time, not the CPU time. This means that |
| 33 | other processes running on the same computer may interfere with the |
| 34 | timing. The best thing to do when accurate timing is necessary is to |
| 35 | repeat the timing a few times and use the best time; the -r option is |
| 36 | good for this. On Unix, you can use clock() to measure CPU time. |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 37 | |
| 38 | Note: there is a certain baseline overhead associated with executing a |
| 39 | pass statement. The code here doesn't try to hide it, but you should |
| 40 | be aware of it (especially when comparing different versions of |
| 41 | Python). The baseline overhead is measured by invoking the program |
| 42 | without arguments. |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 43 | """ |
| 44 | |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 45 | # To use this module with older versions of Python, the dependency on |
| 46 | # the itertools module is easily removed; in the template, instead of |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 47 | # itertools.repeat(None, number), use [None]*number. It's barely |
| 48 | # slower. Note: the baseline overhead, measured by the default |
| 49 | # invocation, differs for older Python versions! Also, to fairly |
| 50 | # compare older Python versions to Python 2.3, you may want to use |
| 51 | # python -O for the older versions to avoid timing SET_LINENO |
| 52 | # instructions. |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 53 | |
Guido van Rossum | 5573541 | 2003-03-06 16:11:17 +0000 | [diff] [blame^] | 54 | # XXX Maybe for convenience of comparing with previous Python versions, |
| 55 | # itertools.repeat() should not be used at all? |
| 56 | |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 57 | import sys |
| 58 | import math |
| 59 | import time |
| 60 | import itertools |
| 61 | |
| 62 | __all__ = ["Timer"] |
| 63 | |
| 64 | default_number = 1000000 |
| 65 | default_repeat = 10 |
| 66 | |
| 67 | if sys.platform == "win32": |
| 68 | # On Windows, the best timer is time.clock() |
| 69 | default_timer = time.clock |
| 70 | else: |
| 71 | # On most other platforms the best timer is time.time() |
| 72 | default_timer = time.time |
| 73 | |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 74 | # Don't change the indentation of the template; the reindent() calls |
| 75 | # in Timer.__init__() depend on setup being indented 4 spaces and stmt |
| 76 | # being indented 8 spaces. |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 77 | template = """ |
| 78 | def inner(number, timer): |
| 79 | %(setup)s |
| 80 | seq = itertools.repeat(None, number) |
| 81 | t0 = timer() |
| 82 | for i in seq: |
| 83 | %(stmt)s |
| 84 | t1 = timer() |
| 85 | return t1-t0 |
| 86 | """ |
| 87 | |
| 88 | def reindent(src, indent): |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 89 | """Helper to reindent a multi-line statement.""" |
Guido van Rossum | e05dcce | 2003-03-06 13:09:09 +0000 | [diff] [blame] | 90 | return src.replace("\n", "\n" + " "*indent) |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 91 | |
| 92 | class Timer: |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 93 | """Class for timing execution speed of small code snippets. |
| 94 | |
| 95 | The constructor takes a statement to be timed, an additional |
| 96 | statement used for setup, and a timer function. Both statements |
| 97 | default to 'pass'; the timer function is platform-dependent (see |
| 98 | module doc string). |
| 99 | |
| 100 | To measure the execution time of the first statement, use the |
| 101 | timeit() method. The repeat() method is a convenience to call |
| 102 | timeit() multiple times and return a list of results. |
| 103 | |
| 104 | The statements may contain newlines, as long as they don't contain |
| 105 | multi-line string literals. |
| 106 | """ |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 107 | |
| 108 | def __init__(self, stmt="pass", setup="pass", timer=default_timer): |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 109 | """Constructor. See class doc string.""" |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 110 | self.timer = timer |
| 111 | stmt = reindent(stmt, 8) |
| 112 | setup = reindent(setup, 4) |
| 113 | src = template % {'stmt': stmt, 'setup': setup} |
| 114 | code = compile(src, "<src>", "exec") |
| 115 | ns = {} |
| 116 | exec code in globals(), ns |
| 117 | self.inner = ns["inner"] |
| 118 | |
| 119 | def timeit(self, number=default_number): |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 120 | """Time 'number' executions of the main statement. |
| 121 | |
| 122 | To be precise, this executes the setup statement once, and |
| 123 | then returns the time it takes to execute the main statement |
| 124 | a number of times, as a float measured in seconds. The |
| 125 | argument is the number of times through the loop, defaulting |
| 126 | to one million. The main statement, the setup statement and |
| 127 | the timer function to be used are passed to the constructor. |
| 128 | """ |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 129 | return self.inner(number, self.timer) |
| 130 | |
| 131 | def repeat(self, repeat=default_repeat, number=default_number): |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 132 | """Call timer() a few times. |
| 133 | |
| 134 | This is a convenience function that calls the timer() |
| 135 | repeatedly, returning a list of results. The first argument |
| 136 | specifies how many times to call timer(), defaulting to 10; |
| 137 | the second argument specifies the timer argument, defaulting |
| 138 | to one million. |
Guido van Rossum | 5573541 | 2003-03-06 16:11:17 +0000 | [diff] [blame^] | 139 | |
| 140 | Note: it's tempting to calculate mean and standard deviation |
| 141 | from the result vector and report these. However, this is not |
| 142 | very useful. In a typical case, the lowest value gives a |
| 143 | lower bound for how fast your machine can run the given code |
| 144 | snippet; higher values in the result vector are typically not |
| 145 | caused by variability in Python's speed, but by other |
| 146 | processes interfering with your timing accuracy. So the min() |
| 147 | of the result is probably the only number you should be |
| 148 | interested in. After that, you should look at the entire |
| 149 | vector and apply common sense rather than statistics. |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 150 | """ |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 151 | r = [] |
| 152 | for i in range(repeat): |
| 153 | t = self.timeit(number) |
| 154 | r.append(t) |
| 155 | return r |
| 156 | |
| 157 | def main(args=None): |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 158 | """Main program, used when run as a script. |
| 159 | |
| 160 | The optional argument specifies the command line to be parsed, |
| 161 | defaulting to sys.argv[1:]. |
| 162 | |
| 163 | The return value is an exit code to be passed to sys.exit(); it |
| 164 | may be None to indicate success. |
| 165 | """ |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 166 | if args is None: |
| 167 | args = sys.argv[1:] |
| 168 | import getopt |
| 169 | try: |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 170 | opts, args = getopt.getopt(args, "n:s:r:tch", |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 171 | ["number=", "setup=", "repeat=", |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 172 | "time", "clock", "help"]) |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 173 | except getopt.error, err: |
| 174 | print err |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 175 | print "use -h/--help for command line help" |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 176 | return 2 |
| 177 | timer = default_timer |
| 178 | stmt = "\n".join(args) or "pass" |
| 179 | number = 0 # auto-determine |
| 180 | setup = "pass" |
| 181 | repeat = 1 |
| 182 | for o, a in opts: |
| 183 | if o in ("-n", "--number"): |
| 184 | number = int(a) |
| 185 | if o in ("-s", "--setup"): |
| 186 | setup = a |
| 187 | if o in ("-r", "--repeat"): |
| 188 | repeat = int(a) |
| 189 | if repeat <= 0: |
| 190 | repeat = 1 |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 191 | if o in ("-t", "--time"): |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 192 | timer = time.time |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 193 | if o in ("-c", "--clock"): |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 194 | timer = time.clock |
Guido van Rossum | e8577b7 | 2003-03-06 03:02:10 +0000 | [diff] [blame] | 195 | if o in ("-h", "--help"): |
| 196 | print __doc__, |
| 197 | return 0 |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 198 | t = Timer(stmt, setup, timer) |
| 199 | if number == 0: |
| 200 | # determine number so that 0.2 <= total time < 2.0 |
| 201 | for i in range(1, 10): |
| 202 | number = 10**i |
| 203 | x = t.timeit(number) |
| 204 | if x >= 0.2: |
| 205 | break |
| 206 | r = t.repeat(repeat, number) |
| 207 | best = min(r) |
| 208 | print "%d loops," % number, |
| 209 | usec = best * 1e6 / number |
| 210 | if repeat > 1: |
| 211 | print "best of %d: %.3f usec" % (repeat, usec) |
| 212 | else: |
| 213 | print "time: %.3f usec" % usec |
Guido van Rossum | b7ab600 | 2003-03-06 02:32:19 +0000 | [diff] [blame] | 214 | return None |
Guido van Rossum | b3f09d4 | 2003-03-05 23:31:58 +0000 | [diff] [blame] | 215 | |
| 216 | if __name__ == "__main__": |
| 217 | sys.exit(main()) |