earwax.promises.staggered_promise module

Provides the StaggeredPromise class.

class earwax.promises.staggered_promise.StaggeredPromise(func: Callable[[...], Generator[float, None, T]])

Bases: earwax.promises.base.Promise

A promise that can suspend itself at will.

I found myself missing the MOO-style suspend() function, so thought I’d make the same capability available in earwax:

@StaggeredPromise.decorate
def promise() -> StaggeredPromiseGeneratorType:
    game.output('Hello.')
    yield 2.0
    game.output('World.')

promise.run()
game.run(window)

This class supports all the promise events found on earwax.Promise, and also has a on_next() event, which will fire whenever a promise suspends:

@promise.event
def on_next(delay: float) -> None:
    print(f'I waited {delay}.')

Variables:

• func – The function to run.
• generator – The generator returned by self.func.

cancel() → None

Cancel this promise.

Cancels self.generator, and sets the proper state.

classmethod decorate(func: Callable[[...], Generator[float, None, T]]) → earwax.promises.staggered_promise.StaggeredPromise

Make an instance from a decorated function.

This function acts as a decorator method for returning earwax.StaggeredPromise instances.

Using this function seems to help mypy figure out what type your function is.

Parameters:func – The function to decorate.

do_next(dt: Optional[float]) → None

Advance execution.

Calls next(self.generator), and then suspend for however long the function demands.

If StopIteration is raised, then the args from that exception are sent to the self.on_done event.

If any other exception is raised, then that exception is passed along to the self.on_error event.

Parameters:dt –

The time since the last run, as passed by pyglet.clock.schedule_once.

If this is the first time this method is called, dt will be None.

on_next(delay: float) → None

Do something when execution is advanced.

This event is dispatched every time next is called on self.func.

Parameters:delay – The delay that was requested by the function.

run(*args, **kwargs) → None

Run this promise.

Start self.func running, and set the proper state.

Parameters:

• args – The positional arguments passed to self.func.
• kwargs – The keyword arguments passed to self.func.