API

API

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

• 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(BaseTimer)

    • (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