timeit模块 — 代码执行时间测量

Python标准库精讲专题 · 测试与调试篇 · 掌握代码计时工具

专题：Python标准库精讲系统学习

关键词：Python, 标准库, timeit, 性能测量, 计时, 基准测试, 微基准, timeit.timeit, Timer

一、timeit概述

timeit 是 Python 标准库中用于测量小段代码执行时间的工具。它专为微基准测试（micro-benchmarking）而设计，能够精确测量短代码片段的运行耗时，避免了许多手动计时方式中容易引入的误差。

与直接使用 time.time() 或 time.perf_counter() 手写计时逻辑不同，timeit 在底层做了多项关键优化：它会自动关闭垃圾回收（GC）以减少干扰，选择系统中精度最高的计时器，并对短代码段自动重复执行多次以获得稳定结果。这些特性使得 timeit 成为官方推荐的微基准测试工具。

timeit 模块提供了三种使用方式：函数式 API（timeit.timeit()、timeit.repeat()）、面向对象的 Timer 类，以及命令行接口（python -m timeit）。不同场景下可以选择最适合的用法。

核心设计理念：微基准测试追求的是"在受控环境中测量最小操作单元的性能"。通过禁用垃圾回收、设置计时精度阈值、自动重复执行等手段，timeit 将外部干扰降至最低，确保测量结果的可重复性和可比性。

在使用 timeit 时有一个重要注意事项：测量结果反映的是测试代码在特定软硬件环境下的表现，不应直接推广到生产环境中的真实工作负载。微基准测试更适合用于横向比较不同实现方案的相对性能差异，而非预测实际系统的绝对吞吐量。

二、函数式API

timeit 模块提供了一组便捷的函数，适用于快速对代码片段进行计时。最常用的两个函数是 timeit.timeit() 和 timeit.repeat()。

2.1 timeit.timeit()

timeit.timeit(stmt='pass', setup='pass', timer=, number=1000000, globals=None) 是模块的核心函数。它执行 setup 中的设置代码一次，然后重复执行 stmt 指定的语句 number 次，并返回总耗时（单位为秒）。

参数说明：stmt 是要测量的代码语句，可以是一个字符串或可调用对象；setup 是执行前的准备语句，通常用于导入模块或定义变量；timer 指定计时器函数，通常使用默认值；number 指定重复执行次数；globals 用于指定全局命名空间，在 Python 3.5 及以上版本中可用。

import timeit

# 测量列表推导式的执行时间
t = timeit.timeit('[i**2 for i in range(100)]', number=10000)
print(f"列表推导式耗时: {t:.4f} 秒")

# 使用 setup 参数导入模块
t = timeit.timeit('math.sqrt(144)',
                  setup='import math',
                  number=100000)
print(f"math.sqrt 耗时: {t:.4f} 秒")

# 使用 globals 参数传递当前命名空间
x = 42
t = timeit.timeit('x ** 2', globals=globals(), number=1000000)
print(f"x**2 耗时: {t:.4f} 秒")

当 stmt 或 setup 中包含多行代码时，可以使用三引号字符串或分号分隔。对于较长的代码块，推荐使用三引号以保持可读性。

2.2 timeit.repeat()

timeit.repeat(stmt='pass', setup='pass', timer=, repeat=5, number=1000000, globals=None) 在 timeit() 的基础上增加了重复测量功能。它会调用 timeit() 共计 repeat 次，并将每次的结果收集在一个列表中返回。这样可以得到一组测量值，便于分析结果的稳定性和波动范围。

import timeit

# 重复测量 5 次，每次执行 10000 轮
results = timeit.repeat(
    '[i**2 for i in range(100)]',
    number=10000,
    repeat=5
)
print(f"各次耗时: {results}")
print(f"最小值: {min(results):.4f} 秒")
print(f"平均值: {sum(results)/len(results):.4f} 秒")

在分析 repeat() 结果时，通常取最小值作为最终参考——因为最小值最接近排除了系统干扰后的真实执行时间。平均值的意义相对有限，因为它可能被偶然的系统抖动拉高。如果各次测量结果之间的差异很大（例如最大值比最小值高出 50% 以上），说明测试环境存在较大噪声，需要进一步控制变量。

三、Timer类

Timer 类是 timeit 模块面向对象编程（OOP）接口的核心。它封装了计时任务的状态，适合在需要多次复用同一测试设置、或希望在程序的不同位置分别计时时使用。

3.1 Timer 构造与基本用法

timeit.Timer(stmt='pass', setup='pass', timer=, globals=None) 创建一个计时器对象。参数含义与函数式 API 中的同名参数完全一致。创建 Timer 实例后，可以调用其 timeit() 和 repeat() 方法来执行测量。

import timeit

# 创建 Timer 实例
timer = timeit.Timer(
    'squares = [i**2 for i in range(100)]'
)

# 执行一次测量
t = timer.timeit(number=10000)
print(f"单次测量: {t:.4f} 秒")

# 重复测量
results = timer.repeat(repeat=3, number=10000)
print(f"重复测量: {results}")

3.2 在交互式环境中的特殊行为

Timer 类有一个重要特性：当 stmt 和 setup 以字符串形式传递时，代码会在独立的命名空间中编译和执行，不会自动捕获调用者所在作用域中的变量。如果需要在计时代码中使用外部变量，必须通过 globals 参数显式传递，或者将代码字符串拼接为包含变量值的文本。

import timeit

value = 42

# 错误用法：value 在计时命名空间中不可见
# t = timeit.timeit('value ** 2', number=1000)  # 会抛出 NameError

# 正确用法：传递 globals 参数
t = timeit.timeit('value ** 2', globals=globals(), number=1000)
print(f"正确使用 globals: {t:.6f} 秒")

3.3 可调用对象作为参数

从 Python 3.5 开始，stmt 和 setup 不仅支持字符串，还可以接受可调用对象（如函数）。使用可调用对象时，代码会在当前命名空间中执行，无需担心变量作用域问题，同时也避免了字符串拼接带来的安全隐患。

import timeit

def compute():
    return [i**2 for i in range(100)]

# 传递可调用对象，免去 globals 参数
t = timeit.timeit(compute, number=10000)
print(f"可调用对象: {t:.4f} 秒")

可调用对象方式在组织较复杂的测试代码时尤为便利——可以将测试逻辑封装为函数，利用 Python 的闭包和参数传递机制灵活控制测试条件。

四、命令行接口

timeit 模块提供了极其便捷的命令行接口，无需编写 Python 脚本即可快速测量代码性能。只需在终端中执行 python -m timeit 并传入待测代码即可。

4.1 基本用法

命令行接口的调用格式为 python -m timeit [-n N] [-r N] [-s S] [-p] [-v] [-h] [statement ...]。在命令行中直接传入代码字符串，timeit 会自动选择合适的重复次数并输出结果。

# 测量列表推导式（自动选择次数）
$ python -m timeit "[i**2 for i in range(100)]"
20000 loops, best of 5: 23.4 usec per loop

# 测量普通 for 循环
$ python -m timeit "squares = []" "for i in range(100):" "    squares.append(i**2)"
10000 loops, best of 5: 30.1 usec per loop

4.2 关键命令行参数

命令行接口提供了多个参数以精细控制测量行为：-n N 手动指定每个循环中执行语句的次数，覆盖默认的自动选择逻辑；-r N 指定重复测量的次数（即 repeat 参数），默认为 5；-s S 指定 setup 语句，可以多次使用以执行多条准备语句；-p 选项在 Windows 平台上使用 time.clock() 以获得更高精度，在类 Unix 系统上无效；-v 输出详细计时信息；-h 显示帮助信息。

# 手动指定次数并添加 setup
$ python -m timeit -n 100000 -r 10 -s "import math" "math.sqrt(144)"
100000 loops, best of 10: 0.123 usec per loop

# 多行 setup（使用多个 -s）
$ python -m timeit -s "data = list(range(1000))" -s "from random import shuffle" "shuffle(data)"
2000 loops, best of 5: 152 usec per loop

4.3 输出结果解读

命令行输出的典型格式为 "20000 loops, best of 5: 23.4 usec per loop"。其中 20000 loops 表示每次循环执行了 20000 次语句（即 number 值）；best of 5 表示总共重复测量了 5 次，取其中最好的结果；23.4 usec per loop 表示每次语句执行平均耗时 23.4 微秒。输出中的时间单位可能是 usec（微秒）、msec（毫秒）或 sec（秒），取决于耗时长短。

命令行技巧：当待测语句中包含引号或特殊字符时，在 Windows 的 cmd.exe 中需要注意转义规则。推荐在 PowerShell 或 Git Bash 中使用双引号包裹整个语句，语句内的引号使用单引号。在 Linux/macOS 的 bash 中则相反：外层用单引号，内层用双引号。

五、实战应用

理论掌握得再好，也不如实操一次来得深刻。本节通过三个经典性能对比场景，展示 timeit 在实际开发中的应用方式。

5.1 列表推导式 vs for 循环

列表推导式通常被认为是比 for 循环更高效的构建列表方式。下面通过 timeit 来量化这一差异：

import timeit

setup_code = '''
squares = []
'''

stmt_for = '''
for i in range(1000):
    squares.append(i**2)
'''

stmt_comp = '''
[i**2 for i in range(1000)]
'''

t_for = timeit.timeit(stmt_for, setup_code, number=10000)
t_comp = timeit.timeit(stmt_comp, number=10000)

print(f"for 循环:     {t_for:.4f} 秒")
print(f"列表推导式:   {t_comp:.4f} 秒")
print(f"列表推导式快了 {t_for/t_comp:.2f} 倍")

多次运行结果表明，列表推导式通常比等效的 for 循环快 30%-60%。原因在于列表推导式在 CPython 内部以 C 速度执行迭代，而 for 循环需要反复执行 Python 字节码循环体。在数据量较大时，这种性能差异会更加明显。

5.2 f-string vs format() vs %格式化

Python 3.6 引入的 f-string 在可读性和性能上都有优势。下面通过 timeit 验证：

import timeit

name, age = "Alice", 30

stmt_f = f"f'{{name}} is {{age}} years old'"
stmt_format = "'{} is {} years old'.format(name, age)"
stmt_percent = "'%s is %d years old' % (name, age)"

globals_dict = {'name': name, 'age': age}

t_f = timeit.timeit(stmt_f, globals=globals_dict, number=1000000)
t_fmt = timeit.timeit(stmt_format, globals=globals_dict, number=1000000)
t_pct = timeit.timeit(stmt_percent, globals=globals_dict, number=1000000)

print(f"f-string:      {t_f:.4f} 秒")
print(f"format():      {t_fmt:.4f} 秒")
print(f"% 格式化:      {t_pct:.4f} 秒")

实测表明，f-string 通常是三者中性能最佳的，尤其在简单字符串插值场景下优势显著。format() 方法由于需要解析格式字符串、处理位置参数，性能略低于 f-string。% 格式化作为最古老的方式，性能介于两者之间，但在复杂格式控制方面不如 format() 灵活。综合考虑性能与可读性，f-string 是日常开发中的首选方案。

5.3 多种数据结构性能对比

不同数据结构的查找、插入和删除操作的时间复杂度不同。通过基准测试可以直观验证这些理论差异：

import timeit
from collections import OrderedDict, defaultdict

setup = '''
n = 10000
data_list = list(range(n))
data_set = set(range(n))
data_dict = {i: i for i in range(n)}
'''

# 成员测试（查找）性能
list_test = '9999 in data_list'
set_test  = '9999 in data_set'
dict_test = '9999 in data_dict'

t_list = timeit.timeit(list_test, setup, number=10000)
t_set  = timeit.timeit(set_test,  setup, number=10000)
t_dict = timeit.timeit(dict_test, setup, number=10000)

print(f"list 成员测试:  {t_list:.4f} 秒")
print(f"set  成员测试:  {t_set:.4f} 秒")
print(f"dict 键测试:    {t_dict:.4f} 秒")
print(f"set 比 list 快 {t_list/t_set:.0f} 倍")

运行结果会清晰展示出 set 和 dict 的哈希表查找与 list 的线性扫描之间的巨大性能差异。在 10000 个元素的集合中，set/dict 的成员测试比 list 快数百倍。这就是为什么在需要频繁进行成员测试的场景中，应优先使用 set 而非 list。需要注意的是，这个差异会随着数据规模增大而进一步扩大——list 的查找时间与数据量呈线性关系，而 set 和 dict 则保持接近常数时间。

5.4 常见场景速查表

对比场景	建议使用	不推荐	性能差异
构建列表	列表推导式	for 循环 + append	快 30%-60%
字符串格式化	f-string	format() / %	快 10%-40%
成员测试	set / dict	list	快数百倍（数据量大时）
字符串拼接	''.join()	+= 逐次拼接	快数倍到数十倍
列表去重	list(set())	手写循环判重	快数倍
属性访问	local 变量引用	重复属性查找	快 10%-20%

六、核心总结

1. timeit 的本质：timeit 是 Python 内置的微基准测试工具，通过禁用 GC、自动选择高精度计时器、重复执行等手段，为短代码片段提供准确、可重复的性能测量。

2. 三种使用方式：函数式 API（timeit() / repeat()）适合快速测试；Timer 类适合需要复用测试设置的场景；命令行接口（python -m timeit）适合在终端中临时测量，无需编写脚本。

3. 关键参数：number 控制每个循环的执行次数，repeat 控制重复测量的轮数。取多个 repeat 结果中的最小值最能反映真实性能。

4. 作用域管理：字符串形式的 stmt 在独立命名空间中执行，需要通过 globals 参数传递外部变量；可调用对象方式（Python 3.5+）可以避免作用域问题。

5. 最大误区：微基准测试的数字（如"23.4 usec per loop"）是理想环境下的最佳值，不代表生产环境的实际性能。timeit 的真正价值在于"横向对比"——在完全相同的条件下比较不同实现方案的相对优劣。

6. 实际应用建议：先用直觉选择方案，遇到性能瓶颈时用 timeit 验证假设。避免过早优化，但在数据结构选择、核心算法实现等关键决策点上，timeit 是客观可靠的决策依据。

微基准测试是一门实践性很强的技能，只有在大量真实的对比测量中才能积累起对 Python 执行性能的直觉。建议读者在阅读完本文后，打开 Python 交互环境或编辑器，用 timeit 模块亲自验证文中的每一个结论，并尝试对自己的代码进行性能摸底。