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