1#!/usr/local/bin/python3.10 2 3"""Tool for measuring execution time of small code snippets. 4 5This 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. 8 9Library usage: see the Timer class. 10 11Command line usage: 12 python timeit.py [-n N] [-r N] [-s S] [-p] [-h] [--] [statement] 13 14Options: 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 5) 17 -s/--setup S: statement to be executed once initially (default 'pass'). 18 Execution time of this setup statement is NOT timed. 19 -p/--process: use time.process_time() (default is time.perf_counter()) 20 -v/--verbose: print raw timing results; repeat for more digits precision 21 -u/--unit: set the output time unit (nsec, usec, msec, or sec) 22 -h/--help: print this usage message and exit 23 --: separate options from statement, use when statement starts with - 24 statement: statement to be timed (default 'pass') 25 26A multi-line statement may be given by specifying each line as a 27separate argument; indented lines are possible by enclosing an 28argument in quotes and using leading spaces. Multiple -s options are 29treated similarly. 30 31If -n is not given, a suitable number of loops is calculated by trying 32increasing numbers from the sequence 1, 2, 5, 10, 20, 50, ... until the 33total time is at least 0.2 seconds. 34 35Note: there is a certain baseline overhead associated with executing a 36pass statement. It differs between versions. The code here doesn't try 37to hide it, but you should be aware of it. The baseline overhead can be 38measured by invoking the program without arguments. 39 40Classes: 41 42 Timer 43 44Functions: 45 46 timeit(string, string) -> float 47 repeat(string, string) -> list 48 default_timer() -> float 49 50""" 51 52import gc 53import sys 54import time 55import itertools 56 57__all__ = ["Timer", "timeit", "repeat", "default_timer"] 58 59dummy_src_name = "<timeit-src>" 60default_number = 1000000 61default_repeat = 5 62default_timer = time.perf_counter 63 64_globals = globals 65 66# Don't change the indentation of the template; the reindent() calls 67# in Timer.__init__() depend on setup being indented 4 spaces and stmt 68# being indented 8 spaces. 69template = """ 70def inner(_it, _timer{init}): 71 {setup} 72 _t0 = _timer() 73 for _i in _it: 74 {stmt} 75 pass 76 _t1 = _timer() 77 return _t1 - _t0 78""" 79 80def reindent(src, indent): 81 """Helper to reindent a multi-line statement.""" 82 return src.replace("\n", "\n" + " "*indent) 83 84class Timer: 85 """Class for timing execution speed of small code snippets. 86 87 The constructor takes a statement to be timed, an additional 88 statement used for setup, and a timer function. Both statements 89 default to 'pass'; the timer function is platform-dependent (see 90 module doc string). If 'globals' is specified, the code will be 91 executed within that namespace (as opposed to inside timeit's 92 namespace). 93 94 To measure the execution time of the first statement, use the 95 timeit() method. The repeat() method is a convenience to call 96 timeit() multiple times and return a list of results. 97 98 The statements may contain newlines, as long as they don't contain 99 multi-line string literals. 100 """ 101 102 def __init__(self, stmt="pass", setup="pass", timer=default_timer, 103 globals=None): 104 """Constructor. See class doc string.""" 105 self.timer = timer 106 local_ns = {} 107 global_ns = _globals() if globals is None else globals 108 init = '' 109 if isinstance(setup, str): 110 # Check that the code can be compiled outside a function 111 compile(setup, dummy_src_name, "exec") 112 stmtprefix = setup + '\n' 113 setup = reindent(setup, 4) 114 elif callable(setup): 115 local_ns['_setup'] = setup 116 init += ', _setup=_setup' 117 stmtprefix = '' 118 setup = '_setup()' 119 else: 120 raise ValueError("setup is neither a string nor callable") 121 if isinstance(stmt, str): 122 # Check that the code can be compiled outside a function 123 compile(stmtprefix + stmt, dummy_src_name, "exec") 124 stmt = reindent(stmt, 8) 125 elif callable(stmt): 126 local_ns['_stmt'] = stmt 127 init += ', _stmt=_stmt' 128 stmt = '_stmt()' 129 else: 130 raise ValueError("stmt is neither a string nor callable") 131 src = template.format(stmt=stmt, setup=setup, init=init) 132 self.src = src # Save for traceback display 133 code = compile(src, dummy_src_name, "exec") 134 exec(code, global_ns, local_ns) 135 self.inner = local_ns["inner"] 136 137 def print_exc(self, file=None): 138 """Helper to print a traceback from the timed code. 139 140 Typical use: 141 142 t = Timer(...) # outside the try/except 143 try: 144 t.timeit(...) # or t.repeat(...) 145 except: 146 t.print_exc() 147 148 The advantage over the standard traceback is that source lines 149 in the compiled template will be displayed. 150 151 The optional file argument directs where the traceback is 152 sent; it defaults to sys.stderr. 153 """ 154 import linecache, traceback 155 if self.src is not None: 156 linecache.cache[dummy_src_name] = (len(self.src), 157 None, 158 self.src.split("\n"), 159 dummy_src_name) 160 # else the source is already stored somewhere else 161 162 traceback.print_exc(file=file) 163 164 def timeit(self, number=default_number): 165 """Time 'number' executions of the main statement. 166 167 To be precise, this executes the setup statement once, and 168 then returns the time it takes to execute the main statement 169 a number of times, as a float measured in seconds. The 170 argument is the number of times through the loop, defaulting 171 to one million. The main statement, the setup statement and 172 the timer function to be used are passed to the constructor. 173 """ 174 it = itertools.repeat(None, number) 175 gcold = gc.isenabled() 176 gc.disable() 177 try: 178 timing = self.inner(it, self.timer) 179 finally: 180 if gcold: 181 gc.enable() 182 return timing 183 184 def repeat(self, repeat=default_repeat, number=default_number): 185 """Call timeit() a few times. 186 187 This is a convenience function that calls the timeit() 188 repeatedly, returning a list of results. The first argument 189 specifies how many times to call timeit(), defaulting to 5; 190 the second argument specifies the timer argument, defaulting 191 to one million. 192 193 Note: it's tempting to calculate mean and standard deviation 194 from the result vector and report these. However, this is not 195 very useful. In a typical case, the lowest value gives a 196 lower bound for how fast your machine can run the given code 197 snippet; higher values in the result vector are typically not 198 caused by variability in Python's speed, but by other 199 processes interfering with your timing accuracy. So the min() 200 of the result is probably the only number you should be 201 interested in. After that, you should look at the entire 202 vector and apply common sense rather than statistics. 203 """ 204 r = [] 205 for i in range(repeat): 206 t = self.timeit(number) 207 r.append(t) 208 return r 209 210 def autorange(self, callback=None): 211 """Return the number of loops and time taken so that total time >= 0.2. 212 213 Calls the timeit method with increasing numbers from the sequence 214 1, 2, 5, 10, 20, 50, ... until the time taken is at least 0.2 215 second. Returns (number, time_taken). 216 217 If *callback* is given and is not None, it will be called after 218 each trial with two arguments: ``callback(number, time_taken)``. 219 """ 220 i = 1 221 while True: 222 for j in 1, 2, 5: 223 number = i * j 224 time_taken = self.timeit(number) 225 if callback: 226 callback(number, time_taken) 227 if time_taken >= 0.2: 228 return (number, time_taken) 229 i *= 10 230 231def timeit(stmt="pass", setup="pass", timer=default_timer, 232 number=default_number, globals=None): 233 """Convenience function to create Timer object and call timeit method.""" 234 return Timer(stmt, setup, timer, globals).timeit(number) 235 236def repeat(stmt="pass", setup="pass", timer=default_timer, 237 repeat=default_repeat, number=default_number, globals=None): 238 """Convenience function to create Timer object and call repeat method.""" 239 return Timer(stmt, setup, timer, globals).repeat(repeat, number) 240 241def main(args=None, *, _wrap_timer=None): 242 """Main program, used when run as a script. 243 244 The optional 'args' argument specifies the command line to be parsed, 245 defaulting to sys.argv[1:]. 246 247 The return value is an exit code to be passed to sys.exit(); it 248 may be None to indicate success. 249 250 When an exception happens during timing, a traceback is printed to 251 stderr and the return value is 1. Exceptions at other times 252 (including the template compilation) are not caught. 253 254 '_wrap_timer' is an internal interface used for unit testing. If it 255 is not None, it must be a callable that accepts a timer function 256 and returns another timer function (used for unit testing). 257 """ 258 if args is None: 259 args = sys.argv[1:] 260 import getopt 261 try: 262 opts, args = getopt.getopt(args, "n:u:s:r:tcpvh", 263 ["number=", "setup=", "repeat=", 264 "time", "clock", "process", 265 "verbose", "unit=", "help"]) 266 except getopt.error as err: 267 print(err) 268 print("use -h/--help for command line help") 269 return 2 270 271 timer = default_timer 272 stmt = "\n".join(args) or "pass" 273 number = 0 # auto-determine 274 setup = [] 275 repeat = default_repeat 276 verbose = 0 277 time_unit = None 278 units = {"nsec": 1e-9, "usec": 1e-6, "msec": 1e-3, "sec": 1.0} 279 precision = 3 280 for o, a in opts: 281 if o in ("-n", "--number"): 282 number = int(a) 283 if o in ("-s", "--setup"): 284 setup.append(a) 285 if o in ("-u", "--unit"): 286 if a in units: 287 time_unit = a 288 else: 289 print("Unrecognized unit. Please select nsec, usec, msec, or sec.", 290 file=sys.stderr) 291 return 2 292 if o in ("-r", "--repeat"): 293 repeat = int(a) 294 if repeat <= 0: 295 repeat = 1 296 if o in ("-p", "--process"): 297 timer = time.process_time 298 if o in ("-v", "--verbose"): 299 if verbose: 300 precision += 1 301 verbose += 1 302 if o in ("-h", "--help"): 303 print(__doc__, end=' ') 304 return 0 305 setup = "\n".join(setup) or "pass" 306 307 # Include the current directory, so that local imports work (sys.path 308 # contains the directory of this script, rather than the current 309 # directory) 310 import os 311 sys.path.insert(0, os.curdir) 312 if _wrap_timer is not None: 313 timer = _wrap_timer(timer) 314 315 t = Timer(stmt, setup, timer) 316 if number == 0: 317 # determine number so that 0.2 <= total time < 2.0 318 callback = None 319 if verbose: 320 def callback(number, time_taken): 321 msg = "{num} loop{s} -> {secs:.{prec}g} secs" 322 plural = (number != 1) 323 print(msg.format(num=number, s='s' if plural else '', 324 secs=time_taken, prec=precision)) 325 try: 326 number, _ = t.autorange(callback) 327 except: 328 t.print_exc() 329 return 1 330 331 if verbose: 332 print() 333 334 try: 335 raw_timings = t.repeat(repeat, number) 336 except: 337 t.print_exc() 338 return 1 339 340 def format_time(dt): 341 unit = time_unit 342 343 if unit is not None: 344 scale = units[unit] 345 else: 346 scales = [(scale, unit) for unit, scale in units.items()] 347 scales.sort(reverse=True) 348 for scale, unit in scales: 349 if dt >= scale: 350 break 351 352 return "%.*g %s" % (precision, dt / scale, unit) 353 354 if verbose: 355 print("raw times: %s" % ", ".join(map(format_time, raw_timings))) 356 print() 357 timings = [dt / number for dt in raw_timings] 358 359 best = min(timings) 360 print("%d loop%s, best of %d: %s per loop" 361 % (number, 's' if number != 1 else '', 362 repeat, format_time(best))) 363 364 best = min(timings) 365 worst = max(timings) 366 if worst >= best * 4: 367 import warnings 368 warnings.warn_explicit("The test results are likely unreliable. " 369 "The worst time (%s) was more than four times " 370 "slower than the best time (%s)." 371 % (format_time(worst), format_time(best)), 372 UserWarning, '', 0) 373 return None 374 375if __name__ == "__main__": 376 sys.exit(main()) 377