| This module provides a simple way to time small bits of Python code. It has both |
| command line as well as callable interfaces. It avoids a number of common traps |
| for measuring execution times. See also Tim Peters' introduction to the |
| "Algorithms" chapter in the Python Cookbook, published by O'Reilly. |
| |
| The module defines the following public class: |
| |
| |
n | .. class:: Timer([stmt=``'pass'`` [, setup=``'pass'`` [, timer=<timer function>]]]) |
n | .. class:: Timer([stmt='pass' [, setup='pass' [, timer=<timer function>]]]) |
| |
| Class for timing execution speed of small code snippets. |
| |
| The constructor takes a statement to be timed, an additional statement used for |
| setup, and a timer function. Both statements default to ``'pass'``; the timer |
| function is platform-dependent (see the module doc string). The statements may |
| contain newlines, as long as they don't contain multi-line string literals. |
| |
| To measure the execution time of the first statement, use the :meth:`timeit` |
| method. The :meth:`repeat` method is a convenience to call :meth:`timeit` |
| multiple times and return a list of results. |
| |
n | .. versionchanged:: 2.6 |
| The *stmt* and *setup* parameters can now also take objects that are callable |
| without arguments. This will embed calls to them in a timer function that will |
| then be executed by :meth:`timeit`. Note that the timing overhead is a little |
| larger in this case because of the extra function calls. |
| |
n | |
| .. method:: Timer.print_exc([file=:const:`None`]) |
| .. method:: Timer.print_exc([file=None]) |
| |
| Helper to print a traceback from the timed code. |
| |
| Typical use:: |
| |
| t = Timer(...) # outside the try/except |
| try: |
| t.timeit(...) # or t.repeat(...) |
| except: |
| t.print_exc() |
| |
| The advantage over the standard traceback is that source lines in the compiled |
| template will be displayed. The optional *file* argument directs where the |
| traceback is sent; it defaults to ``sys.stderr``. |
| |
| |
n | .. method:: Timer.repeat([repeat\ ``=3`` [, number\ ``=1000000``]]) |
n | .. method:: Timer.repeat([repeat=3 [, number=1000000]]) |
| |
| Call :meth:`timeit` a few times. |
| |
| This is a convenience function that calls the :meth:`timeit` repeatedly, |
| returning a list of results. The first argument specifies how many times to |
| call :meth:`timeit`. The second argument specifies the *number* argument for |
| :func:`timeit`. |
| |
| lowest value gives a lower bound for how fast your machine can run the given |
| code snippet; higher values in the result vector are typically not caused by |
| variability in Python's speed, but by other processes interfering with your |
| timing accuracy. So the :func:`min` of the result is probably the only number |
| you should be interested in. After that, you should look at the entire vector |
| and apply common sense rather than statistics. |
| |
| |
n | .. method:: Timer.timeit([number\ ``=1000000``]) |
n | .. method:: Timer.timeit([number=1000000]) |
| |
| Time *number* executions of the main statement. This executes the setup |
| statement once, and then returns the time it takes to execute the main statement |
| a number of times, measured in seconds as a float. The argument is the number |
| of times through the loop, defaulting to one million. The main statement, the |
| setup statement and the timer function to be used are passed to the constructor. |
| |
| .. note:: |
| |
n | By default, :meth:`timeit` temporarily turns off garbage collection during the |
n | By default, :meth:`timeit` temporarily turns off :term:`garbage collection` |
| timing. The advantage of this approach is that it makes independent timings |
| during the timing. The advantage of this approach is that it makes |
| more comparable. This disadvantage is that GC may be an important component of |
| independent timings more comparable. This disadvantage is that GC may be |
| the performance of the function being measured. If so, GC can be re-enabled as |
| an important component of the performance of the function being measured. |
| the first statement in the *setup* string. For example:: |
| If so, GC can be re-enabled as the first statement in the *setup* string. |
| For example:: |
| |
| timeit.Timer('for i in xrange(10): oct(i)', 'gc.enable()').timeit() |
n | |
| Starting with version 2.6, the module also defines two convenience functions: |
| |
| |
| .. function:: repeat(stmt[, setup[, timer[, repeat=3 [, number=1000000]]]]) |
| |
| Create a :class:`Timer` instance with the given statement, setup code and timer |
| function and run its :meth:`repeat` method with the given repeat count and |
| *number* executions. |
| |
| .. versionadded:: 2.6 |
| |
| |
| .. function:: timeit(stmt[, setup[, timer[, number=1000000]]]) |
| |
| Create a :class:`Timer` instance with the given statement, setup code and timer |
| function and run its :meth:`timeit` method with *number* executions. |
| |
| .. versionadded:: 2.6 |
| |
| |
| Command Line Interface |
| ---------------------- |
| |
| When called as a program from the command line, the following form is used:: |
| |
t | python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...] |
t | python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...] |
| |
| where the following options are understood: |
| |
| -n N/:option:`--number=N` |
| how many times to execute 'statement' |
| |
| -r N/:option:`--repeat=N` |
| how many times to repeat the timer (default 3) |