Skip to content
Back to top
View this page

# API Documentation

class hiro.Timeline(scale=1, start=None)

  Timeline context manager. Within this context the following builtins respect the alterations made to the timeline:

  - `time.time()`

  - `time.time_ns()`

  - `time.monotonic()`

  - `time.monotonic_ns()`

  - `time.sleep()`

  - `time.localtime()`

  - `time.gmtime()`

  - `datetime.datetime.now()`

  - `datetime.date.today()`

  - `datetime.datetime.utcnow()`

  The class can be used either as a context manager or a decorator.

  The following are all valid ways to use it.

      with Timeline(scale=10, start=datetime.datetime(2012,12,12)):
          ....

      fast_timeline = Timeline(scale=10).forward(120)

      with fast_timeline as timeline:
          ....

      delta = datetime.date(2015,1,1) - datetime.date.today()
      future_frozen_timeline = Timeline(scale=10000).freeze().forward(delta)
      with future_frozen_timeline as timeline:
          ...

      @Timeline(scale=100)
      def slow():
          time.sleep(120)

  Parameters:

    - scale (float) – > 1 time will go faster and < 1 it will be slowed down.

    - start – if specified starts the timeline at the given value (either a floating point representing seconds since epoch or a `datetime.datetime` object)

  forward(amount)

    forwards the timeline by the specified `amount`

    Parameters:

      amount – either an integer representing seconds or a `datetime.timedelta` object

  freeze(target_time=None)

    freezes the timeline

    Parameters:

      target_time – the time to freeze at as either a float representing seconds since the epoch or a `datetime.datetime` object. If not provided time will be frozen at the current time of the enclosing `Timeline`

  reset()

    resets the current timeline to the actual time now with a scale factor 1

  rewind(amount)

    rewinds the timeline by the specified `amount`

    Parameters:

      amount – either an integer representing seconds or a `datetime.timedelta` object

  scale(factor)

    changes the speed at which time elapses and how long sleeps last for.

    Parameters:

      factor (float) – > 1 time will go faster and < 1 it will be slowed down.

  unfreeze()

    if a call to `freeze()` was previously made, the timeline will be unfrozen to the point which `freeze()` was invoked.

    Warning

    Since unfreezing will reset the timeline back to the point in when the `freeze()` was invoked - the effect of previous invocations of `forward()` and `rewind()` will be lost. This is by design so that freeze/unfreeze can be used as a checkpoint mechanism.

hiro.run_sync(factor, func, *args, **kwargs)

  Executes a callable within a `hiro.Timeline`

  Parameters:

    - factor (int) – scale factor to use for the timeline during execution

    - func (function) – the function to invoke

    - args – the arguments to pass to the function

    - kwargs – the keyword arguments to pass to the function

  Returns:

    an instance of `hiro.core.ScaledRunner`

hiro.run_threaded(factor, func, *args, **kwargs)

  Executes a callable in a separate thread within a `hiro.Timeline`

  Parameters:

    - factor (int) – scale factor to use for the timeline during execution

    - func (function) – the function to invoke

    - args – the arguments to pass to the function

    - kwargs – the keyword arguments to pass to the function

  Returns:

    an instance of `hiro.core.ScaledThreadedRunner`

hiro.run_async(factor, func, *args, **kwargs)

  Executes a callable in a separate thread within a `hiro.Timeline`

  Parameters:

    - factor (int) – scale factor to use for the timeline during execution

    - func (function) – the function to invoke

    - args – the arguments to pass to the function

    - kwargs – the keyword arguments to pass to the function

  Returns:

    an instance of `hiro.core.ScaledAsyncRunner`

  Deprecated since version 1.0.0: Use `run_threaded()`

class hiro.core.ScaledRunner(factor, func, *args, **kwargs)

  manages the execution of a callable within a `hiro.Timeline` context.

  get_execution_time()
    Returns:

      the real execution time of `func` in seconds

  get_response()
    Returns:

      the return value from `func`

    Raises:

      Exception if the `func` raised one during execution

class hiro.core.ScaledThreadedRunner(*args, **kwargs)

  manages the threaded execution of a callable within a `hiro.Timeline` context.

  get_execution_time()
    Returns:

      the real execution time of `func` in seconds

  get_response()
    Returns:

      the return value from `func`

    Raises:

      Exception if the `func` raised one during execution

  is_running()
    Rtype bool:

      whether the `func` is still running or not.

  join()

    waits for the `func` to complete execution.

hiro.core.ScaledAsyncRunner

  alias of `ScaledThreadedRunner`