Core API

Protocol

The Connection class implements the RPyC protocol itself.

The constructor of Connection takes the following parameters:

• service - the service class which this side of the connection exposes. The service class is instantiated and initialized in the constructor.
• channel - the channel object on which this connection operates
• config - the config dict (by default {}, which means the default config is used)

API:

• close() - closes the connections and releases all resources
• closed - a property indicating whether this protocol object is closed
• fileno() - returns the file descriptor of the underlying channel
• ping(data, timeout) - checks if the other party is alive
• serve() - serves a single request (blocking)
• serve_all() - serve all requests until the connection closes (blocking)
• poll(timeout = 0) - serves a single request, if one received within the given timeout (nonblocking)
• poll_all(timeout = 0) - serves all requests within the given timeout (nonblocking)
• sync_request(handler, *args) - performs a synchronous request to 'handler' with 'args'
• async_request(handler, *args, timeout = None) - performs an asynchronous request to 'handler' with 'args', with an optional timeout limit. Returns an AsyncResult.
• root - a property that fetches the other party's service object (referred to as "root")

Attribute Access

By default, the access to remote object attributes is mandated by the parameters of the config dict, but objects may customize access to their attributes by defining any of these RPyC special-methods:

• _rpyc_getattr(self, name) - gets an attribute of this object, exposed to the other party, or raises AttributeError (equivalent of __getattr__)
• _rpyc_setattr(self, name, value) - sets an attribute of this object, exposed to the other party, or raises AttributeError (equivalent of __setattr__)
• _rpyc_delattr(self, name) - deletes an attribute of this object, exposed to the other party, or raises AttributeError (equivalent of __delattr__)

class Foo(object):
    def _rpyc_getattr(self, name):
        if name.startswith("safe_"):
            return getattr(self, name)
        else:
            raise AttributeError("only safe_xxx attributes can be accessed")

    def safe_get_the_answer(self):
        return 42
    def unsafe_get_the_question(self):
        return "what is 6 times 7"

SlaveService

When using classic-mode RPyC (i.e, the SlaveService), some additional shortcuts are added to the protocol objects: proto.xxx is a shortcut to proto.root.xxx, and can be accessed both ways.

API:

• modules - property exposing the modules namespace of the other party. Top-level modules, like sys, os, et al, can be accessed with a shortcut notation as modules.sys. Deeper-level modules, like xml.dom.minidom, can only be accessed with the bracket notation as modules["foo.bar.spam.eggs"].
• eval(code) - evaluates the given code string on the other party
• execute(code) - executes the given code string on the other party
• namespace - property returning the remote dict used as the execution namespace for eval() and execute()

Configuration

The protocol object can be configured using the config dict, with the following parameters:

Name	Type	Default	Description
Attributes
allow_safe_attrs	bool	True	whether to allow attribute access to safe attributes
safe_attrs	set	…	a set of attribute names considered safe (i.e., __iter__, __mul__, etc.)
allow_exposed_attrs	bool	True	whether to allow access to attributes beginning with a well-defined prefix
exposed_prefix	str	"exposed_"	the prefix of exposed attributes
allow_public_attrs	bool	False	whether to allow access to public attributes (name does not begin with '_')
allow_all_attrs	bool	False	whether to allow access to all attributes (including special and private)
Exceptions
include_local_traceback	bool	True	whether to include the local traceback text in the vinegared exception info
instantiate_custom_exceptions	bool	False	whether to allow instantiation of custom exceptions classes (non-builtin exceptions)
import_custom_exceptions	bool	False	whether to allow importing custom modules
instantiate_oldstyle_exceptions	bool	False	whether to allow instantiation of old-style classes (not deriving from Exception)
propagate_SystemExit	bool	False	whether to propagate the SystemExit exception from one party to the other, or whether it should be dealt with locally (terminating the local party).
Misc
debug	bool	False	whether to print debug logs (used to debug the protocol)
allow_pickle	bool	False	whether to allow object pickling

Service

Services expose restricted functionality to clients. The Server class has the following API:

• ALIASES - (class attribute) a list of names that are used as aliases to this service. The first name is used as the primary name. If empty, the name of the service class is used (minus the 'Service' suffix)
• on_connect() - an overridable method called when an RPyC connection is made; may be used to initialize the service object or perform additional configuration on the connection
• on_disconnect() - an overridable method called when the RPyC connection is closed; must not perform any IO on the connection, since the underlying IO layers have already closed.
• get_service_name() - returns the primary name of the services (the first alias)
• get_service_aliases() - returns all the aliases of the service

When implementing custom services, simply derive from the base Service class and define methods or any other attributes that begin with the string "exposed_". These attributes will be accessible (via getattr) to the client. All other attributes will be restricted.