API Documentation¶
instrument¶
you are not expected to understand this implementation. that’s why it has tests. the above-mentioned ‘you’ includes the author. :-}
-
instrument.
iter
(iterable, name=None, metric=<function call_default>)¶ Measure total time and element count for consuming an iterable
Parameters: - iterable – any iterable
- metric (function) – f(name, count, total_time)
- name (str) – name for the metric
-
instrument.
each
(iterable, name=None, metric=<function call_default>)¶ Measure time elapsed to produce each item of an iterable
Parameters: - iterable – any iterable
- metric (function) – f(name, 1, time)
- name (str) – name for the metric
-
instrument.
reduce
(name=None, metric=<function call_default>)¶ Decorator to measure a function that consumes many items.
The wrapped
func
should take either a singleiterable
argument or*args
(plus keyword arguments).Parameters: - metric (function) – f(name, count, total_time)
- name (str) – name for the metric
-
instrument.
produce
(name=None, metric=<function call_default>)¶ Decorator to measure a function that produces many items.
The function should return an object that supports
__len__
(ie, a list). If the function returns an iterator, useiter.func()
instead.Parameters: - metric (function) – f(name, count, total_time)
- name (str) – name for the metric
-
instrument.
func
(name=None, metric=<function call_default>)¶ Decorator to measure function execution time.
Parameters: - metric (function) – f(name, 1, total_time)
- name (str) – name for the metric
-
instrument.
first
(iterable, name=None, metric=<function call_default>)¶ Measure time elapsed to produce first item of an iterable
Parameters: - iterable – any iterable
- metric (function) – f(name, 1, time)
- name (str) – name for the metric
-
instrument.
block
(name=None, metric=<function call_default>, count=1)¶ Context manager to measure execution time of a block
Parameters: - metric (function) – f(name, 1, time)
- name (str) – name for the metric
- count (int) – user-supplied number of items, defaults to 1
-
instrument.
print_metric
(name, count, elapsed)¶ A metric function that prints
Parameters: - name (str) – name of the metric
- count (int) – number of elements
- elapsed (float) – time in seconds
-
instrument.
default_metric
(name, count, elapsed)¶ A metric function that prints
Parameters: - name (str) – name of the metric
- count (int) – number of elements
- elapsed (float) – time in seconds
-
instrument.
make_multi_metric
(*metrics)¶ Make a new metric function that calls the supplied metrics
Parameters: metrics (functions) – metric functions Return type: function
instrument.csv¶
-
class
instrument.csv.
CSVDirMetric
(name)¶ Write metrics to multiple CSV files
Do not create instances of this class directly. Simply pass the classmethod
metric()
to a measurement function. Output usingdump()
. These are the only public methods.Each metric consumes one open file and 32K of memory while running.
Variables: - dump_atexit – automatically call
dump()
when the interpreter exits. Defaults to True. - outdir – directory to save CSV files in. Defaults to
./mit_csv
.
-
classmethod
dump
()¶ Output all recorded metrics
-
classmethod
metric
(name, count, elapsed)¶ A metric function that writes multiple CSV files
Parameters: - name (str) – name of the metric
- count (int) – number of elements
- elapsed (float) – time in seconds
- dump_atexit – automatically call
-
class
instrument.csv.
CSVFileMetric
(outfile='mit.csv', dump_atexit=True)¶ Write metrics to a single CSV file
Pass the method
metric()
to a measurement function. Output usingdump()
. These are the only public methods.Variables: - outfile – file to save to. Defaults to
./mit.csv
. - dump_atexit – automatically call
dump()
when the interpreter exits. Defaults to True.
-
dump
()¶ Output all recorded metrics
-
metric
(name, count, elapsed)¶ A metric function that writes a single CSV file
Parameters: - name (str) – name of the metric
- count (int) – number of elements
- elapsed (float) – time in seconds
- outfile – file to save to. Defaults to
instrument.numpy¶
numpy-based metrics
-
class
instrument.numpy.
NumpyMetric
¶ Do not create instances of this class directly. Simply pass the classmethod
metric()
to a measurement function. Output usingdump()
. These are the only public methods. This is an abstract base class; you should use one of the concrete subclases in this module instead.Each metric consumes one open file and 32K of memory while running. Output requires enough memory to load all data points for each metric.
Variables: dump_atexit – automatically call dump()
when the interpreter exits. Defaults to True.-
classmethod
metric
(name, count, elapsed)¶ A metric function that buffers through numpy
Parameters: - name (str) – name of the metric
- count (int) – number of elements
- elapsed (float) – time in seconds
-
classmethod
dump
()¶ Output all recorded metrics
-
classmethod
-
class
instrument.numpy.
TableMetric
¶ Print a table of statistics
Variables: outfile – output file. Defaults to sys.stderr
.
-
class
instrument.numpy.
PlotMetric
¶ Plot graphs of metrics.
Variables: outdir – directory to save plots in. Defaults to ./mit_plots
.