Futures
- class pykka.Future[source]
A
Future
is a handle to a value which is available or will be available 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()
orawait
the future.- get(timeout=None)[source]
Get the value encapsulated by the future.
If the encapsulated value is an exception, it is raised instead of returned.
If
timeout
isNone
, as default, the method will block until it gets a reply, potentially forever. Iftimeout
is an integer or float, the method will wait for a reply fortimeout
seconds, and then raisepykka.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=None)[source]
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=None)[source]
Set an exception as the encapsulated value.
You can pass an
exc_info
three-tuple, as returned bysys.exc_info()
. If you don’t passexc_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)[source]
Set a function to be executed when
get()
is called.The function will be called when
get()
is called, with thetimeout
value as the only argument. The function’s return value will be returned fromget()
.New in version 1.2.
- Parameters
func (function accepting a timeout value) – called to produce return value of
get()
- filter(func)[source]
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 whichfunc(item)
is true. If the future’s value isn’t an iterable, aTypeError
will be raised whenget()
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)[source]
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)[source]
Return a new future with the result of the future passed 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[, initial])[source]
Return a new future with the result of reducing the future’s iterable into 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, timeout=None)[source]
Collect all values encapsulated in the list of futures.
If
timeout
is notNone
, the method will wait for a reply fortimeout
seconds, and then raisepykka.Timeout
.- Parameters
futures (list of
pykka.Future
) – futures for the results to collecttimeout (float or
None
) – seconds to wait before timeout
- Raise
pykka.Timeout
if timeout is reached- Returns
list of results