Skip to content

API

Jump to bottom
Jacob Morris edited this page Jun 8, 2019 · 31 revisions

API

Below all files, classes, and methods are documented that are relevant to the use of ExecTiming.

  • exectiming.exectiming

  • exectiming.best_fit_curves

  • exectiming.output_wrappers

  • exectiming.exectiming

    • BaseTimer

      • S: time unit - seconds
      • MS: time unit - milliseconds (10^-3)
      • US: time unit - microseconds (10^-6)
      • NS: time unit - nanoseconds (10^-9)

    • StaticTimer

      • (static) context(*args, runs=1, iterations_per_run=1, label="Context", time_unit=BaseTime.MS, output_stream: TextIO=stdout, **kwargs)

        Provides a context manager that can be used with a with statement as with StaticTimer.context():. The only option is to output the measured time.

        • args: any arguments to log with the run
        • runs: how many times the execution time of the wrapped function will be measured
        • iterations_per_run: how many times the wrapped function will be called for each run. The time for the run will the sum of the times of iterations
        • label: the label for the run
        • time_unit: the time scale to output the values in
        • output_stream: the file-like object to write any output to if display
        • kwargs: any keyword arguments to log with the run

      • (static) decorate(runs=1, iterations_per_run=1, average_runs=True, display=True, time_unit=BaseTimer.MS, output_stream: TextIO=stdout, call_callable_args=False, log_arguments=False) -> callable

        A decorator that will time a function and then either output the results to output_stream if display. Otherwise, the measured time(s) will be returned along with the return value of the wrapped function

        • runs: how many times the execution time of the wrapped function will be measured
        • iterations_per_run: how many times the wrapped function will be called for each run. The time for the run will the sum of the times of iterations
        • average_runs: whether to average the measured times from all the runs together or not
        • display: whether to display the measured time or to return it as Tuple[function return value: any, times: Union[float, List[float]]]
        • time_unit: the time scale to output the values in
        • output_stream: the file-like object to write any output to if display
        • call_callable_args: If True, then any callable arguments/parameters that are passed into the wrapped function will be replaced with their return value. So wrapped(callable) will actually be wrapped(callable())
        • log_arguments: whether to keep track of the arguments so they can be displayed if display
        • return: a function wrapper

      • (static) elapsed(display=True, time_unit=BaseTimer.MS, output_stream: TextIO=stdout, label="Elapsed", reset=False) -> Union[None, float]

        Determine how much time has elapsed since the last call to .start() or .elasped(reset=True). .start()must be called before.elasped()can be. The elapsed time will either be displayed ifdisplay` or otherwise will be returned as a float.

        • display: whether to display the measured time or to return it
        • time_unit: the unit to display the measured time in
        • output_stream: the file-like object to write any output to if display
        • label: the label to use if displaying the measured time
        • reset: call .start() after calculating the elapsed time. Removes the need to call .start() again and so .elapsed() can be called successively.
        • return: If display, then None is returned. Otherwise, the elapsed time is returned as a float in time_unit

      • (static) start()

        Log the current time so .elapsed() can be called. Must be called before .elapsed() can be called for the first time.

      • (static) time_it(block: Union[str, callable], *args, runs=1, iterations_per_run=1, average_runs=True, display=True, time_unit=BaseTimer.MS, output_stream: TextIO=stdout, call_callable_args=False, log_arguments=False, globals: dict=(), locals: dict=(), **kwargs) -> Union[any, Tuple[any, float], Tuple[any, List[float]]]

        Measure the execution time of a function are string. Positional and keyword arguments can be passed through to block if it is a function. eval is used if block is a string and so a namespace can be passed to it by setting globals and/or locals.

        • block: either a callable or a string
        • args: any positional arguments to pass into block if it is callable
        • runs: the number of times to measure the execution time
        • iterations_per_run: the number of times to execute the function for each run
        • average_runs: whether to average the runs together or not
        • display: whether to display the measured time or to return it
        • time_unit: the unit to display the measured time in if display
        • output_stream: the file-like object to write any output to if display
        • call_callable_args: If True, then any callable values in args and kwargs will be replaced with their return value. So time_it(func, callable1, something=callable2 will become func(callable1(), something=callable2()). Only useful if block is callable
        • log_arguments: whether to keep track of the arguments so they can be displayed if display. Only valid if block is callable
        • globals: a global namespace to pass to eval if block is a string
        • locals: a local namespace to pass to eval if block is a string
        • kwargs: any keyword arguments to pass into block if it is callable
        • return: If display, then just the return value of calling/evaluating block is returned. Otherwise, a tuple of the return value and the measured time(s) is returned. If average, then a single time value is returned. Otherwise, a list of time values, one for each run, is returned. Any returned times will be in time_unit

    • Timer(self, output_stream: TextIO=stdout, split: bool=False, label: str= "Split", indent: str= " ", start: bool=False)

      Create a new timer.

      • output_stream: the file-like object to write any output to. Must have a .write(str) method.

      • split: automatically create a split. Needed if the first calls will be to .start() and .log() as .time_it() and .decorate() create new splits for themselves by default

      • label: the label for the new split if split

      • indent: the amount to indent lines when outputting data

      • start: go ahead and call .start() to allow .log() to be called immediately. Only use if a minimal amount of time will pass between timer creation the first call to .log()

      • best_fit_curve(self, curve_type: str=any, exclude: Set[Union[str, int]]=(), split_index: Union[int, str]=-1, transformers: Union[callable, Dict[Union[str, int], callable]]=()) -> Union[None, Tuple[str, dict]]

        Determine the best fit curve for a split using logged arguments as the independent variable and the measured time as the dependent variable. By default, the most recent split is used. All non-excluded arguments must have integer values to allow curve calculation. If the values are not integers, then they must be transformed.

        • curve_type: specify a specific curve type to determine the parameters for
        • exclude: the indices of the positional arguments or keys of keyword arguments to exclude when performing curve calculation
        • split_index: The index or name of the split to determine the best fit curve for
        • transformers: function(s) that take an argument and return an integer, as integers are needed for determining the best fit curve. transformers can be formatted in one of two ways:
          1. A callable which will be used with every argument that is encountered, aka, transformers=len
          2. A map of positional argument indices and keyword argument names to the callable to use with that argument, aka, `transformers={0: len, "array": sum}
        • return: None if there is no best fit curve. Otherwise, the name of the curve and any parameters

      • context(self, *args, runs=1, iterations_per_run=1, label="Context", **kwargs)

        Provides a context manager that can be used with a with statement as with StaticTimer.context():. The only option is to output the measured time.

        • args: any arguments to log with the run
        • runs: how many times the execution time of the wrapped function will be measured
        • iterations_per_run: how many times the wrapped function will be called for each run. The time for the run will the sum of the times of iterations
        • label: the label for the run
        • kwargs: any keyword arguments to log with the run

      • decorate(self, runs=1, iterations_per_run=1, call_callable_args=False, log_arguments=False, split=True, split_label: str=None) -> callable

        A decorator that will time a function and store the measured time

        • runs: the number times to measure the execution time
        • iterations_per_run: how many times to execute the function for each run
        • call_callable_args: If True, then any callable arguments/parameters that are passed into the wrapped function will be replaced with their return value. So wrapped(callable) will actually be wrapped(callable())
        • log_arguments: whether to keep track of the arguments so they can be displayed at a later point or used for curve calculation
        • split: create a split that will be used to store any runs created
        • split_label: what the name of the new split will be. If None, then func.name will be used
        • return: a function wrapper

      • log(self, *args, runs=1, iterations_per_run=1, label="Log", reset=True, time_unit=BaseTimer.MS, **kwargs) -> float

        Log the amount of time since the last call to Timer(start=True), .start(), or to .log(reset=True). Arguments can be stored by adding them to the function call. Will automatically call .start() again unless reset=False

        • args: any arguments to store with this run
        • runs: how many runs this log point is for
        • iterations_per_run: how many iterations for each run this log point is for
        • label: the label/name for the log point
        • reset: whether to call .start() again or not
        • time_unit: the time unit that will be used for the returned value
        • kwargs: any keyword arguments to store with the run
        • return: the amount of time in time_unit since the timer was started

      • output(self, split_index: Union[int, str]=all, time_unit=BaseTimer.MS, transformers: Union[callable, Dict[Union[int, str], Union[callable, Dict[Union[int, str], callable]]]]=())

        Output all the logged runs for all of the splits or just the specified one. Transformers can be passed that will be used to transform how logged arguments appear in the output.

        • split_index: the split index/name to output. Defaults to all
        • time_unit: the time unit to output times in
        • transformers: functions that will be used to modify how logged parameters appear in the output. By default, all parameters are just passed through str, but this allows more control. There are three ways transformers can be passed.
          1. It can be a single function, which only works when all parameters across all splits being output can be transformed with this function.
          2. It can be a map of argument indices/names to functions, which only works when all arguments with that index or name across all splits being output can be transformed with the given function.
          3. It can be a map of split indices/labels to a map like that in the second option. So transformers=len, transformers={0: len, "array": sum}, and transformers={"binary_search": {0: len}, "adder": {"array": sum}} are all valid

      • plot(self, split_index: Union[str, int]=-1, key: Union[str, int]=None, transformer: callable=None, time_unit=BaseTimer.MS, y_label: str="Time", x_label: str=None, title: str=None, plot_curve: bool=False, curve: Tuple[str, dict]=None, curve_steps: int=100, equation_rounding: int=8)

        Plot the runs in the specified split or the most recent split if none is specified. If there is more than one argument logged for the runs, then a key needs to be provided to use as the independent variable. The argument's value must be an integer or a transformer must be provided.

        • split_index: the label or index of the split to plot
        • key: the integer position or keyword name of the argument to use as the independent variable
        • transformer: a transformer to make the independent variable an integer
        • time_unit: the time unit to use when plotting
        • y_label: the label for the y-axis, defaults to "Time"
        • x_label: the label for the x-axis, default to None
        • title: the title of the plot, defaults to the label of the split
        • plot_curve: plot the best fit curve. If curve=None, then the best fit curve will be determined. Otherwise, curve will be used. If the split has more than one logged argument or that argument is not an integer, then the curve will need to be determined separately.
        • curve: the curve to plot, must be formatted (curve type, params), which is how .best_fit_curve() returns it
        • curve_steps: the number of points used when drawing the best fit curve if plot_curve
        • equation_rounding: the number of decimal places to round the equation to if plot_curve

      • predict(self, parameters: Tuple[str, dict], *args, time_unit=BaseTime.MS, rounding=8, **kwargs) -> float

        Predict the execution time based on the given best fit curve and the parameters being passed in. All argument values must be integers and they must correspond in position or name to how the best-fit-curve was determined

        • parameters: the curve type and parameters of the best-fit-curve. Should be the exact result of a call to .best_fit_curve()
        • args: any positional arguments needed when predicting the execution time.
        • time_unit: the time unit to return the execution time in
        • rounding: how much to round the predicted execution time
        • kwargs: any keyword arguments to use when predicting the execution time
        • return: the predicted execution time

      • sort_runs(self, split_index: Union[str, int]=all, reverse: bool=False, keys: Union[str, int, Dict[Union[str, int], Union[str, int]]]=None, transformers: Union[callable, Dict[Union[str, int], callable]]=())

        Sort the runs in a given split, or in all splits. Sorting will default to be by time. Otherwise, it will sort by the value of the positional argument or keyword argument specified by the key(s).

        • split_index: the name or label of the split to sort
        • reverse: whether to reverse the sort order of the runs or not
        • keys: either a string name of a keyword argument or an integer index of a positional argument or a map of split indexes/labels to a string name or index position of the argument to sort on
        • transformers: either a callable or a map of split indexes/labels to callables, where the key will be used to get a value which will then be passed to this callable and the return value will be used when sorting.

      • start(self)

        Start the elapsed time. Must be called before .log() unless Timer(start=True).

      • statistics(self, split_index: Union[int, str]=all, time_unit=BaseTimer.MS)

        Output statistics for each split or for a specified split. The statistics are the number of runs, total time, average, standard deviation, and variance

        • split_index: the index or label of the split to output statistics for, defaults to all
        • time_unit: the time unit to output times in

      • split(self, label: str="Split")

        Create a new split that will be used for subsequent runs

        • label: the label of the new split

      • time_it(self, block: Union[str, callable], *args, runs=1, iterations_per_run=1, call_callable_args=False, log_arguments=False, split=True, split_label=None, globals: dict=(), locals: dict=(), **kwargs) -> any

        Measure the execution time of a function are string. Positional and keyword arguments can be passed through to block if it is a function. eval is used if block is a string and so a namespace can be passed to it by setting globals and/or locals.

        • block: either a callable or a string
        • args: any positional arguments to pass into block if it is callable
        • runs: the number of times to measure the execution time
        • iterations_per_run: the number of times to call/evaluate block for each run
        • call_callable_args: If True, then any callable in args or kwargs will be replaced with their return value. So time_it(func, callable1, something=callable2) will become func(callable1(), something=callable2()). Only useful if block is callable
        • log_arguments: whether to keep track of the arguments so they can be displayed at a later point or used for curve calculation. Only useful if block is callable
        • split: create a split that will be used for any runs created measuring the execution time of block
        • split_label: what the name of the new split will be. If None, then the label will be block.__name__ if block is callable. Otherwise, it will be the block itself.
        • globals: a global namespace to pass to eval if block is a string
        • locals: a local namespace to pass to eval if block is a string
        • kwargs: any keyword arguments to pass into block if it is callable
        • return: a return/result value of calling/evaluating block

  • exectiming.best_fit_curves

    • BestFitExponential

      Uses scipy.optimize.curve_fit to find a and b such that a + b*e^x best fits the data given. Can only handle a single independent variable. Generated parameters are a and b

    • BestFitLinear

      Uses sklearn.linear_model.LinearRegression to determine coefficients for each of the independent variables and the y-intercept. Generate parameters are the y-intercept, b, and coefficients where the key is the index of the argument or its key depending on whether it is a positional or keyword argument, respectively.

    • BestFitLogarithmic

      Uses scipy.optimize.curve_fit to find a and b such that a + b*log(x) is best fitted to the data. Can only handle a single independent variable. Generated parameters are a and b

    • BestFitPolynomial

      Uses scipy.optimize.curve_fit to find the values a, b, and, c such that ax^2 + bx + c is best fit to the data.

  • exectiming.output_wrappers

    • LoggingInfoWrapper

      Provides a basic wrapper around logging.info to allow it to act like a file-like object to be used as an output stream for the timers

    • LoggingDebugWrapper

      Provides a basic wrapper around logging.debug to allow it to act like a file-like object to be used as an output stream for the timers

Clone this wiki locally