Proxies

class pykka.ActorProxy(*, actor_ref: ActorRef[A], attr_path: AttrPath | None = None)

An ActorProxy wraps an ActorRef instance.

The proxy allows the referenced actor to be used through regular method calls and field access.

You can create an ActorProxy from any ActorRef:

actor_ref = MyActor.start()
actor_proxy = ActorProxy(actor_ref)

You can also get an ActorProxy by using proxy():

actor_proxy = MyActor.start().proxy()

Attributes and method calls

When reading an attribute or getting a return value from a method, you get a Future object back. To get the enclosed value from the future, you must call get() on the returned future:

print(actor_proxy.string_attribute.get())
print(actor_proxy.count().get() + 1)

If you call a method just for it’s side effects and do not care about the return value, you do not need to accept the returned future or call get() on the future. Simply call the method, and it will be executed concurrently with your own code:

actor_proxy.method_with_side_effect()

If you want to block your own code from continuing while the other method is processing, you can use get() to block until it completes:

actor_proxy.method_with_side_effect().get()

You can also use the await keyword to block until the method completes:

await actor_proxy.method_with_side_effect()

If you access a proxied method as an attribute, without calling it, you get an CallableProxy.

Proxy to itself

An actor can use a proxy to itself to schedule work for itself. The scheduled work will only be done after the current message and all messages already in the inbox are processed.

For example, if an actor can split a time consuming task into multiple parts, and after completing each part can ask itself to start on the next part using proxied calls or messages to itself, it can react faster to other incoming messages as they will be interleaved with the parts of the time consuming task. This is especially useful for being able to stop the actor in the middle of a time consuming task.

To create a proxy to yourself, use the actor’s actor_ref attribute:

proxy_to_myself_in_the_future = self.actor_ref.proxy()

If you create a proxy in your actor’s constructor or on_start method, you can create a nice API for deferring work to yourself in the future:

def __init__(self):
    ...
    self._in_future = self.actor_ref.proxy()
    ...

def do_work(self):
    ...
    self._in_future.do_more_work()
    ...

def do_more_work(self):
    ...

To avoid infinite loops during proxy introspection, proxies to self should be kept as private instance attributes by prefixing the attribute name with _.

Examples

An example of ActorProxy usage:

#!/usr/bin/env python3

import pykka


class Adder(pykka.ThreadingActor):
    def add_one(self, i):
        print(f"{self} is increasing {i}")
        return i + 1


class Bookkeeper(pykka.ThreadingActor):
    def __init__(self, adder):
        super().__init__()
        self.adder = adder

    def count_to(self, target):
        i = 0
        while i < target:
            i = self.adder.add_one(i).get()
            print(f"{self} got {i} back")


if __name__ == "__main__":
    adder = Adder.start().proxy()
    bookkeeper = Bookkeeper.start(adder).proxy()
    bookkeeper.count_to(10).get()
    pykka.ActorRegistry.stop_all()

Parameters:

actor_ref (pykka.ActorRef) – reference to the actor to proxy

Raise:

pykka.ActorDeadError if actor is not available

actor_ref: ActorRef[A]

The actor’s pykka.ActorRef instance.

class pykka.CallableProxy(*, actor_ref: ActorRef[A], attr_path: AttrPath)

Proxy to a single method.

CallableProxy instances are returned when accessing methods on a ActorProxy without calling them.

Example:

proxy = AnActor.start().proxy()

# Ask semantics returns a future. See `__call__()` docs.
future = proxy.do_work()

# Tell semantics are fire and forget. See `defer()` docs.
proxy.do_work.defer()

__call__(*args: Any, **kwargs: Any) → Future[Any]

Call with ask() semantics.

Returns a future which will yield the called method’s return value.

If the call raises an exception is set on the future, and will be reraised by get(). If the future is left unused, the exception will not be reraised. Either way, the exception will also be logged. See Logging for details.

defer(*args: Any, **kwargs: Any) → None

Call with tell() semantics.

Does not create or return a future.

If the call raises an exception, there is no future to set the exception on. Thus, the actor’s on_failure() hook is called instead.

New in version 2.0.

pykka.traversable(obj: T) → T

Mark an actor attribute as traversable.

The traversable marker makes the actor attribute’s own methods and attributes available to users of the actor through an ActorProxy.

Used as a function to mark a single attribute:

class AnActor(pykka.ThreadingActor):
    playback = pykka.traversable(Playback())

class Playback(object):
    def play(self):
        return True

This function can also be used as a class decorator, making all instances of the class traversable:

class AnActor(pykka.ThreadingActor):
    playback = Playback()

@pykka.traversable
class Playback(object):
    def play(self):
        return True

The third alternative, and the only way in Pykka < 2.0, is to manually mark a class as traversable by setting the pykka_traversable attribute to True:

class AnActor(pykka.ThreadingActor):
    playback = Playback()

class Playback(object):
    pykka_traversable = True

    def play(self):
        return True

When the attribute is marked as traversable, its methods can be executed in the context of the actor through an actor proxy:

proxy = AnActor.start().proxy()
assert proxy.playback.play().get() is True

New in version 2.0.