Skip to main content

Type safe JSON RPC client with automatic (de)serialization. Best paired with instant_api.

Project description


Build Status Coverage Status Supports Python versions 3.7+

A type-safe JSON-RPC client with automatic (de)serialization.

pip install instant-client

For communication over HTTP (like in the example below):

pip install 'instant-client[requests]'

instant_client can be used with any server implementing JSON-RPC, but it's best paired with instant_api. For example, suppose the API server is set up like this:

from dataclasses import dataclass
from flask import Flask
from instant_api import InstantAPI

app = Flask(__name__)

class Point:
    x: int
    y: int

class Methods:
    def translate(self, p: Point, dx: int, dy: int) -> Point:
        return Point(p.x + dx, p.y + dy)

    def scale(self, p: Point, factor: int) -> Point:
        return Point(p.x * factor, p.y * factor)

if __name__ == '__main__':

Then using the client is as simple as:

from server import Methods, Point  # the classes we defined above
from instant_client import InstantClient

# The type hint is a lie, but your linter/IDE doesn't know that!
methods: Methods = InstantClient("", Methods()).methods

assert methods.scale(Point(1, 2), factor=3) == Point(3, 6)

That looks a lot like it just called Methods.scale() directly, which is the point (no pun intended), but under the hood it did in fact send an HTTP request to the server! The same code written more manually looks like this:

import requests

response =
        'id': 0, 
        'jsonrpc': '2.0', 
        'method': 'scale', 
        'params': {
            'p': {'x': 1, 'y': 2}, 
            'factor': 3,

assert response.json()['result'] == {'x': 3, 'y': 6}

In general, the InstantClient constructor has two required parameters:

  1. A client from the jsonrpcclient library for your desired transport. For example:

    from jsonrpcclient.clients.zeromq_client import ZeroMQClient
    from instant_client import InstantClient
    client = InstantClient(ZeroMQClient("tcp://localhost:5000"), Methods())

    As a convenience, you can also just pass a string representing a URL, which will be used to construct an HTTPClient.

  2. An object defining your methods. The method body can be empty, InstantClient just uses the signature and type hints to serialize the arguments and deserialize the result with the help of datafunctions.

The methods attribute of the client is a simple proxy so that this:

client.methods.scale(Point(1, 2), factor=3)

is equivalent to:

client.request("scale", Point(1, 2), factor=3)

which in turn looks up the signature of the original method.

Your IDE/linter/type-checker should think that client.methods is the object you passed at the beginning, so you can get all the usual warnings and autocompletions. Adding your own type hint can help but shouldn't be necessary.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

instant_client-0.0.1-py3-none-any.whl (5.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page