1:mod:`timeit` --- Measure execution time of small code snippets 2=============================================================== 3 4.. module:: timeit 5 :synopsis: Measure the execution time of small code snippets. 6 7 8.. versionadded:: 2.3 9 10.. index:: 11 single: Benchmarking 12 single: Performance 13 14**Source code:** :source:`Lib/timeit.py` 15 16-------------- 17 18This module provides a simple way to time small bits of Python code. It has both 19a :ref:`timeit-command-line-interface` as well as a :ref:`callable <python-interface>` 20one. It avoids a number of common traps for measuring execution times. 21See also Tim Peters' introduction to the "Algorithms" chapter in the *Python 22Cookbook*, published by O'Reilly. 23 24 25Basic Examples 26-------------- 27 28The following example shows how the :ref:`timeit-command-line-interface` 29can be used to compare three different expressions: 30 31.. code-block:: sh 32 33 $ python -m timeit '"-".join(str(n) for n in range(100))' 34 10000 loops, best of 3: 40.3 usec per loop 35 $ python -m timeit '"-".join([str(n) for n in range(100)])' 36 10000 loops, best of 3: 33.4 usec per loop 37 $ python -m timeit '"-".join(map(str, range(100)))' 38 10000 loops, best of 3: 25.2 usec per loop 39 40This can be achieved from the :ref:`python-interface` with:: 41 42 >>> import timeit 43 >>> timeit.timeit('"-".join(str(n) for n in range(100))', number=10000) 44 0.8187260627746582 45 >>> timeit.timeit('"-".join([str(n) for n in range(100)])', number=10000) 46 0.7288308143615723 47 >>> timeit.timeit('"-".join(map(str, range(100)))', number=10000) 48 0.5858950614929199 49 50Note however that :mod:`timeit` will automatically determine the number of 51repetitions only when the command-line interface is used. In the 52:ref:`timeit-examples` section you can find more advanced examples. 53 54 55.. _python-interface: 56 57Python Interface 58---------------- 59 60The module defines three convenience functions and a public class: 61 62 63.. function:: timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000) 64 65 Create a :class:`Timer` instance with the given statement, *setup* code and 66 *timer* function and run its :meth:`.timeit` method with *number* executions. 67 68 .. versionadded:: 2.6 69 70 71.. function:: repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=3, number=1000000) 72 73 Create a :class:`Timer` instance with the given statement, *setup* code and 74 *timer* function and run its :meth:`.repeat` method with the given *repeat* 75 count and *number* executions. 76 77 .. versionadded:: 2.6 78 79 80.. function:: default_timer() 81 82 Define a default timer, in a platform-specific manner. On Windows, 83 :func:`time.clock` has microsecond granularity, but :func:`time.time`'s 84 granularity is 1/60th of a second. On Unix, :func:`time.clock` has 1/100th of 85 a second granularity, and :func:`time.time` is much more precise. On either 86 platform, :func:`default_timer` measures wall clock time, not the CPU 87 time. This means that other processes running on the same computer may 88 interfere with the timing. 89 90 91.. class:: Timer(stmt='pass', setup='pass', timer=<timer function>) 92 93 Class for timing execution speed of small code snippets. 94 95 The constructor takes a statement to be timed, an additional statement used 96 for setup, and a timer function. Both statements default to ``'pass'``; 97 the timer function is platform-dependent (see the module doc string). 98 *stmt* and *setup* may also contain multiple statements separated by ``;`` 99 or newlines, as long as they don't contain multi-line string literals. 100 101 To measure the execution time of the first statement, use the :meth:`.timeit` 102 method. The :meth:`.repeat` method is a convenience to call :meth:`.timeit` 103 multiple times and return a list of results. 104 105 .. versionchanged:: 2.6 106 The *stmt* and *setup* parameters can now also take objects that are 107 callable without arguments. This will embed calls to them in a timer 108 function that will then be executed by :meth:`.timeit`. Note that the 109 timing overhead is a little larger in this case because of the extra 110 function calls. 111 112 113 .. method:: Timer.timeit(number=1000000) 114 115 Time *number* executions of the main statement. This executes the setup 116 statement once, and then returns the time it takes to execute the main 117 statement a number of times, measured in seconds as a float. 118 The argument is the number of times through the loop, defaulting to one 119 million. The main statement, the setup statement and the timer function 120 to be used are passed to the constructor. 121 122 .. note:: 123 124 By default, :meth:`.timeit` temporarily turns off :term:`garbage 125 collection` during the timing. The advantage of this approach is that 126 it makes independent timings more comparable. This disadvantage is 127 that GC may be an important component of the performance of the 128 function being measured. If so, GC can be re-enabled as the first 129 statement in the *setup* string. For example:: 130 131 timeit.Timer('for i in xrange(10): oct(i)', 'gc.enable()').timeit() 132 133 134 .. method:: Timer.repeat(repeat=3, number=1000000) 135 136 Call :meth:`.timeit` a few times. 137 138 This is a convenience function that calls the :meth:`.timeit` repeatedly, 139 returning a list of results. The first argument specifies how many times 140 to call :meth:`.timeit`. The second argument specifies the *number* 141 argument for :meth:`.timeit`. 142 143 .. note:: 144 145 It's tempting to calculate mean and standard deviation from the result 146 vector and report these. However, this is not very useful. 147 In a typical case, the lowest value gives a lower bound for how fast 148 your machine can run the given code snippet; higher values in the 149 result vector are typically not caused by variability in Python's 150 speed, but by other processes interfering with your timing accuracy. 151 So the :func:`min` of the result is probably the only number you 152 should be interested in. After that, you should look at the entire 153 vector and apply common sense rather than statistics. 154 155 156 .. method:: Timer.print_exc(file=None) 157 158 Helper to print a traceback from the timed code. 159 160 Typical use:: 161 162 t = Timer(...) # outside the try/except 163 try: 164 t.timeit(...) # or t.repeat(...) 165 except: 166 t.print_exc() 167 168 The advantage over the standard traceback is that source lines in the 169 compiled template will be displayed. The optional *file* argument directs 170 where the traceback is sent; it defaults to :data:`sys.stderr`. 171 172 173.. _timeit-command-line-interface: 174 175Command-Line Interface 176---------------------- 177 178When called as a program from the command line, the following form is used:: 179 180 python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...] 181 182Where the following options are understood: 183 184.. program:: timeit 185 186.. cmdoption:: -n N, --number=N 187 188 how many times to execute 'statement' 189 190.. cmdoption:: -r N, --repeat=N 191 192 how many times to repeat the timer (default 3) 193 194.. cmdoption:: -s S, --setup=S 195 196 statement to be executed once initially (default ``pass``) 197 198.. cmdoption:: -t, --time 199 200 use :func:`time.time` (default on all platforms but Windows) 201 202.. cmdoption:: -c, --clock 203 204 use :func:`time.clock` (default on Windows) 205 206.. cmdoption:: -v, --verbose 207 208 print raw timing results; repeat for more digits precision 209 210.. cmdoption:: -h, --help 211 212 print a short usage message and exit 213 214A multi-line statement may be given by specifying each line as a separate 215statement argument; indented lines are possible by enclosing an argument in 216quotes and using leading spaces. Multiple :option:`-s` options are treated 217similarly. 218 219If :option:`-n` is not given, a suitable number of loops is calculated by trying 220successive powers of 10 until the total time is at least 0.2 seconds. 221 222:func:`default_timer` measurations can be affected by other programs running on 223the same machine, so 224the best thing to do when accurate timing is necessary is to repeat 225the timing a few times and use the best time. The :option:`-r` option is good 226for this; the default of 3 repetitions is probably enough in most cases. On 227Unix, you can use :func:`time.clock` to measure CPU time. 228 229.. note:: 230 231 There is a certain baseline overhead associated with executing a pass statement. 232 The code here doesn't try to hide it, but you should be aware of it. The 233 baseline overhead can be measured by invoking the program without arguments, and 234 it might differ between Python versions. Also, to fairly compare older Python 235 versions to Python 2.3, you may want to use Python's :option:`!-O` 236 option (see :ref:`Optimizations <using-on-optimizations>`) for 237 the older versions to avoid timing ``SET_LINENO`` instructions. 238 239 240.. _timeit-examples: 241 242Examples 243-------- 244 245It is possible to provide a setup statement that is executed only once at the beginning: 246 247.. code-block:: sh 248 249 $ python -m timeit -s 'text = "sample string"; char = "g"' 'char in text' 250 10000000 loops, best of 3: 0.0877 usec per loop 251 $ python -m timeit -s 'text = "sample string"; char = "g"' 'text.find(char)' 252 1000000 loops, best of 3: 0.342 usec per loop 253 254:: 255 256 >>> import timeit 257 >>> timeit.timeit('char in text', setup='text = "sample string"; char = "g"') 258 0.41440500499993504 259 >>> timeit.timeit('text.find(char)', setup='text = "sample string"; char = "g"') 260 1.7246671520006203 261 262The same can be done using the :class:`Timer` class and its methods:: 263 264 >>> import timeit 265 >>> t = timeit.Timer('char in text', setup='text = "sample string"; char = "g"') 266 >>> t.timeit() 267 0.3955516149999312 268 >>> t.repeat() 269 [0.40193588800002544, 0.3960157959998014, 0.39594301399984033] 270 271 272The following examples show how to time expressions that contain multiple lines. 273Here we compare the cost of using :func:`hasattr` vs. :keyword:`try`/:keyword:`except` 274to test for missing and present object attributes: 275 276.. code-block:: sh 277 278 $ python -m timeit 'try:' ' str.__nonzero__' 'except AttributeError:' ' pass' 279 100000 loops, best of 3: 15.7 usec per loop 280 $ python -m timeit 'if hasattr(str, "__nonzero__"): pass' 281 100000 loops, best of 3: 4.26 usec per loop 282 283 $ python -m timeit 'try:' ' int.__nonzero__' 'except AttributeError:' ' pass' 284 1000000 loops, best of 3: 1.43 usec per loop 285 $ python -m timeit 'if hasattr(int, "__nonzero__"): pass' 286 100000 loops, best of 3: 2.23 usec per loop 287 288:: 289 290 >>> import timeit 291 >>> # attribute is missing 292 >>> s = """\ 293 ... try: 294 ... str.__nonzero__ 295 ... except AttributeError: 296 ... pass 297 ... """ 298 >>> timeit.timeit(stmt=s, number=100000) 299 0.9138244460009446 300 >>> s = "if hasattr(str, '__bool__'): pass" 301 >>> timeit.timeit(stmt=s, number=100000) 302 0.5829014980008651 303 >>> 304 >>> # attribute is present 305 >>> s = """\ 306 ... try: 307 ... int.__nonzero__ 308 ... except AttributeError: 309 ... pass 310 ... """ 311 >>> timeit.timeit(stmt=s, number=100000) 312 0.04215312199994514 313 >>> s = "if hasattr(int, '__bool__'): pass" 314 >>> timeit.timeit(stmt=s, number=100000) 315 0.08588060699912603 316 317To give the :mod:`timeit` module access to functions you define, you can pass a 318*setup* parameter which contains an import statement:: 319 320 def test(): 321 """Stupid test function""" 322 L = [] 323 for i in range(100): 324 L.append(i) 325 326 if __name__ == '__main__': 327 import timeit 328 print(timeit.timeit("test()", setup="from __main__ import test")) 329