plumpy.futures module

Module containing future related methods and classes

exception plumpy.futures.CancelledError[source]

Bases: concurrent.futures._base.Error

The Future was cancelled.

class plumpy.futures.Future(*, loop=None)

Bases: object

This class is almost compatible with concurrent.futures.Future.


  • result() and exception() do not take a timeout argument and raise an exception when the future isn’t done yet.

  • Callbacks registered with add_done_callback() are always called via the event loop’s call_soon_threadsafe().

  • This class is not compatible with the wait() and as_completed() methods in the concurrent.futures package.


Add a callback to be run when the future becomes done.

The callback is called with a single argument - the future object. If the future is already done when this is called, the callback is scheduled with call_soon.


Cancel the future and schedule callbacks.

If the future is already done or cancelled, return False. Otherwise, change the future’s state to cancelled, schedule the callbacks and return True.


Return True if the future was cancelled.


Return True if the future is done.

Done means either that a result / exception are available, or that the future was cancelled.


Return the exception that was set on this future.

The exception (or None if no exception was set) is returned only if the future is done. If the future has been cancelled, raises CancelledError. If the future isn’t done yet, raises InvalidStateError.


Return the event loop the Future is bound to.

remove_done_callback(fn, /)

Remove all instances of a callback from the “call when done” list.

Returns the number of callbacks removed.


Return the result this future represents.

If the future has been cancelled, raises CancelledError. If the future’s result isn’t yet available, raises InvalidStateError. If the future is done and has an exception set, this exception is raised.

set_exception(exception, /)

Mark the future done and set an exception.

If the future is already done when this method is called, raises InvalidStateError.

set_result(result, /)

Mark the future done and set its result.

If the future is already done when this method is called, raises InvalidStateError.

plumpy.futures.chain(source, target)[source]

Chain two futures together so that when one completes, so does the other.

The result (success or failure) of a will be copied to b, unless b has already been completed or cancelled by the time a finishes.

plumpy.futures.copy_future(source, target)[source]

Copy the status of future a to b unless b is already done in which case return

  • source (kiwipy.Future) – The source future

  • target (kiwipy.Future) – The target future

plumpy.futures.create_task(coro: Callable[], Coroutine], loop: Optional[] = None) → _asyncio.Future[source]

Schedule a call to a coro in the event loop and wrap the outcome in a future.

  • coro – a function which creates the coroutine to schedule

  • loop – the event loop to schedule it in


the future representing the outcome of the coroutine

plumpy.futures.gather(*coros_or_futures, loop=None, return_exceptions=False)[source]

Return a future aggregating results from the given coroutines/futures.

Coroutines will be wrapped in a future and scheduled in the event loop. They will not necessarily be scheduled in the same order as passed in.

All futures must share the same event loop. If all the tasks are done successfully, the returned future’s result is the list of results (in the order of the original sequence, not necessarily the order of results arrival). If return_exceptions is True, exceptions in the tasks are treated the same as successful results, and gathered in the result list; otherwise, the first raised exception will be immediately propagated to the returned future.

Cancellation: if the outer Future is cancelled, all children (that have not completed yet) are also cancelled. If any child is cancelled, this is treated as if it raised CancelledError – the outer Future is not cancelled in this case. (This is to prevent the cancellation of one child to cause other children to be cancelled.)

If return_exceptions is False, cancelling gather() after it has been marked done won’t cancel any submitted awaitables. For instance, gather can be marked done after propagating an exception to the caller, therefore, calling gather.cancel() after catching an exception (raised by one of the awaitables) from gather won’t cancel any other awaitables.