入门
本页将指导您如何使用 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 实例。demo_stopwatch: Stopwatch = Stopwatch(
default_precision = None
)
类
Stopwatch
的构造器方法包含一个数据类型为 int
的可选参数 default_precision
,该参数指示被创建的 Stopwatch 实例的计时器精度(小数点位数)。如果未提供该参数或值为 None
,则该参数的默认值为 3
。在上文中,我们定义了名为
demo_stopwatch
的变量,它是一个 Stopwatch 实例。现在我们尝试使 demo_stopwatch
开始计时。demo_stopwatch.start()
接着,我们使用
time.sleep
函数挂起当前线程 3 秒,模拟第一阶段的程序代码运行。time.sleep(3)
当我们的项目中存在多个程序阶段时,为了计算每个阶段的运行时间,阶段性计时是必不可少的。在上文示例代码中我们使用
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'
)
在上文中,我们使用
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
在上文中,我们使用
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 实例重置为初始状态。
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
)