API

pytimer.py

Table of Contents

• pytimer.PyTimer
  • PyTimer.microseconds
  • PyTimer.milliseconds
  • PyTimer.nanoseconds
  • PyTimer.rounding
  • PyTimer.seconds
  • PyTimer.elapsed() (static)
  • PyTimer.time_it() (static)
  • PyTimer.average()
  • PyTimer.averages()
  • PyTimer.decorator()
  • PyTimer.deviation()
  • PyTimer.deviations()
  • PyTimer.display_average()
  • PyTimer.display_averages()
  • PyTimer.display_deviation()
  • PyTimer.display_deviations()
  • PyTimer.display_overall_time()
  • PyTimer.display_split()
  • PyTimer.display_splits()
  • PyTimer.log()
  • PyTimer.overall_time()
  • PyTimer.pause()
  • PyTimer.reset()
  • PyTimer.resume()
  • PyTimer.split()
  • PyTimer.start()
  • PyTimer.time()
  • PyTimer.times()
  • PyTimer.write_output()

• class PyTimer

  PyTimer is a class for easily timing execution of sections of codes. PyTimer supports splitting to allow different segments of code to be timed separately.

  • Constants

    • microseconds = "us"
    • milliseconds = "ms"
    • nanoseconds = "ns"
    • rounding = 4
    • seconds = "s"

  • Static Methods

    • elapsed(display=True, message="")

      Allows the elapsed time to be easily checked using repeated calls to this. There must be an initial call that gets the start time.

      • display (optional): whether to display the elapsed time, or to return it as a value
      • message (optional): if display==True, this message will be attached with the output that is displayed
      • return: the elapsed time if display==False

    • time_it(block, *args, reps=1, runs_per_rep=10, display=True, message="", callable_args=False, **kwargs)

      A static method that allows timing a function or string of code without creating a PyTimer object

      • block: either a callable, or a string
      • args: any positional arguments to be passed into block if it is a function
      • reps (optional): the number of times to average the elapsed time
      • runs_per_rep (optional): the number of runs for every rep. Useful if block is generally called multiple times
      • display (optional): if True, then display the calculated time, else, return the value
      • message (optional): if display==True, then this message will be displayed with the calculated value
      • callable_args (optional): whether to look through args and kwargs and see if any parameters are callable. If so, replace their value with the value returned from calling them. Only works if block is callable.
      • kwargs: any keyword arguments to be passed into block if it is a function
      • return: If block is not callable or a string, then None is returned. If display==True, then nothing is returned, else if display==False, the calculated time is returned

  • Methods

    • average(self, i: int)

      Calculates average for split i

      • i: Index of split to determine average for
      • return: None if empty split, False if invalid index, otherwise average for split

    • averages(self) -> list

      Returns list of averages for every split

      • return: list of averages, if position i is invalid, then list[i] is None

    • decorator(self, reps=1, runs_per_rep=1, callable_args=False) -> callable

      Function used as a decorator for timing functions. Decorator can have arguments, which allows the reps, runs_per_rep and whether the args are callable to be set for each function this is being used on. To use: @timer.decorator(reps=10, callable_args=True), where timer is a PyTimer instance.

      • reps (optional): the number of times to average the elapsed time
      • runs_per_rep (optional): the number of runs for every rep. Useful if block is generally called multiple times
      • callable_args (optional): whether to look through args and kwargs that are being passed to the function being decorated and see if any parameters are callable. If so, replace their value with the value returned from calling them.
      • return: a function that takes the function being decorated as a parameter

    • deviation(self, i: int)

      Calculates standard deviation for split i

      • i: split index
      • return: None if split i is empty, False if invalid index, otherwise returns standard deviation of split i

    • deviations(self) -> list

      Calculates standard deviations for every split

      • return: list of standard deviations for all splits. If split i is empty, than list[i] is None

    • display_average(self, i: int)

      Display average for split i if valid index and split is not empty, otherwise displays appropriate message

      • i: split index

    • display_averages(self)

      Display averages for all splits unless split i is empty, in which case it is skipped

    • display_deviation(self, i: int)

      Display standard deviation for split i if valid index and split is not empty, otherwise displays appropriate message

      • i: split index

    • display_deviations(self)

      Display standard deviation for all splits unless split is empty, in which case that split is skipped

    • display_overall_time(self)

      Display time since last start() or reset(). This time includes that time taken to execute PyTimer method calls

    • display_split(self, i: int)

      Display all values in split i if valid index and split is not empty, otherwise displays appropriate message

      • i: split index

    • display_splits(self)

      Display all values for all splits unless split is empty, in which case the split is skipped

    • log(self, message="")

      Log elapsed time, log will have no affect if timer is paused

      • message (optional): optional: store message with the log

    • overall_time(self) -> float

      • return: Elapsed time since start() in seconds, includes time to execute PyTimer method calls

    • pause(self)

      Pause the timer, meaning no actions can be performed, allows portions of code to be skipped

    • reset(self)

      Clear the timer back to its defaults

    • resume(self)

      Resume the timer from being paused, updates the internal clock to the current time

    • split(self, message="")

    • start(self)

    • time(self, block, *args, reps=10, runs_per_rep=10, split_message="", callable_args=False, **kwargs)

      Times a string of code or a function and times how long it takes for each iteration. If block is a function, then parameters can be passed to it like so: time(bar, "something", 12, runs_per_rep=100) -> bar("something", 12). No error checking is done, meaning any error that is raised within block will crash the entire program.

      • block: either function or string of code
      • args: any arguments that needs to be passed into block if block is a function
      • reps (optional): the number of times to average the elapsed time
      • runs_per_rep (optional): the number of runs for every rep. Useful if block is generally called multiple times
      • split_message (optional): the message that will be recorded with this split
      • callable_args (optional): whether to look through args and kwargs and see if any parameters are callable. If so, replace their value with the value returned from calling them. Only works if block is callable.
      • kwargs: keyword arguments that will be passed into block if it is a function

    • times(self, i: int)

      Return list of elapsed times for split i

      • i: index of split
      • return: returns list of elapsed times for split i if valid index, otherwise returns None

    • write_output(self, folder_path: str, basename: str, file_per_run=False)

      Write all collected output to a file, assuming that _collect_output was set in constructor. File is either written to folder_path + basename if file_per_run is false or folder_path + basename + date_time where date_time is formatted "-day-month-year-hours-minutes-seconds". All files are written to .txt format

      • folder_path: Path of folder to write to
      • basename: Name of file
      • file_per_run (optional): Create a new file with every run