timeit — 测量小代码段的执行时间

源代码: Lib/timeit.py


此模块提供了一种简单的方法来对小段 Python 代码进行计时。它既有 命令行界面,也有 可调用 的界面。它避免了测量执行时间时常见的许多陷阱。另请参阅 Tim Peters 在 O'Reilly 出版的《Python Cookbook》第二版“算法”一章中的简介。

基本示例

以下示例展示了如何使用 命令行界面 来比较三个不同的表达式

$ python -m timeit "'-'.join(str(n) for n in range(100))"
10000 loops, best of 5: 30.2 usec per loop
$ python -m timeit "'-'.join([str(n) for n in range(100)])"
10000 loops, best of 5: 27.5 usec per loop
$ python -m timeit "'-'.join(map(str, range(100)))"
10000 loops, best of 5: 23.2 usec per loop

这可以通过 Python 接口 实现

>>> import timeit
>>> timeit.timeit('"-".join(str(n) for n in range(100))', number=10000)
0.3018611848820001
>>> timeit.timeit('"-".join([str(n) for n in range(100)])', number=10000)
0.2727368790656328
>>> timeit.timeit('"-".join(map(str, range(100)))', number=10000)
0.23702679807320237

还可以通过 Python 接口 传递一个可调用对象

>>> timeit.timeit(lambda: "-".join(map(str, range(100))), number=10000)
0.19665591977536678

但是请注意,timeit() 仅在使用命令行界面时才自动确定重复次数。您可以在 示例 部分中找到更高级的示例。

Python 接口

该模块定义了三个便捷函数和一个公有类

timeit.timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000, globals=None)

使用给定的语句、设置代码和计时器函数创建一个 Timer 实例,并使用数字执行运行它的 timeit() 方法。可选的全局参数指定执行代码的命名空间。

版本 3.5 中已更改: 添加了可选的全局参数。

timeit.repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=5, number=1000000, globals=None)

使用给定的语句、设置代码和计时器函数创建一个 Timer 实例,并使用给定的重复计数和数字执行运行它的 repeat() 方法。可选的全局参数指定执行代码的命名空间。

版本 3.5 中已更改: 添加了可选的全局参数。

版本 3.7 中已更改: 重复的默认值已从 3 更改为 5。

timeit.default_timer()

默认计时器始终是 time.perf_counter(),它返回浮点秒。备选计时器 time.perf_counter_ns 返回整数纳秒。

版本 3.3 中已更改: time.perf_counter() 现在是默认计时器。

class timeit.Timer(stmt='pass', setup='pass', timer=<timer function>, globals=None)

用于对小代码段的执行速度进行计时的小类。

构造函数采用要计时的语句、用于设置的附加语句和计时器函数。这两个语句都默认为 'pass';计时器函数取决于平台(请参阅模块文档字符串)。只要stmtsetup 不包含多行字符串文字,它们还可以包含由 ; 或换行符分隔的多个语句。该语句在默认情况下将在 timeit 的命名空间内执行;可以通过将命名空间传递给全局来控制此行为。

要测量第一个语句的执行时间,请使用 timeit() 方法。repeat()autorange() 方法是调用 timeit() 多次的便捷方法。

setup 的执行时间从整体计时执行运行中排除。

stmtsetup 参数还可以采用无参数的可调用对象。这会在计时函数中嵌入对它们的调用,然后由 timeit() 执行。请注意,在这种情况下,由于额外的函数调用,计时开销会稍大一些。

版本 3.5 中已更改: 添加了可选的全局参数。

timeit(number=1000000)

对主语句执行 number 次执行。这会执行一次 setup 语句,然后返回执行主语句多次所需的时间。默认计时器以浮点数形式返回秒数。参数是循环执行的次数,默认为一百万。主语句、setup 语句和要使用的计时器函数会传递给构造函数。

注意

默认情况下,timeit() 在计时期间会暂时关闭 垃圾回收。这种方法的优点是它使独立计时更具可比性。缺点是 GC 可能是被测量的函数性能的一个重要组成部分。如果是这样,则可以在 setup 字符串中的第一个语句中重新启用 GC。例如

timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit()
autorange(callback=None)

自动确定调用 timeit() 的次数。

这是一个便捷函数,它反复调用 timeit(),以便总时间 >= 0.2 秒,返回最终(循环次数、该循环次数所花费的时间)。它使用序列 1、2、5、10、20、50、… 中不断增加的数字调用 timeit(),直到所花费的时间至少为 0.2 秒。

如果给出了 callback 且它不是 None,它将在每次试验后使用两个参数调用:callback(number, time_taken)

在版本 3.6 中添加。

repeat(repeat=5, number=1000000)

多次调用 timeit()

这是一个便捷函数,它反复调用 timeit(),返回结果列表。第一个参数指定调用 timeit() 的次数。第二个参数指定 timeit()number 参数。

注意

从结果向量计算平均值和标准差并报告这些值非常诱人。然而,这并不是很有用。在典型情况下,最低值给出了机器运行给定代码段的速度的下限;结果向量中的较高值通常不是由 Python 速度的变化引起的,而是由其他进程干扰了计时精度。因此,结果的 min() 可能是您应该感兴趣的唯一数字。之后,您应该查看整个向量并应用常识,而不是统计数据。

版本 3.7 中已更改: 重复的默认值已从 3 更改为 5。

print_exc(file=None)

帮助从计时代码打印回溯。

典型用法

t = Timer(...)       # outside the try/except
try:
    t.timeit(...)    # or t.repeat(...)
except Exception:
    t.print_exc()

与标准回溯相比,优势在于将显示已编译模板中的源代码行。可选的 file 参数指示将回溯发送到何处;它默认为 sys.stderr

命令行界面

当从命令行作为程序调用时,将使用以下形式

python -m timeit [-n N] [-r N] [-u U] [-s S] [-p] [-v] [-h] [statement ...]

理解以下选项

-n N, --number=N

执行“语句”的次数

-r N, --repeat=N

重复计时器的次数(默认 5)

-s S, --setup=S

最初仅执行一次的语句(默认 pass

-p, --process

测量进程时间,而不是使用 time.process_time()(默认)的挂钟时间,而不是 time.perf_counter()

在 3.3 版中添加。

-u, --unit=U

指定计时器输出的时间单位;可以选择 nsecusecmsecsec

在 3.5 版中添加。

-v, --verbose

打印原始计时结果;重复以获得更多位精度

-h, --help

打印简短的使用信息并退出

可以通过将每行指定为单独的语句参数来给出多行语句;缩进行可以通过将参数用引号括起来并使用前导空格来实现。多个 -s 选项的处理方式类似。

如果未给出 -n,将通过尝试从序列 1、2、5、10、20、50、… 中增加数字来计算合适的循环次数,直到总时间至少为 0.2 秒。

default_timer() 测量可能会受到同一台机器上运行的其他程序的影响,因此在需要准确计时时,最好的办法是重复计时几次并使用最佳时间。 -r 选项非常适合此目的;在大多数情况下,默认的 5 次重复可能就足够了。你可以使用 time.process_time() 来测量 CPU 时间。

注意

执行 pass 语句时会产生一定的基线开销。此处的代码不会尝试隐藏它,但你应该意识到这一点。可以通过不带参数调用程序来测量基线开销,并且它可能因 Python 版本而异。

示例

可以提供仅在开头执行一次的设置语句

$ python -m timeit -s "text = 'sample string'; char = 'g'" "char in text"
5000000 loops, best of 5: 0.0877 usec per loop
$ python -m timeit -s "text = 'sample string'; char = 'g'" "text.find(char)"
1000000 loops, best of 5: 0.342 usec per loop

输出中有三个字段。循环计数,它告诉你每次计时循环重复运行语句体的次数。重复计数(“最佳 5 次”),它告诉你计时循环重复的次数,最后是语句体在计时循环的最佳重复中平均花费的时间。也就是说,最快的重复花费的时间除以循环计数。

>>> import timeit
>>> timeit.timeit('char in text', setup='text = "sample string"; char = "g"')
0.41440500499993504
>>> timeit.timeit('text.find(char)', setup='text = "sample string"; char = "g"')
1.7246671520006203

可以使用 Timer 类及其方法执行相同的操作

>>> import timeit
>>> t = timeit.Timer('char in text', setup='text = "sample string"; char = "g"')
>>> t.timeit()
0.3955516149999312
>>> t.repeat()
[0.40183617287970225, 0.37027556854118704, 0.38344867356679524, 0.3712595970846668, 0.37866875250654886]

以下示例展示了如何对包含多行的表达式进行计时。此处我们比较使用 hasattr()try/except 来测试缺少和存在的对象属性的成本

$ python -m timeit "try:" "  str.__bool__" "except AttributeError:" "  pass"
20000 loops, best of 5: 15.7 usec per loop
$ python -m timeit "if hasattr(str, '__bool__'): pass"
50000 loops, best of 5: 4.26 usec per loop

$ python -m timeit "try:" "  int.__bool__" "except AttributeError:" "  pass"
200000 loops, best of 5: 1.43 usec per loop
$ python -m timeit "if hasattr(int, '__bool__'): pass"
100000 loops, best of 5: 2.23 usec per loop
>>> import timeit
>>> # attribute is missing
>>> s = """\
... try:
...     str.__bool__
... except AttributeError:
...     pass
... """
>>> timeit.timeit(stmt=s, number=100000)
0.9138244460009446
>>> s = "if hasattr(str, '__bool__'): pass"
>>> timeit.timeit(stmt=s, number=100000)
0.5829014980008651
>>>
>>> # attribute is present
>>> s = """\
... try:
...     int.__bool__
... except AttributeError:
...     pass
... """
>>> timeit.timeit(stmt=s, number=100000)
0.04215312199994514
>>> s = "if hasattr(int, '__bool__'): pass"
>>> timeit.timeit(stmt=s, number=100000)
0.08588060699912603

要向 timeit 模块授予对定义的函数的访问权限,你可以传递包含 import 语句的 setup 参数

def test():
    """Stupid test function"""
    L = [i for i in range(100)]

if __name__ == '__main__':
    import timeit
    print(timeit.timeit("test()", setup="from __main__ import test"))

另一个选项是将 globals() 传递给 globals 参数,这将导致代码在当前全局命名空间中执行。这可能比单独指定 import 更方便

def f(x):
    return x**2
def g(x):
    return x**4
def h(x):
    return x**8

import timeit
print(timeit.timeit('[func(42) for func in (f,g,h)]', globals=globals()))