earwax.promises.base module

Provides the base Promise class, and the PromisesStates enumeration.

class earwax.promises.base.Promise

Bases: typing.Generic, earwax.mixins.RegisterEventMixin

The base class for promises.

Instances of this class have a few possible states which are contained in the PromiseStates enumeration.

Variables:state – The state this promise is in (see above).
cancel() → None

Override to provide cancel functionality.

done(value: T) → None

Finish up.

Dispatches the on_done() event with the given value, and set self.state to earwax.PromiseStates.done.

Parameters:value – The value that was returned from whatever function this promise had.
error(e: Exception) → None

Handle an error.

This event dispatches the on_error() event with the passed exception.

Parameters:e – The exception that was raised.
on_cancel() → None

Handle cancellation.

This event is dispatched when this instance has its cancel() method called.

on_done(result: T) → None

Handle return value.

This event is dispatched when this promise completes with no error.

Parameters:result – The value returned by the function.
on_error(e: Exception) → None

Handle an error.

This event is dispatched when this promise raises an error.

Parameters:e – The exception that was raised.
on_finally() → None

Handle this promise comise completing.

This event is dispatched when this promise completes, whether or not it raises an error.

run(*args, **kwargs) → None

Start this promise running.

class earwax.promises.base.PromiseStates

Bases: enum.Enum

The possible states of earwax.Promise instances.

Variables:
  • not_ready –

    The promise has been created, but a function must still be added.

    How this is done depends on how the promise subclass in question has been implemented, and may not always be used.

  • ready – The promise has been created, and a function registered. The run() method has not yet been called.
  • running – The promise’s run() method has been called, but the function has not yet returned a value, or raised an error.
  • done – The promise has finished, and there was no error. The on_done() and on_finally() events have already been dispatched.
  • error –

    The promise completed, but there was an error, which was handled by the on_error() event.

    The on_finally() event has been dispatched.

  • cancelled – The promise has had its cancel() method called, and its on_cancel() event has been dispatched.
cancelled = 5
done = 3
error = 4
not_ready = 0
ready = 1
running = 2