Main Code

PyActor: Python Actor library

Context

See source

class pyactor.context.Host(url)

Host must be created using the function create_host(). Do not create a Host directly.

Host is a container for actors. It manages the spawn and elimination of actors and their communication through channels. Also configures the remote points where the actors will be able to receive and send queries remotely. Additionally, controls the correct management of its actors’ threads and intervals.

The host is managed as an actor itself so you interact with it through its Proxy. This allows you to pass it to another host to spawn remotely.

Parameters:url (str.) – URL that identifies the host and where to find it.
attach_interval(interval_id, interval_event)

Registers an interval event to the host.

detach_interval(interval_id)

Deletes an interval event from the host registry.

dumps(param)

Checks the parameters generating new proxy instances to avoid query concurrences from shared proxies and creating proxies for actors from another host.

has_actor(aid)

Checks if the given id is used in the host by some actor.

Parameters:aid (str.) – identifier of the actor to check.
Returns:True if the id is used within the host.
loads(param)

Checks the return parameters generating new proxy instances to avoid query concurrences from shared proxies and creating proxies for actors from another host.

lookup(aid)

Gets a new proxy that references to the actor of this host (only actors in this host) identified by the given ID.

This method can be called remotely synchronously.

Parameters:aid (str.) – identifier of the actor you want.
Returns:Proxy to the actor required.
Raises:NotFoundError if the actor does not exist.
Raises:HostDownError if the host is down.
lookup_url(url, klass, module=None)

Gets a proxy reference to the actor indicated by the URL in the parameters. It can be a local reference or a remote direction to another host.

This method can be called remotely synchronously.

Parameters:
  • url (srt.) – address that identifies an actor.
  • klass (class) – the class of the actor.
  • module (srt.) – if the actor class is not in the calling module, you need to specify the module where it is here. Also, the klass parameter change to be a string.
Returns:

Proxy of the actor requested.
Raises:

NotFoundError, if the URL specified do not correspond to any actor in the host.
Raises:

HostDownError if the host is down.
Raises:

HostError if there is an error looking for the actor in another server.
new_parallel(a_function, *params)

Register a new thread executing a parallel method.

spawn(aid, klass, *param, **kparam)

This method creates an actor attached to this host. It will be an instance of the class klass and it will be assigned an ID that identifies it among the host.

This method can be called remotely synchronously.

Parameters:
  • aid (str.) – identifier for the spawning actor. Unique within the host.
  • klass (class) – class type of the spawning actor. If you are spawning remotely and the class is not in the server module, you must specify here the path to that class in the form ‘module.py/Class’ so the server can import the class and create the instance.
  • param – arguments for the init function of the spawning actor class.
  • kparam – arguments for the init function of the spawning actor class.
Returns:

Proxy to the spawned actor.
Raises:

AlreadyExistsError, if the ID specified is already in use.
Raises:

HostDownError if the host is not initiated.
stop_actor(aid)

This method removes one actor from the Host, stopping it and deleting all its references.

Parameters:aid (str.) – identifier of the actor you want to stop.
pyactor.context.create_host(url='local://local:6666/host')

This is the main function to create a new Host to which you can spawn actors. It will be set by default at local address if no parameter url is given. This function should be called once for execution or after calling shutdown() to the previous host.

However, it is possible to create locally more than one host and simulate a remote communication between them if they are of some remote type (http or amqp), but the first one created will be the main host, which is the one hosting the queries from the main function. Of course, every host must be initialized with a different URL(port). Although that, more than one host should not be required for any real project.

Parameters:url (str.) – URL where to start and bind the host.
Returns:Proxy to the new host created.
Raises:Exception if there is a host already created with that URL.
pyactor.context.interval(host, time, actor, method, *args, **kwargs)

Creates an Event attached to the host for management that will execute the method of the actor every time seconds.

See example in Sample 11 - Intervals

Return type:
Parameters:
  • host (Proxy) – host that will manage the interval, commonly the host of the actor.
  • time (float) – seconds for the intervals.
  • actor (Proxy) – actor to which make the call every time seconds.
  • method (Str.) – method of the actor to be called.
  • args (list) – arguments for method.
Returns:

Event instance of the interval.
pyactor.context.later(timeout, actor, method, *args, **kwargs)

Sets a timer that will call the method of the actor past timeout seconds.

See example in Sample 11 - Intervals

Parameters:
  • timeout (int) – seconds until the method is called.
  • actor (Proxy) – actor to which make the call after time seconds.
  • method (Str.) – method of the actor to be called.
  • args (list) – arguments for method.
Returns:

manager of the later (Timer in thread, Greenlet in green_thread)
pyactor.context.serve_forever()

This allows the host (main host) to keep alive indefinitely so its actors can receive queries at any time. The main thread stays blocked forever. To kill the execution, press Ctrl+C.

See usage example in Sample 6 - self.id, proxy and host.

pyactor.context.set_context(module_name='thread')

This function initializes the execution context deciding which type of threads are being used: classic python threads or green threads, provided by Gevent.

This should be called first of all in every execution, otherwise, the library would not work.

The default module is ‘thread’.

Parameters:module_name (str.) – Name of the module you want to use (‘thread’ or ‘green_thread’).
pyactor.context.set_rabbit_credentials(user, password)

If you use a RabbitMQ server and want to make remote queries, you might need to specify new credentials for connection.

By default, PyActor uses the guest RabbitMQ user.

Parameters:
  • user (str.) – Name for the RabbitMQ user.
  • password (str.) – Password for the RabbitMQ user.
pyactor.context.shutdown(url=None)

Stops the Host passed by parameter or all of them if none is specified, stopping at the same time all its actors. Should be called at the end of its usage, to finish correctly all the connections and threads.

pyactor.context.sleep(seconds)

Facade for the sleep function. Do not use time.sleep if you are running green threads.

Proxy

See source

class pyactor.proxy.AskRefWrapper(channel, method, actor_url)

Wrapper for Ask queries that have a proxy in parameters or returns.

class pyactor.proxy.AskWrapper(channel, method, actor_url)

Wrapper for Ask type queries to the proxy. Calling it blocks the execution until the result is returned or timeout is reached. You can add the tagged parameter “timeout” to change the time limit to wait. Default timeout is set to 10s. It is also possible to specify “future=True” to get an instant response with a Future object with which you can manage the result.

Parameters:
  • channel (Channel) – communication way for the query.
  • method (str.) – name of the method this query is gonna invoke.
  • actor_url (str.) – URL address where the actor is set.
class pyactor.proxy.Proxy(actor)

Proxy is the class that supports to create a remote reference to an actor and invoke its methods. All the references to actors will be proxies, even the host. To get a proxy to an Actor, you should use one of the host functions that provide one, like spawn() or lookup_url().

Parameters:actor (Actor) – the actor the proxy will manage.
get_id()
Returns:the id of the actor that this proxy holds.
Raises:Exception if the proxy holds a remote actor. Use URL.
get_url()
Returns:the URL of the actor that this proxy holds.
class pyactor.proxy.TellRefWrapper(channel, method, actor_url)

Wrapper for Tell queries that have a proxy in parameters.

class pyactor.proxy.TellWrapper(channel, method, actor_url)

Wrapper for Tell type queries to the proxy. Creates the request and sends it through the channel.

Parameters:
  • channel (Channel) – communication way for the query.
  • method (str.) – name of the method this query is going to invoke.
  • actor_url (str.) – URL address where the actor is set.

Util

Defined constants:
FROM, TO, TYPE, METHOD, PARAMS, FUTURE, ASK, TELL, SRC, CHANNEL, CALLBACK, ASK_RESPONSE, FUTURE_RESPONSE, RESULT, RPC_ID

Remote Solutions

class pyactor.rpcserver.RequestHandler(request, client_address, server)
class pyactor.rpcserver.Sink(url)

Facade for XMLRPC proxies.

class pyactor.rpcserver.Source(addr)

Facade for simple remote communication using XMLRPCServer.

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

class pyactor.rabbitserver.Sink(url)

Facade for RabbitMQ concrete connexions to remote actors. This manages the publish to queues.

class pyactor.rabbitserver.Source(addr)

Facade for simple remote communication using RabbitMQ. This connection uses by default the guest RabbitMQ user. To change credentials see setRabbitCredentials().

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

Exceptions

PyActor exceptions.

exception pyactor.exceptions.AlreadyExistsError(value='Not specified')

Actor ID repeated.

exception pyactor.exceptions.FutureError(value='Not specified')

Some problem with the Future.

exception pyactor.exceptions.HostDownError

The Host is down.

exception pyactor.exceptions.HostError(value='Not specified')

Some problem with the Host.

exception pyactor.exceptions.IntervalError(value='Not specified')

Some problem with the interval.

exception pyactor.exceptions.NotFoundError(value='Not specified')

Actor not found in Host.

exception pyactor.exceptions.PyActorTimeoutError(method='Not specified')

Wait time expired.