Stopwatch 管理器

本页将指导您如何使用 Stopwatch 管理器来托管多个 Stopwatch 实例。
指导
当我们在一些简单的项目中使用 Stopwatch 时，通常仅创建一个 Stopwatch 实例。
demo_stopwatch: Stopwatch = Stopwatch()
但在一些中、大型项目中，我们可能会需要使用多个 Stopwatch 实例并在项目全局共享。此时，上文中直接创建的 Stopwatch 实例可能不便于在全局范围内共享和维护。而当需要多个 Stopwatch 实例时，对实例对象的管理和维护将变得复杂。
在 0.1.3 或更高版本中，我们可以使用一个或多个 Stopwatch 管理器托管这些 Stopwatch 实例并在全局范围内共享，开发者也无需维护这些实例对象。
在下文中，我们将通过几段连续的 Python 代码向您演示如何使用 Stopwatch 管理器。
导入模块
在使用 Stopwatch 管理器之前，我们应该导入 StopwatchManager：
from stopwatch import StopwatchManager
如果您不需要多个 Stopwatch 管理器实例，可以直接使用默认的 Stopwatch 管理器并在全局范围内共享。
from stopwatch import default_manager
符号 default_manager 是一个数据类型为 StopwatchManager 的变量，它在包 stopwatch 被首次导入时创建。因此，您可以在全局范围内导入此变量，以在全局范围内共享 Stopwatch 默认管理器实例。
创建管理器
如果 Stopwatch 默认管理器不足以满足需求，您可以额外创建多个 Stopwatch 管理器实例。
demo_manager: StopwatchManager = StopwatchManager(
    max_stopwatch_count = None
)
类 StopwatchManager 的构造器方法有一个数据类型为 int 的可选参数 max_stopwatch_count，该参数指示被创建的 Stopwatch 管理器最多可以同时托管多少个 Stopwatch 实例。如果未提供该参数或值为 None，则不限制 Stopwatch 实例个数。
添加 Stopwatch
我们在本篇指导文章的开头，定义了名为 demo_stopwatch 的变量，它是一个 Stopwatch 实例。现在我们尝试将 demo_stopwatch 添加到上文创建的 Stopwatch 管理器实例 demo_manager 中。
demo_manager.add(
    stopwatch_name = 'guide::demo1', 
    stopwatch_instance = demo_stopwatch
)
方法 add 有 2 个参数，它们分别是：
参数名
类型
必选
描述
stopwatch_name
str
True
Stopwatch 实例唯一名称。
stopwatch_instance
Stopwatch
True
被添加的 Stopwatch 实例对象。
我们强烈建议您使用 namespace::name 的形式命名 Stopwatch 实例唯一名称，这样当多个协作项目在同一全局范围内，不会引发 Stopwatch 实例唯一名称冲突，Namespace 可以是项目名称。
请注意，Stopwatch 实例名称在当前 Stopwatch 管理器范围内必须是唯一的，否则将引发 StopwatchNameError 异常。
如果当前 Stopwatch 管理器内已托管的 Stopwatch 实例个数等于或超过 max_stopwatch_count 参数的限制，将引发 MaxLimitError 异常。
创建 Stopwatch
除了向 Stopwatch 管理器添加已有 Stopwatch 实例外，我们也可以直接在 Stopwatch 管理器中创建一个具有默认构造器方法参数的新 Stopwatch 实例。
new_stopwatch: Stopwatch = demo_manager.create(
    stopwatch_name = 'guide::demo2'
)
方法 create 具有 1 个数据类型为 str 的参数 stopwatch_name，该参数指示新创建并添加的 Stopwatch 实例唯一名称。创建并添加后，该方法返回数据类型为 Stopwatch 的 Stopwatch 实例对象。
我们还可以创建并添加一个 Stopwatch 实例后，使它开始计时。
new_stopwatch: Stopwatch = demo_manager.create_and_start(
    stopwatch_name = 'guide::demo2'
)
移除 Stopwatch
当我们需要从 Stopwatch 管理器中移除指定唯一名称的 Stopwatch 实例时，我们可以这样做。
demo_manager.remove(
    stopwatch_name = 'guide::demo2'
)
如果需要移除所有 Stopwatch 实例，可以使用 clear 方法。
demo_manager.clear()
请注意，如果指定 Stopwatch 实例唯一名称不存在，将引发 StopwatchNameError 异常。
获得 Stopwatch
当我们需要在项目全局范围内共享 Stopwatch 实例时，无需维护这些 Stopwatch 实例，而是使用 Stopwatch 实例的唯一名称从 Stopwatch 管理器中获得它。
demo_stopwatch: Stopwatch = demo_manager.get(
    stopwatch_name = 'guide::demo1'
)
如果我们需要确定一个 Stopwatch 实例是否存在，可以使用 has 方法检查。
if not demo_manager.has(
    stopwatch_name = 'guide::demo2'
):
    print('no such stopwatch')
管理 Stopwatch
获取实例个数
当我们需要获取指定 Stopwatch 管理器已托管的 Stopwatch 实例个数时，可以使用 get_count 方法。
number_of_stopwatchs: int = demo_manager.get_count()
方法 get_count 具有 int 数据类型的返回值，其指示 Stopwatch 实例个数。
使实例开始计时
当我们需要使指定一批或全部 Stopwatch 实例开始计时时，可以使用 starts 方法。
demo_manager.starts(
    stopwatch_names = [
        'guide::demo1', 
        ...
    ]
)
方法 starts 有一个数据类型为 list 的可选参数 stopwatch_names，其指示需要开始的 Stopwatch 实例的唯一名称列表。如果未提供此参数或值为 None，则使所有 Stopwatch 实例开始计时。
该方法返回数据类型为 int 的返回值，指示实际开始的 Stopwatch 实例个数。
请注意，如果有一个或多个实例已经开始计时，该方法将跳过而非引发 StatusError 异常。
使实例停止计时
同样的，我们也可以使指定一批或全部 Stopwatch 实例停止计时。
demo_manager.stops(
    stopwatch_names = [
        'guide::demo1', 
        ...
    ]
)
该方法返回数据类型为 int 的返回值，指示实际停止的 Stopwatch 实例个数。
请注意，如果有一个或多个实例已经停止计时，该方法将跳过而非引发 StatusError 异常。
使实例重置
除了开始计时、停止计时外，我们也可以使指定一批或全部 Stopwatch 实例重置。
demo_manager.resets(
    stopwatch_names = [
        'guide::demo1', 
        ...
    ]
)
获取实例总计时时长
当我们需要获取指定一批或全部 Stopwatch 实例的当前总计时时长时，可以使用 get_watchs 方法。
total_of_watch: float = demo_manager.get_watchs(
    stopwatch_names = [
        'guide::demo1', 
        ...
    ], 
    watch_precision = 3
)
方法 get_watchs 相对于上文所提及的其他方法有一个额外数据类型为 int 的可选参数 watch_precision，其指示获取总计时时长的精度（小数点位数）。如果未提供此参数或值为 None，其行为与 Stopwatch 实例的 get_watch 方法对参数 watch_precision 的行为一致。
示例
源代码
quickstart.py
# quickstart.py is python-3.7.4 source file
​
import time
​
from stopwatch import Stopwatch
from stopwatch import StopwatchManager
​
​
# define main function
​
def main():
​
    # create a stopwatch manager
    
    demo_manager: StopwatchManager = StopwatchManager(
        max_stopwatch_count = 64
    )
    
    # Start timing after creating and adding a stopwatch instance to the manager
    
    demo_manager.create('guide::demo1').start()
    
    # simulated program time-consuming operation
    
    time.sleep(1)
    
    # get the stopwatch instance from the manager and stop timing.
    
    demo_manager.get('guide::demo1').stop()
    
    # total time duration after getting a stopwatch instance from the manager
    
    print(demo_manager.get('guide::demo1').get_watch())
    
    # remove the stopwatch instance from the manager.
    
    demo_manager.remove('guide::demo1')
​
​
# define virtual main function
​
if __name__ == '__main__':
    main()
运行结果
1.0
Python - Previous
入门
Next - Python
更新日志
Last modified 3yr ago
参数名	类型	必选	描述
stopwatch_name	str	True	Stopwatch 实例唯一名称。
stopwatch_instance	Stopwatch	True	被添加的 Stopwatch 实例对象。