Services

Introduction to Services

Services expose a set of capabilities to the other party. Services need not be symmetric between the two sides; each side may expose a different service. Services are accessible through the .root attribute of connection objects. For example:

c = rpyc.connect("hostname", 12345)
c.root.func1(1,2,3)
c.root.func2(4,5,6)

Built-in Services

VoidService

The VoidService is the simplest and safest of all services: it exposes nothing. The other party can't access anything on a server that exposes Void. For security reasons, it is the default service for the connection factories (connect() and tls_connect()). If you want the client to expose a different service, you'll have to explicitly pass the service parameter to the factories.

SlaveService

The SlaveService is the service that implements classic mode. This service exposes import, eval and exec, which practically make the server a slave of the client. If you use the classic factories (classic.connect and classic.tls_connect), they set the client side service to Slave as well, and also set some shortcuts for backwards compatibility.

Note: see the security notes concerning classic mode.

Custom Services

Writing custom services is very easy, just use the following boilerplate:

import rpyc
 
class MyService(rpyc.Service):
    def exposed_func1(self, ...):
        ...
    def exposed_func2(self, ...):
        ...
    ...

Where func1, func2, … will be the functions/methods you expose. By default, in order to expose attributes to the other party, their name must begin with exposed_.

If you require initialization or finalization of services, you can override on_connect and on_disconnect:

class MyService(rpyc.Service):
    def on_connect(self):
        # code to initialize the service, i.e., change the connection 
        # config, register client, etc.
 
    def on_disconnect(self):
        # finalization code goes here. note that when this method is
        # invoked, the connection is already disconnected.

Naming

• Naming convention: append the Service suffix to your service name, i.e., the My service class should be called MyService.
• By default, the name of your service will be the name of the class without the Service suffix, e.g., My.
• If you want to set multiple or custom names (aliases) for your service class, use the ALIASES class attribute:

class MyService(rpyc.Service):
    ALIASES = ["hello", "world", "foo", "bar"]
    ...

• The service name is used to identify your service in the registry server. Make sure you choose unique names, or confusion is bound to happen. Service names are not case-sensitive.
• If your service has several versions, just append the version to the name. The default version should create an alias to the unversioned name, e.g.

class Chat1Service(rpyc.Service):
    ...
class Chat2Service(rpyc.Service):
    ...
class Chat3Service(rpyc.Service):
    ALIASES = ["Chat3", "Chat"]

That way, when a client seeks the chat service, it will get the latest version. However, if the client wants explicitly version 1, it can seek chat1.