Quickstart

Quickstart

Installation

Install django-modern-rpc in your environment

pip install django-modern-rpc

poetry add django-modern-rpc

uv add django-modern-rpc

Basic setup

Create an RpcServer instance and register your first procedure

myproject/myapp/rpc.py
from modernrpc.server import RpcServer

server = RpcServer()

@server.register_procedure
def add(a: int, b: int) -> int:
    """Add two numbers and return the result.
    :param a: First number
    :param b: Second number
    :return: Sum of a and b
    """
    return a + b

Remote procedures are Python functions decorated with the server’s register_procedure decorator. Both server and procedure registration can be customized. See Procedures registration

Serve the procedures

To execute a remote procedure, clients will send a POST request to a single url in your project. Declare the route to this view in your project’s urls.py

myproject/myproject/urls.py
from django.urls import path
from myapp.rpc import server

urlpatterns = [
    # ... other url patterns
    path('rpc/', server.view),  # Synchronous view
]

The server’s view is already configured with CSRF exemption and POST-only restrictions.

Async Support

For Django projects using ASGI and async views, you can use the async version of the view:

myproject/myproject/urls.py (with async support)
from django.urls import path
from myapp.rpc import server

urlpatterns = [
    # ... other url patterns
    path('rpc/', server.async_view),  # Asynchronous view
]

The async view provides the same functionality as the synchronous view but can be used in an async context, allowing your Django application to handle other requests while waiting for RPC operations to complete.

Test the server

Start your project using python manage.py runserver and call your procedure using JSON-RPC or XML-RPC client, or directly with your favourite HTTP client

JSON-RPC example
~$ curl -X POST localhost:8000/rpc -H "Content-Type: application/json" -d '{"id": 1, "method": "system.listMethods", "jsonrpc": "2.0"}'
{"id": 1, "jsonrpc": "2.0", "result": ["add", "system.listMethods", "system.methodHelp", "system.methodSignature"]}

~$ curl -X POST localhost:8000/rpc -H "Content-Type: application/json" -d '{"id": 2, "method": "add", "params": [5, 9], "jsonrpc": "2.0"}'
{"id": 2, "jsonrpc": "2.0", "result": 14}
XML-RPC example
from xmlrpc.client import ServerProxy

with ServerProxy("http://localhost:8000/rpc") as proxy:
    proxy.system.listMethods()
    proxy.add(5, 9)

 # ['add', 'system.listMethods', 'system.methodHelp', 'system.methodSignature', 'system.multicall']
 # 14
Navigation