API Documentation#

class hiro.Timeline(scale=1, start=None)[source]#

Timeline context manager. Within this context the builtins time.time(), time.sleep(), datetime.datetime.now(), datetime.date.today(), datetime.datetime.utcnow() and time.gmtime() respect the alterations made to the timeline.

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)[source]#

forwards the timeline by the specified amount

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

freeze(target_time=None)[source]#

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()[source]#: resets the current timeline to the actual time now with a scale factor 1

rewind(amount)[source]#

rewinds the timeline by the specified amount

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

scale(factor)[source]#

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()[source]#: 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_async(factor, func, *args, **kwargs)[source]#

Asynchronously 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.ScaledAsyncRunner

hiro.run_sync(factor, func, *args, **kwargs)[source]#

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

class hiro.core.ScaledRunner(factor, func, *args, **kwargs)[source]#

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

get_execution_time()[source]#

Returns: the real execution time of func in seconds

get_response()[source]#

Returns: the return value from func
Raises: Exception if the func raised one during execution

class hiro.core.ScaledAsyncRunner(*args, **kwargs)[source]#

manages the asynchronous 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()[source]#

Rtype bool: whether the func is still running or not.

join()[source]#: waits for the func to complete execution.