timeutils.stopwatch module

Stopwatch

class timeutils.stopwatch.Stopwatch(start=False, verbose=False, label=None, logger=None, logger_level=None)[source]

Provides a set of methods and properties that you can use to accurately measure elapsed time.

Parameters:
  • start (bool, optional) – if set to True, immediately starts measuring the time (by calling start()). By default set to False.
  • verbose (bool, optional) – if set to True, logs the elapsed time when the stop() method is called. By default set to False.
  • label (str, optional) – Optional stopwatch label to be included in the log messages (only if verbose is True).
  • logger (logging.Logger, optional) – logger object for logging stopwatch messages if verbose is True. If set to None (the default), the logger is set to sys.stdout.
  • logger_level (int, optional) – logging level as defined in the build-in logging package (only if the logger object is set).

Examples

Simple time measurement:

sw = Stopwatch(start=True)
# code to be measured
sw.stop()

Getting the elapsed time:

print(sw.elapsed)  # hh:mm:ss.ms
print(sw.elapsed.human_str())  # human-readable time

Restarting the stopwatch instance:

sw.restart()

Pausing and resuming the stopwatch:

sw.suspend()
# code block not included in the measurement
sw.resume()

Using a logger:

import logging

logger = logging.getLogger()
logger.setLevel(logging.INFO)
logger.addHandler(logging.FileHandler(filename='example.log'))

sw = Stopwatch(verbose=True, label='Example', logger=logger)
sw.start()
# code to be measured
sw.stop()

Note

Stopwatch methods are protected against inappropriate calls. It is an error to start or stop a Stopwatch object that is already in the desired state.

See also

Documentation of the TimeSpan class.

elapsed

The total elapsed time measured by the current instance.

elapsed_seconds

The total elapsed time in fractions of a second measured by the current instance.

is_running

Indicates whether the Stopwatch instance is running.

is_suspended

Indicates whether the Stopwatch instance is suspended.

reset()[source]

Stops time interval measurement and resets the Stopwatch instance. The time elapsed before reset is set to zero.

restart()[source]

Stops time interval measurement, resets the Stopwatch instance, and starts measuring elapsed time. The time elapsed before restart is set to zero.

resume()[source]

Resumes measuring elapsed time after calling suspend().

start()[source]

Starts measuring elapsed time for an interval.

start_time

The datetime at which the time measurement has been started.

Changed in version 0.3.2: Returns a datetime object instead of a float timestamp.

stop()[source]

Stops the time measurement. Returns the total elapsed time measured by the current instance.

stop_time

The datetime at which the time measurement has been stopped.

Changed in version 0.3.2: Returns a datetime object instead of a float timestamp.

suspend()[source]

Pauses the time measurement until the Stopwatch instance is resumed or stopped. Returns the total elapsed time measured by the current instance.

Call resume() to resume measuring elapsed time.