API Reference

Top Level Functions

human_readable(seconds: float) → str

Convert seconds to a human-readable format.

Parameters:

seconds – The number of seconds to convert.

Returns:

The human-readable format of the seconds.

Return type:

str

Stopwatch Class

class Stopwatch(name: str = 'stw', verbose: bool = False)

Bases: object

A simple stopwatch class that can be used to time code execution.

__init__(name: str = 'stw', verbose: bool = False)

Initialize the stopwatch.

Parameters:

• name – Name for this stopwatch instance, used in verbose output.

• verbose – Whether to automatically print output for every function call.

now() → float

Get the current system time.

Returns:

The current time in seconds

Return type:

current_time

property laps: list[tuple[str, float, float, float]]

Get the list of recorded laps.

Returns:

A list of tuples containing (lap_name, timestamp, total_time, lap_time) for each recorded lap.

Return type:

list[tuple[str, float, float, float]]

lap(lap_name: str = None) → tuple[float, float]

Record a lap in the stopwatch.

If initialized with verbose=True, prints the lap time and total time since the stopwatch was started.

Parameters:

lap_name – The name of the lap. If not provided, the name will be “lap n” where n is the lap number.

Returns:

A tuple containing (total_time, lap_time) - the time it took to complete the lap, and total time since the stopwatch was started.

Return type:

tuple[float, float]

get_lap(index: int = None, name: str = None) → tuple[float, float, float]

Get a lap by index or name.

> Please provide only one of index or name!

Parameters:

• index – The index of the lap to get.

• name – The name of the lap to get.

Returns:

A tuple containing (timestamp, total_time, lap_time) for the requested lap.

Return type:

tuple[float, float, float]

elapsed_total(name: str = None) → float

Get the total time since the stopwatch was started until the lap.

Parameters:

name – The name of the lap to get the time until. If not provided, the time until the last lap will be returned.

Returns:

The total time since the stopwatch was started

Return type:

total_time

elapsed_since_lap(name: str = None) → float

Get the time elapsed since the last lap.

Parameters:

name – The name of the lap to get the time elapsed since. If not provided, the time elapsed since the last lap will be returned.

Returns:

The time elapsed since the last lap.

Return type:

elapsed_time

__str__() → str

Get a string representation of the stopwatch.

Returns:

The string representation of the stopwatch.

Return type:

str

__repr__() → str

Get a string representation of the stopwatch.

Returns:

The string representation of the stopwatch.

Return type:

str

__enter__()

__exit__(exc_type, exc_val, exc_tb)

time_function(func, *args, **kwargs) → tuple[float, any]

Time the execution of a function.

Parameters:

• func – The function to time

• *args – The positional arguments to pass to the function

• **kwargs – The keyword arguments to pass to the function

Returns:

A tuple containing (elapsed_time, result) where elapsed_time is the time it took

to execute the function and result is the return value of the function

Return type:

tuple[float, any]

print_diagram()

Print a visual diagram of the stopwatch laps.

This displays a visual representation of lap times with proportional spacing and labeled duration, making it easy to compare relative lap times.

Returns:

None

Error Handling

The Stopwatch class raises the following exceptions:

• ValueError: When accessing invalid laps or providing invalid arguments