Futures

class pykka.Future

A handle to a value which is available now or in the future.

Typically returned by calls to actor methods or accesses to actor fields.

To get hold of the encapsulated value, call Future.get() or await the future.

get(*, timeout: float | None = None) → T

Get the value encapsulated by the future.

If the encapsulated value is an exception, it is raised instead of returned.

If timeout is None, as default, the method will block until it gets a reply, potentially forever. If timeout is an integer or float, the method will wait for a reply for timeout seconds, and then raise pykka.Timeout.

The encapsulated value can be retrieved multiple times. The future will only block the first time the value is accessed.

Parameters:

timeout (float or None) – seconds to wait before timeout

Raise:

pykka.Timeout if timeout is reached

Raise:

encapsulated value if it is an exception

Returns:

encapsulated value if it is not an exception

set(value: T | None = None) → None

Set the encapsulated value.

Parameters:

value (any object or None) – the encapsulated value or nothing

Raise:

an exception if set is called multiple times

set_exception(exc_info: OptExcInfo | None = None) → None

Set an exception as the encapsulated value.

You can pass an exc_info three-tuple, as returned by sys.exc_info(). If you don’t pass exc_info, sys.exc_info() will be called and the value returned by it used.

In other words, if you’re calling set_exception(), without any arguments, from an except block, the exception you’re currently handling will automatically be set on the future.

Parameters:

exc_info (three-tuple of (exc_class, exc_instance, traceback)) – the encapsulated exception

set_get_hook(func: Callable[[float | None], T]) → None

Set a function to be executed when get() is called.

The function will be called when get() is called, with the timeout value as the only argument. The function’s return value will be returned from get().

New in version 1.2.

Parameters:

func (function accepting a timeout value) – called to produce return value of get()

filter(func: Callable[[J], bool]) → Future[Iterable[J]]

Return a new future with only the items passing the predicate function.

If the future’s value is an iterable, filter() will return a new future whose value is another iterable with only the items from the first iterable for which func(item) is true. If the future’s value isn’t an iterable, a TypeError will be raised when get() is called.

Example:

>>> import pykka
>>> f = pykka.ThreadingFuture()
>>> g = f.filter(lambda x: x > 10)
>>> g
<pykka.future.ThreadingFuture at ...>
>>> f.set(range(5, 15))
>>> f.get()
[5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
>>> g.get()
[11, 12, 13, 14]

New in version 1.2.

join(*futures: Future[Any]) → Future[Iterable[Any]]

Return a new future with a list of the result of multiple futures.

One or more futures can be passed as arguments to join(). The new future returns a list with the results from all the joined futures.

Example:

>>> import pykka
>>> a = pykka.ThreadingFuture()
>>> b = pykka.ThreadingFuture()
>>> c = pykka.ThreadingFuture()
>>> f = a.join(b, c)
>>> a.set('def')
>>> b.set(123)
>>> c.set(False)
>>> f.get()
['def', 123, False]

New in version 1.2.

map(func: Callable[[T], M]) → Future[M]

Pass the result of the future through a function.

Example:

>>> import pykka
>>> f = pykka.ThreadingFuture()
>>> g = f.map(lambda x: x + 10)
>>> f.set(30)
>>> g.get()
40

>>> f = pykka.ThreadingFuture()
>>> g = f.map(lambda x: x['foo'])
>>> f.set({'foo': 'bar'}})
>>> g.get()
'bar'

New in version 1.2.

Changed in version 2.0: Previously, if the future’s result was an iterable (except a string), the function was applied to each item in the iterable. This behavior is unpredictable and makes regular use cases like extracting a single field from a dict difficult, thus the behavior has been simplified. Now, the entire result value is passed to the function.

reduce(func: Callable[[R, J], R], *args: R) → Future[R]

Reduce a future’s iterable result to a single value.

The function of two arguments is applied cumulatively to the items of the iterable, from left to right. The result of the first function call is used as the first argument to the second function call, and so on, until the end of the iterable. If the future’s value isn’t an iterable, a TypeError is raised.

reduce() accepts an optional second argument, which will be used as an initial value in the first function call. If the iterable is empty, the initial value is returned.

Example:

>>> import pykka
>>> f = pykka.ThreadingFuture()
>>> g = f.reduce(lambda x, y: x + y)
>>> f.set(['a', 'b', 'c'])
>>> g.get()
'abc'

>>> f = pykka.ThreadingFuture()
>>> g = f.reduce(lambda x, y: x + y)
>>> f.set([1, 2, 3])
>>> (1 + 2) + 3
6
>>> g.get()
6

>>> f = pykka.ThreadingFuture()
>>> g = f.reduce(lambda x, y: x + y, 5)
>>> f.set([1, 2, 3])
>>> ((5 + 1) + 2) + 3
11
>>> g.get()
11

>>> f = pykka.ThreadingFuture()
>>> g = f.reduce(lambda x, y: x + y, 5)
>>> f.set([])
>>> g.get()
5

New in version 1.2.

pykka.get_all(futures: Iterable[Future[T]], *, timeout: float | None = None) → Iterable[T]

Collect all values encapsulated in the list of futures.

If timeout is not None, the method will wait for a reply for timeout seconds, and then raise pykka.Timeout.

Parameters:

• futures (list of pykka.Future) – futures for the results to collect

• timeout (float or None) – seconds to wait before timeout

Raise:

pykka.Timeout if timeout is reached

Returns:

list of results