入门

本页将指导您如何使用 Stopwatch 来计算程序的运行时间。

指导

当我们尝试计算一段程序的运行时间时,通常会使用 timeit 模块中定义的 default_timer 函数。

current_timer_count: float = float(timeit.default_timer())
time.sleep(3)
print(float(timeit.default_timer()) - current_timer_count)

但在一些项目中,我们可能需要统计各个阶段的运行时间并统一管理和维护。此时,上文示例代码中演示的计算方式将非常不便。当需要计算的阶段节点过多时,将会产生大量重复的代码,造成代码冗余且不利于维护。

对于 Python 入门开发者而言,上文示例代码中演示的计算方式可能不利于理解。

在下文中,我们通过几段连续的 Python 代码片段来向您演示如何使用 Stopwatch 计算程序的运行时间。

导入模块

为便于理解,我们需要使用 time 模块中的 sleep 函数来模拟程序的运行流程。

import time

在使用 Stopwatch 之前,我们应该导入 Stopwatch

from stopwatch import Stopwatch

如果您需要捕获 Stopwatch 的相关异常,应该导入:

from stopwatch import StatusError
from stopwatch import LapNameError

创建 Stopwatch

Stopwatch 的功能被定义在名为 Stopwatch 的类中。因此,我们可以通过实例化 Stopwatch 类来创建一个或多个 Stopwatch 实例。

demo_stopwatch: Stopwatch = Stopwatch(
default_precision = None
)

Stopwatch 的构造器方法包含一个数据类型为 int 的可选参数 default_precision,该参数指示被创建的 Stopwatch 实例的计时器精度(小数点位数)。如果未提供该参数或值为 None,则该参数的默认值为 3

开始 Stopwatch

在上文中,我们定义了名为 demo_stopwatch 的变量,它是一个 Stopwatch 实例。现在我们尝试使 demo_stopwatch 开始计时。

demo_stopwatch.start()

接着,我们使用 time.sleep 函数挂起当前线程 3 秒,模拟第一阶段的程序代码运行。

time.sleep(3)

记录 Stopwatch

当我们的项目中存在多个程序阶段时,为了计算每个阶段的运行时间,阶段性计时是必不可少的。在上文示例代码中我们使用 time.sleep 函数模拟程序运行的第一个阶段,接着我们使用 lap 方法记录一次计时结果。

lap_of_watch: float = demo_stopwatch.lap(
lap_name = 'stage1'
)

计时记录分为 2 种:

  • 命名计时记录

  • 匿名计时记录

方法 lap 具有一个数据类型为 str 的可选参数 lap_name,该参数指示计时记录的唯一名称。如果未提供该参数或值为 None,则计时记录是匿名的。

该方法返回数据类型为 float 的返回值,其指示当前阶段的计时结果。如果这是第一条计时记录,计时结果是从 Stopwatch 开始计时到目前的间隔时间(秒);否则,计时结果是从上一条计时记录到目前的间隔时间(秒)。

请注意,计时记录的名称在当前 Stopwatch 实例中必须是唯一的,即不可重复。否则,将引发 LapNameError 异常。

接着,我们再次使用 time.sleep 函数挂起当前线程 1 秒,模拟第二阶段的程序代码运行。

time.sleep(1)

然后,记录第二阶段的计时结果。

lap_of_watch: float = demo_stopwatch.lap(
lap_name = 'stage2'
)

停止 Stopwatch

在上文中,我们使用 time.sleep 函数模拟了程序运行的第一阶段和第二阶段,并使用 lap 方法记录了程序运行第一阶段和第二阶段的计时结果。

现在,我们使 demo_stopwatch 停止计时。

total_of_watch: float = demo_stopwatch.stop()

方法 stop 返回数据类型为 float 的返回值,其指示当前 Stopwatch 实例从首次开始计时到停止计时的总计时时间(秒)。

该返回值可以被忽略,我们可以使用 get_watch 方法即时检查 Stopwatch 实例的总计时时间:

total_of_watch: float = demo_stopwatch.get_watch(
watch_precision: int = None
)

方法 get_watch 有一个数据类型为 int 的可选参数,该参数指示获取的总计时精度(小数点)。如果未提供该参数或值为 None,该参数的默认值为 Stopwatch 类构造器方法参数 default_precision 的值。

请注意,在低于 0.1.3 版本的 Stopwatch 中使用 get_watch 方法时,应该确保 Stopwatch 实例已经停止计时,否则将引发 StatusError 异常。

我们可以使用 get_status 方法检查当前 Stopwatch 实例的状态。

if demo_stopwatch.get_status() == StopwatchStatus.Stopped:
print('stopwatch has stopped timing')

StopwatchStatus 是预定义的 Stopwatch 状态枚举器,可以与方法 get_status 的返回值比较。

from stopwatch import StopwatchStatus

获取 Stopwatch 记录

在上文中,我们使用 lap 方法分阶段记录了程序运行第一阶段和第二阶段的计时结果。现在我们尝试获取这些计时记录。

获取命名计时记录

我们可以使用 get_lap 方法获取命名的计时记录。

lap_of_watch: float = demo_stopwatch.get_lap(
lap_name = 'stage1',
lap_precision = 3
)

方法 get_lap 有 2 个参数,它们分别是:

参数名

数据类型

可选

描述

lap_name

str

False

计时记录的唯一名称。

lap_precision

int

True

获取的计时记录精度(小数点位数)

参数 lap_precision 是可选的。如果未提供该参数或值为 None,该参数的默认值为 Stopwatch 类构造器方法参数 default_precision 的值。

请注意,如果指定计时记录名称不存在,将引发 LapNameError 异常。

如果我们需要确定一个计时记录是否存在,可以使用 has_lap 方法检查。

if not demo_stopwatch.has_lap(
lap_name = 'stage1'
):
print('no such lap')

获取匿名计时记录

值得注意的是,匿名计时记录并非是真正的匿名,而是使用 lap_ 和记录编号组合的方式来命名计时记录(例如:lap_1)。因此,我们也可以使用 get_lap 方法获取匿名计时记录,但更便捷的方式是使用 get_lap_by_number 方法。

lap_of_watch: float = demo_stopwatch.get_lap_by_number(
lap_number = 1,
lap_precision = 3
)

与方法 get_lap 不同之处是,该方法的参数 lap_number 指示匿名记录的编号(从 1 开始),其数据类型为 int。在该方法内部仍然调用 get_lap 方法获取匿名计时记录。

请注意,如果使用该方法获取非匿名计时记录,将引发 LapNameError 异常。

为使您更加清晰的了解命名计时记录与匿名计时记录之间的关系,我们将通过下文的演示来详细说明。

demo_stopwatch.lap('stage1')
demo_stopwatch.lap()
demo_stopwatch.get_lap_by_number(1)

在上文示例代码中,我们记录了 2 次 Stopwatch 当前计时结果,命名计时记录和匿名计时记录各一条。现在 Stopwatch 实例中计时记录集的内容如下:

[
'stage1',
'lap_2'
]

而在上文示例代码中,使用 get_lap_by_number 方法获取第一条命名计时记录时将引发异常:

LapNameError(no such lap: lap_1)

因为当前 Stopwatch 实例的计时记录集中不存在名为 lap_1 的命名计时记录,所以必然引发 LapNameError 异常。由此可见匿名计时记录仅是以默认形式(lap_ 和记录编号的组合)对记录命名。

获取所有计时记录的平均结果

如果我们需要获取当前 Stopwatch 实例中所有计时记录的平均计时结果,可以使用 get_average_of_laps 方法。

average_of_laps: float = demo_stopwatch.get_average_of_laps(
average_precision = None
)

方法 get_average_of_laps 有一个数据类型为 int 的可选参数 average_precision,该参数指示获取的计时记录平均结果的精度(小数点位数)。如果未提供该参数或值为 None,该方法的行为与 get_lap 一致。

枚举所有计时记录名称

我们还可以使用 get_laps 方法枚举所有计时记录的唯一名称,其中也包含匿名计时记录。

for lap_name in demo_stopwatch.get_laps():
print(lap_name)

方法 get_laps 返回数据类型为 list 的返回值,其中包含所有计时记录的唯一名称,成员数据类型为 str

获取计时记录条数

我们可以使用 get_lap_count 方法获取当前 Stopwatch 实例的计时记录总条数。

number_of_laps: int = demo_stopwatch.get_lap_count()

重置 Stopwatch

每个 Stopwatch 实例自开始计时起,都会产生当前实例的状态数据(例如:计时记录等...)。如果我们需要清空这些数据,则应该将 Stopwatch 实例重置为初始状态。

Tips: Stopwatch 实例可以重复开始和结束,计时记录和总计时时长都将累计,直到被重置。

demo_stopwatch.reset()

重置 Stopwatch 实例后,所有状态数据将被清理,Stopwatch 实例重置为初始状态。

请注意,如果 Stopwatch 实例仍然处于计时状态,将引发 StatusError 异常。可以使用 get_status 方法检查 Stopwatch 实例的状态。

示例

下文将以完整的 Python 示例代码演示如何使用 Stopwatch。

源代码

quickstart.py
# quickstart.py is python-3.7.4 source file
import time
from stopwatch import Stopwatch
from stopwatch import StopwatchStatus
# define main function
def main():
# instantiate stopwatch
demo_stopwatch: Stopwatch = Stopwatch(
default_precision = 3 # ignorable
)
# make stopwatch start timing
demo_stopwatch.start()
# the first stage of the simulation program
time.sleep(3)
# it takes time to record the first phase of the program
demo_stopwatch.lap('stage1')
# the second stage of the simulation program
time.sleep(1)
# it takes time to record the second phase of the program
demo_stopwatch.lap('stage2')
# try checking the stopwatch total time every 1 second
for count in range(3):
print('{COUNT} check: {WATCH_SECONDS} seconds'.format(
COUNT = count + 1,
WATCH_SECONDS = demo_stopwatch.get_watch()
))
# record cycle check time spent on stopwatch
demo_stopwatch.lap('stage3')
# get the status of stopwatch
if demo_stopwatch.get_status() == StopwatchStatus.Started:
print('stopwatch is timing...')
# stop and print the timing of the stopwatch
print(
(
'total: {TOTAL_SECONDS} seconds\n'
'stage1: {STAGE1_SECONDS} seconds\n'
'stage2: {STAGE2_SECONDS} seconds\n'
'stage3: {STAGE3_SECONDS} seconds\n'
'----------\n'
'average of stages: {AVERAGE_SECONDS} seconds'
).format(
TOTAL_SECONDS = demo_stopwatch.stop(),
STAGE1_SECONDS = demo_stopwatch.get_lap('stage1'),
STAGE2_SECONDS = demo_stopwatch.get_lap('stage2'),
STAGE3_SECONDS = demo_stopwatch.get_lap('stage2'),
AVERAGE_SECONDS = demo_stopwatch.get_average_of_laps()
)
)
# reset stopwatch
demo_stopwatch.reset()
# define virtual main function
if __name__ == '__main__':
main()

运行结果

1 check: 4.001 seconds
2 check: 4.002 seconds
3 check: 4.003 seconds
stopwatch is timing...
total: 4.006 seconds
stage1: 3.0 seconds
stage2: 1.001 seconds
stage3: 1.001 seconds
----------
average of stages: 1.335 seconds