API Reference

class bistiming.MultiStopwatch(n=None, *args, **kwargs)

Bases: UserList

Use multiple Stopwatch to profile and compare multiple code segments.

Because this class is inheritted from UserList, it also supports all the methods in the built-in list.

Parameters:

• n (Union[int, Iterable, None]) – If n is an int, then initialize a list with n Stopwatch. If n is None, then initialize an empty list. Otherwise, directly use n to initialize a list.

• *args – Other arguments will be passed to initialize Stopwatch.

• **kwargs – Other keyword arguments will be passed to initialize Stopwatch.

format_statistics(tablefmt='fancy_grid')

Format the statistics using tabulate.

Parameters:

tablefmt (str) – See the available options in tabulate’s documentation.

get_cumulative_elapsed_time()

Get the cumulative elapsed time of each stopwatch (including the current split).

Returns:

cumulative_elapsed_time

Return type:

List[datetime.timedelta]

get_mean_per_split()

Get the mean elapsed time per split of each stopwatch (excluding the current split).

Returns:

mean_elapsed_time_per_split

Return type:

List[datetime.timedelta]

get_n_splits()

Get number of splits of each stopwatch (excluding the current split).

Returns:

n_splits

Return type:

List[int]

get_percentage()

Get the cumulative time percentage of each stopwatch (including the current split).

Returns:

cumulative_elapsed_time_percentage

Return type:

List[float]

get_statistics()

Get all statistics as a dictionary.

Returns:

statistics

Return type:

Dict[str, List]

class bistiming.Stopwatch(description='', logger=None, logging_level=20, verbose_start=True, verbose_end=True, end_in_new_line=True, prefix='...', verbose=True)

Bases: object

A logging-friendly stopwatch with splitting function.

Parameters:

• description (str) – The log to show at starting time (entering with-block or calling start()) or ending time (exiting with-block or calling split()).

• logger (Callable) – A callable that accepts logging_level as its first argument and a str to log as its first argument (basically, a logging.Logger object). If None, use six.print_(), which is similar to the built-in print() in Python 3. When using with end_in_new_line=True, it requires end and flush parameters.

• logging_level (int) – If logger is not None, this is the first argument to be passed to logger. Usually, this should be logging.{DEBUG, INFO, WARNING, ERROR, CRITICAL}. (default: logging.INFO)

• verbose_start (bool) – Wether to log at starting time (entering with-block or calling start()).

• verbose_end (bool) – Wether to log at ending time (exiting with-block or calling split()).

• end_in_new_line (bool) – Wether to log the ending log in a new line. If False, the starting log will not have a trailing new line, so the ending log can be logged in the same line. This requires logger to have end and flush parameters, or just logger=None.

• prefix (str) – The prefix added to description.

• verbose (bool) – If False, turn off all the logs, that is, verbose_start and verbose_end will be set to False.

split_elapsed_time

The elapsed time of each split (excluding the current split).

Type:

List[datetime.timedelta]

__enter__()

Call start().

__exit__(exc_type, exc, exc_tb)

Call pause() and then split().

get_cumulative_elapsed_time()

Get the cumulative elapsed time without considering splits.

get_elapsed_time()

Get the elapsed time of the current split.

log_elapsed_time(prefix='Elapsed time: ')

Log the elapsed time of the current split.

Parameters:

prefix (str) – The prefix of the log.

pause()

Pause the stopwatch.

If the stopwatch is already paused, nothing will happen.

reset()

Reset the stopwatch.

split(verbose=None, end_in_new_line=None, message_format='done in {elapsed_time}')

Save the elapsed time of the current split and restart the stopwatch.

The current elapsed time will be appended to split_elapsed_time. If the stopwatch is paused, then it will remain paused. Otherwise, it will continue running.

Parameters:

• verbose (Optional[bool]) – Wether to log. If None, use verbose_end set during initialization.

• end_in_new_line (Optional[bool]]) – Wether to log the description. If None, use end_in_new_line set during initialization.

• message_format (str) – The string that will be formatted using message_format.format(...) and be logged as the ending message. Available variables: elapsed_time.

start(verbose=None, end_in_new_line=None)

Start the stopwatch if it is paused.

If the stopwatch is already started, then nothing will happen.

Parameters:

• verbose (Optional[bool]) – Wether to log. If None, use verbose_start set during initialization.

• end_in_new_line (Optional[bool]]) – If False, prevent logging the trailing new line. If None, use end_in_new_line set during initialization.