--------------
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.
+ a :ref:`command-line-interface` as well as a :ref:`callable <python-interface>`
+ one. 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:
+ Basic Examples
+ --------------
- .. class:: Timer(stmt='pass', setup='pass', timer=<timer function>)
+ The following example shows how the :ref:`command-line-interface`
+ can be used to compare three different expressions:
- Class for timing execution speed of small code snippets.
+ .. code-block:: sh
- 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). *stmt* and *setup*
- may also contain multiple statements separated by ``;`` or newlines, as long as
- they don't contain multi-line string literals.
+ $ python -m timeit '"-".join(str(n) for n in range(100))'
+ 10000 loops, best of 3: 40.3 usec per loop
+ $ python -m timeit '"-".join([str(n) for n in range(100)])'
+ 10000 loops, best of 3: 33.4 usec per loop
+ $ python -m timeit '"-".join(map(str, range(100)))'
+ 10000 loops, best of 3: 25.2 usec per loop
- To measure the execution time of the first statement, use the :meth:`Timer.timeit`
- method. The :meth:`repeat` method is a convenience to call :meth:`.timeit`
- multiple times and return a list of results.
+ This can be achieved from the :ref:`python-interface` with::
+
+ >>> import timeit
+ >>> timeit.timeit('"-".join(str(n) for n in range(100))', number=10000)
+ 0.8187260627746582
+ >>> timeit.timeit('"-".join([str(n) for n in range(100)])', number=10000)
+ 0.7288308143615723
+ >>> timeit.timeit('"-".join(map(str, range(100)))', number=10000)
+ 0.5858950614929199
+
+ Note however that :mod:`timeit` will automatically determine the number of
+ repetitions only when the command-line interface is used. In the
+ :ref:`timeit-examples` section you can find more advanced examples.
- The *stmt* and *setup* parameters can 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.
+ .. _python-interface:
- .. method:: Timer.print_exc(file=None)
+ Python Interface
+ ----------------
- Helper to print a traceback from the timed code.
+ The module defines three convenience functions and a public class:
+
+
+ .. function:: timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000)
- Typical use::
+ Create a :class:`Timer` instance with the given statement, *setup* code and
+ *timer* function and run its :meth:`.timeit` method with *number* executions.
- 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``.
+ .. function:: repeat(stmt='pass', setup='pass', timer=<default 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.
- .. method:: Timer.repeat(repeat=3, number=1000000)
- Call :meth:`.timeit` a few times.
+ .. function:: default_timer()
- 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
- :meth:`.timeit`.
- Define a default timer, in a platform-specific manner. On Windows,
- :func:`time.clock` has microsecond granularity, but :func:`time.time`'s
- granularity is 1/60th of a second. On Unix, :func:`time.clock` has 1/100th of
- a second granularity, and :func:`time.time` is much more precise. On either
- platform, :func:`default_timer` measures wall clock time, not the CPU
- time. This means that other processes running on the same computer may
- interfere with the timing.
++ The default timer, which is always :func:`time.perf_counter`.
+
- .. note::
++ .. versionchanged:: 3.3
++ :func:`time.perf_counter` is now the default timer.
- It's tempting to calculate mean and standard deviation from the result vector
- and report these. However, this is not very useful. In a typical case, the
- 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.
+ .. class:: Timer(stmt='pass', setup='pass', timer=<timer function>)
- .. method:: Timer.timeit(number=1000000)
+ Class for timing execution speed of small code snippets.
- 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.
+ 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).
+ *stmt* and *setup* may also contain multiple statements separated by ``;``
+ or newlines, as long as they don't contain multi-line string literals.
- .. note::
+ 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.
- By default, :meth:`.timeit` temporarily turns off :term:`garbage collection`
- during the timing. The advantage of this approach is that it makes
- independent timings more comparable. This disadvantage is that GC may be
- an important component of the performance of the function being measured.
- If so, GC can be re-enabled as the first statement in the *setup* string.
- For example::
+ The *stmt* and *setup* parameters can 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.
- timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
+ .. method:: Timer.timeit(number=1000000)
- The module also defines three convenience functions:
+ 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::
- .. function:: default_timer()
+ By default, :meth:`.timeit` temporarily turns off :term:`garbage
+ collection` during the timing. The advantage of this approach is that
+ it makes independent timings more comparable. This disadvantage is
+ that GC may be an important component of the performance of the
+ function being measured. If so, GC can be re-enabled as the first
+ statement in the *setup* string. For example::
- The default timer, which is always :func:`time.perf_counter`.
+ timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
- .. function:: repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=3, number=1000000)
+ .. method:: Timer.repeat(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.
+ 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 :meth:`.timeit`.
- .. function:: timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000)
+ .. note::
- Create a :class:`Timer` instance with the given statement, setup code and timer
- function and run its :meth:`.timeit` method with *number* executions.
+ It's tempting to calculate mean and standard deviation from the result
+ vector and report these. However, this is not very useful.
+ In a typical case, the 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.
- Command Line Interface
+ .. 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 :data:`sys.stderr`.
+
+
+ .. _command-line-interface:
+
+ Command-Line Interface
----------------------
When called as a program from the command line, the following form is used::
projects / python / commitdiff