# 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[Any]], *, timeout: float | None = None) → Iterable[Any]

  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