API Documentation

This is the documentation for the classes contained in unitbench.

Benchmark

This is the main class to extend when using unitbench.

class unitbench.Benchmark

run([reporter=None])

If the reporter is None the ConsoleReporter is used.

This should generally not be overloaded. It runs the benchmark functions that are found in the child class. Benchmark functions are discovered by looking for methods starting with bench.

input()

Hook method for providing the input to the benchmark. None should not be passed into a benchmark function. It is used as a marker that no arguments are present.

A list containing only 0 is used as a default.

repeats()

Hook method for the number of times to repeat the benchmark (default 7)

setup()

Hook method called once before every run of each benchmark.

teardown()

Hook method called once after every run of each benchmark.

warmup()

Hook method for the number of warmup runs to do (default 1)

The warmup will run for each benchmark function with each value.

ConsoleReporter

This is the default reporter for unitbench. It will it writes out results in the following format:

Value: 1000                                   user       sys      real
======================================================================
Benchmark 01                                   0.0       0.0 0.0009084
Benchmark 02                                   0.0       0.0 1.816e-06

class unitbench.ConsoleReporter

__init__([output_stream=sys.stdout])

Will write the output formatted as above to the given file-type stream. It does not open or close the stream, so make sure to handle that outside of this method.

The only method called on the stream is write(str), so any object with a write function should work.

CsvReporter

This is an alternative reporter for unitbench. It writes the output to a csv format for easy ingestion into spreadsheet programs.

class unitbench.CsvReporter

__init__([output_stream=sys.stdout[, time_type="wall"]])

As with the ConsoleReporter this reporter also takes a stream to write its output. It also has a second parameter time_type. time_type can be “wall”, “system”, or “user”. It denotes which type of time for which to retrieve the average.

Type	Definition
wall	Wall clock time.
user	User CPU time.
system	System or kernel CPU time.

Reporter

class unitbench.Reporter

This is the base class for benchmark result reporting. If you’d like to write a custom importer this is the class to extend.

write_results(value, results)

Override this method to output the results of the benchmark run. Value is the value passed into each benchmark. Results is a list of BenchResult objects. See the BenchResult documentation for the information it contains.

write_titles(titles)

Override this method if you’d like to write out the titles at the beginning of your reporter. The CsvReporter uses this function to output the titles at the top of each column. Alternatively, the ConsoleReporter doesn’t override this function because it doesn’t need to output the titles of each benchmark.

BenchResult

Using this class is only necessary if you’re writing a new results reporter. It is passed into the write_results method of the various reporters.

class unitbench.BenchResult(name, value, times)

This contains the results of running a benchmark.

It contains the mean, variance, standard deviation, minimum, and maximum. Each of these attributes are available for user, wall, and system time.

Times:

• wall
• user
• system

Statistics:

• min
• max
• mean
• variance
• std_dev (standard deviation)

Combine one of the times and one of the statistics to get the appropriate attribute.

Examples:

• wall_mean - Mean wall clock time
• user_std_dev - Standard deviation of user time
• system_variance - Variance of system (kernel) time
• wall_min - Minimum wall clock time
• and so on...