szrpc 2026.7.0

Running a Server instance

Once a service is defined, it can easily be used to start a server which can listen for incoming connections from multiple clients as follows:

from szrpc.server import Server

if __name__ == '__main__':
   service = MyService()
   server = Server(service=service, ports=(9990, 9991))
   server.run()

This says that our server will be available at the TCP address ‘tcp://localhost:9990’ for clients, and at the address ‘tcp://localhost:9991’ for workers. For simple cases, you don’t need to worry about workers but by default, one worker created behind the scenes to provide the service, thus it is mandatory to specify both ports. Additionally, you can change your mind and run additional workers at any point in the future on any host after the server is started.

To start the server with more than one worker on the local host, modify the instances keyword argument as follows:

server = Server(service_factory=factory, ports=(9990, 9991), instances=1)

It is possible to start the server with instances = 0 however, it will obviously not be able to handle any requests until at least one worker is started.

Starting External Workers

Starting external workers is very similar to starting Servers.

from szrpc import log
from szrpc.server import Server, Service, WorkerManager

from test_server import MyService

if __name__ == '__main__':

    service = MyService()
    log.log_to_console()
    server = WorkerManager(
        service=service, backend="tcp://localhost:9991",
        instances=2
    )
    server.run()

In the above example, we are staring two instances of workers on this host which are connected to the backend address of the main server.

Creating Clients

Clients are just as easy, if not easier to create. Here is a test client for the above service.

import time
from szrpc import log
from szrpc.client import Client

# Define response handlers
def on_done(res, data):
    print(f"Done: {res} {data!r}")

def on_err(res, data):
    print(f"Failed: {res} : {data!r}")

def on_update(res, data):
    print(f"Update: {res} {data!r}")

if __name__ == '__main__':
    log.log_to_console()
    client = Client('tcp://localhost:9990')

    # wait for client to be ready before sending commands
    while not client.is_ready():
        time.sleep(.001)

    res = client.hello_world(name='Joe')
    res.connect('done', on_done)
    res.connect('update', on_update)
    res.connect('failed', on_err)

Here we have defined a few handler functions to get called once the replies are received. A few things are noteworthy in the above client code:

• The client automatically figures out from the server, which methods to generate. For this reason, you will get “InvalidAttribute” errors if the initial handshake has not completed before method calls are made. For most production situations, this is not a problem but in the example above, we wait until the client.is_ready() returns True before proceeding.

• The method names at the client end do not nave the remote__ prefix. This means, overriding remote methods in the client will clobber the name.

• Only key-worded arguments are allowed for remote methods.

• Results are delivered asynchronously. To write synchronous code, you can call the res.wait() method on Result objects.

There are three signal types corresponding to the three types of replies a server can send:

‘done’

the server has completed processing the request, no further replies should be expected for this request

‘update’

partial data is has been received for the request. More replies should be expected.

‘failed’

The request has failed. No more replies should be expected.

Handler functions take two arguments, the first is always the result object, which is an instance of szrpc.result.Result, and the second is the decoded message from the server.

Result Classes

All results are instances of szrpc.result.Result or sub-classes thereof. The types of result objects produced can be changed to allow better integration with various frameworks. Presently, alternatives are available Gtk, Qt as well as a pure Python-based class. The pure Python result class is the default but it can easily be changed as follows.

from szrpc.result.gresult import GResult
import szrpc.client

szrpc.client.use(GResult)

my_client = szrpc.client.Client('tcp://localhost:9990')

All subsequent result objects will be proper GObjects usable with the Gtk Main loop.