Skip to main content

Async JSON-RPC 2.0 protocol + server powered by asyncio

Project description

Async JSON-RPC 2.0 protocol + asyncio server

Python package status security status pypi version

Lightweight JSON-RPC 2.0 protocol implementation and asynchronous server powered by asyncio. This library is a successor of json-rpc and written by the same team.

Features:

  • Full JSON-RPC 2.0 Implementation.
  • Async request manager that handles the protocol.
  • Vanilla Python, no dependencies.
  • API server setup in 1 min.
  • Same development team as json-rpc, largely compatible code.

Installing

$ pip install ajsonrpc

Quick Start

This package contains core JSON-RPC 2.0 primitives (request, response, etc.) and convenient backend-independent abstractions on top of them: dispatcher and request manager. These modules mirror implementation in the original json-rpc package with minor changes and improvements. Below is a summary of each module.

Core Module

Consists of JSON-RPC 2.0 primitives: request, batch request, response, batch response, error. It also defines base classes for custom errors and exceptions.

Development principles:

  • If python object is created or modified without exceptions, it contains valid data.
  • Private state <object>._body contains the single source of truth. It is accessible and modifiable via getters (properties) and setters that ensure validation.
  • body is always a dictionary with primitive keys and values (the only exception is response.result that could hold any value defined by the application).
  • Constructor, getters and setters operate with JSON-RPC defined types, e.g. response.error always has JSONRPC20Error type. Most of other types are strings and numbers.

Unlike json-rpc package, core module does not deal with serialization/de-serialization, this logic was moved to manager.

Dispatcher

Dispatcher is a dict-like object that maps method names to executables. One can think of it as an inproved dictionary, in fact it is inherited from MutableMapping. Some of the ways to add methods to dispatcher:

# init
d = Dispatcher({"sum": lambda a, b: a + b})

# set item
d["max"] = lambda a, b: max(a, b)

# function decorator
@d.add_function
def add(x, y):
    return x + y

# Add class or object
class Math:
    def sum(self, a, b):
        return a + b

    def diff(self, a, b):
        return a - b

d.add_class(Math)
d.add_object(Math())
d.add_dict({"min": lambda a, b: min(a, b)})

# rename function
d.add_function(add, name="my_add")

# prefix methos
d.add_class(Math, prefix="get_")

Manager

Manager generates a response for a request. It handles common routines: request parsing, exception handling and error generation, parallel request execution for batch requests, serialization/de-serialization. Manager is asynchronous and dackend agnostic, it exposes following common methods:

# Get a response object for a single request. Used by other methods.
async def get_response_for_request(
    self, request: JSONRPC20Request
    ) -> Optional[JSONRPC20Response]

# Get (batch) response for a string payload. Handles de-serialization and parse errors.
async def get_response_for_payload(
    self, payload: str
    ) -> Optional[Union[JSONRPC20Response, JSONRPC20BatchResponse]]

# Most high-level method, returns string json for a string payload.
async def get_payload_for_payload(self, payload: str) -> str

Vanilla Server (Demo)

This package comes with an asyncio Protocol-based minimalistic server script async-json-rpc-server. One could think of it as a bottle-py of API servers.

This was an experiment turned prototype: unlike json-rpc that requires some "shell" like Django or Flask to work, this package relies on asyncio and therefore could build on top of its TCP server. Indeed, JSON-RPC 2.0 is intentionally simple: server does not require views, has only one endpoint (routing is not required), only deals with json. Hence, vanilla code would be not only sufficient but likely faster than any framework.

This idea of self-sufficient server was extended further: what would be the minimum interface that allows to plug application code? What if zero integration is required? Likely, this was possible with runtime method introspection: async-json-rpc-server parses given file with methods and exposes all of them. Let's consider an example:

# examples/methods.py
import asyncio

def echo(s='pong'):
    return s

def mul2(a, b):
    return a * b

async def say_after(delay, what):
    await asyncio.sleep(delay)
    return what

To launch a server based on above methods, simply run:

$ async-json-rpc-server examples/methods.py --port=8888

(Ctrl+C stops the server).

Single request example:

$ curl -H 'Content-Type: application/json' \
    -d '{"jsonrpc": "2.0", "method": "echo", "id": 0}' \
    http://127.0.0.1:8888

{"jsonrpc": "2.0", "id": 0, "result": "pong"}

Batch request example: server-example-batch

Backends

Backend support is a syntactic sugar that wraps dispatcher and manager under one api class and provides convenient boilerplate, such as handler generation. Currently supported frameworks:

  • Tornado
  • Sanic
  • Quart

Project details


Download files

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

Source Distribution

ajsonrpc-1.2.0.tar.gz (22.1 kB view details)

Uploaded Source

Built Distribution

ajsonrpc-1.2.0-py3-none-any.whl (22.8 kB view details)

Uploaded Python 3

File details

Details for the file ajsonrpc-1.2.0.tar.gz.

File metadata

  • Download URL: ajsonrpc-1.2.0.tar.gz
  • Upload date:
  • Size: 22.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.6

File hashes

Hashes for ajsonrpc-1.2.0.tar.gz
Algorithm Hash digest
SHA256 791bac18f0bf0dee109194644f151cf8b7ff529c4b8d6239ac48104a3251a19f
MD5 d35f6c9b45616aaddcfd13538aa13311
BLAKE2b-256 da5c95a9b83195d37620028421e00d69d598aafaa181d3e55caec485468838e1

See more details on using hashes here.

File details

Details for the file ajsonrpc-1.2.0-py3-none-any.whl.

File metadata

  • Download URL: ajsonrpc-1.2.0-py3-none-any.whl
  • Upload date:
  • Size: 22.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.6

File hashes

Hashes for ajsonrpc-1.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 0fa2c1cf8e619d18ffee96043822032d6520eda65d3b712f9540a3a63e9cac25
MD5 edb0d99801691dc4086ef1b1068530fe
BLAKE2b-256 cf6f6abff7fe6813e6f94129a50c8c70bf70fb33ed2515b1037e703cef6d7a7e

See more details on using hashes here.

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