Simple RPC Library (SRPC)

SRPC is an experimental RPC framework that uses Python as its Interface Definition Language. Define a service contract using Python, implement the service, generate server and client stubs, and invoke remote procedures.

Features

• Python as IDL
• Automatic Stub generation
• TLS support

Warning

Currently, the framework only supports Python language.

Table of Contents

• Simple RPC Library (SRPC)
  • Features
  • Table of Contents
  • Installation
  • Quick Start
    • Server side directory structure
    • Define service contract
    • Implement service
    • Generate Server Stub
    • Implement the Server
    • Run the Server
    • Client side directory Structure
    • Generate Client Stub
    • Implement the Client
    • Run the Client
    • Naming conventions
  • Important Technical Details
  • License

Installation

SRPC is currently distributed through GitHub Releases rather than PyPI.

Download and extract the latest release from GitHub. From the extracted directory, run: python -m pip install .

Quick Start

Let’s implement a simple service that supports the four basic arithmetic operators: Addition, Subtraction, Multiplication and Division

Server side directory structure

├─calculator-service/
|   ├─ calc/
|   │  ├─ __init__.py
|   │  ├─ calc_interface.py
|   │  ├─ calc.py
|   ├─ srpc_calc_server_stub.py
|   ├─ server.py
...

With:

• calculator-service/ is the root directory of the service.

Define service contract

# calc_interface.py
from abc import ABC, abstractmethod
class CalcInterface(ABC):
    @abstractmethod
    def add(self, a: int, b: int) -> int:
        pass

    @abstractmethod
    def sub(self, a: int, b: int) -> int:
        pass

    @abstractmethod
    def mult(self, a: int, b: int) -> int:
        pass

    @abstractmethod
    def div(self, a: int, b: int) -> int:
        pass

Implement service

# calc.py
from .calc_interface import CalcInterface

class Calc(CalcInterface):
    def add(self, a: int, b: int) -> int:
        return a + b

    def sub(self, a: int, b: int) -> int:
        return a - b

    def mult(self, a: int, b: int) -> int:
        return a * b

    def div(self, a: int, b: int) -> int:
        return a / b

Generate Server Stub

The tool to generate the stubs is srpc_stub_gen. Use it as below:

srpc_stub_gen <interface-path> <target> <language>

With:

• the path of the service contract
• specify the target Stub(CLIENT/SERVER)
• Specify the language in which the stub should be generated.

Inside calculator-service/ directory run:

python -m srpcLib.tools.srpc_stub_gen calc/calc_interface.py SERVER PYTHON

It will generate the file srpc_calc_server_stub.py

Implement the Server

# server.py
from srpc_calc_server_stub import SrpcCalcServerStub
calcServerStub = SrpcCalcServerStub(tls_config=None, host="127.0.0.1")
calcServerStub.start()

With: tls_config=None means do not use TLS host="127.0.0.1" means the server will use the localhost as IP address

Run the Server

Inside calculator-service/ directory run:

python server.py

You should see something like this:

2026-08-19 22:27:24,649 [INFO] srpc_base_server_stub: Procedures calls on [tcp-192.168.0.117:5000].
2026-08-19 22:27:24,649 [INFO] srpc_base_server_stub: press Ctrl+C to stop.

Note

By standard, SRPC uses port 5000.

Client side directory Structure

├─ calculator-client/
|    ├─ calc/
|    │  ├─ __init__.py
|    │  ├─ calc_interface.py
|    ├─ srpc_calc_client_stub.py
|    ├─ client.py
...

Note

The client and server must use the same service contract. In this example, the contract is copied into both projects.

Generate Client Stub

Inside the calculator-client/ directory run:

python -m srpcLib.tools.srpc_stub_gen calc/calc_interface.py CLIENT PYTHON

It will generate the file srpc_calc_client_stub.py

Implement the Client

# client.py
from srpc_calc_client_stub import SrpcCalcClientStub

SERVER_HOST = "127.0.0.1"
calcStub = SrpcCalcClientStub(SERVER_HOST)

a = 4
b = 2

print(f"{calcStub.add(a, b)}")
print(f"{calcStub.mult(a, b)}")
print(f"{calcStub.sub(a, b)}")
print(f"{calcStub.div(a, b)}")

Run the Client

Inside the calculator-client/ directory run:

python client.py

Naming conventions

Component	Required pattern	Example
Service package	lowercase service name	calc/
Service contract/interface	<service>_interface.py	calc_interface.py
Implementation script	<service>.py	calc.py
Interface class	<Service>Interface	CalcInterface
Implementation class	<Service>	Calc

Warning

SRPC currently relies on naming conventions for automatic discovery and stub generation.

Important Technical Details

Under the hood, SRPC uses:

• A framed application protocol with fixed-size header
• MessagePack-based serialization(SRPC exchanges messages as byte arrays)
• Generic error communication based on error codes
• One connection and one handler thread are used for each request.

Warning

No performance tests or rigorous security analysis have been conducted. Do not use this in production environments.

Note

Technical documentation and release notes for version v4.x.x in progress...

License