Create JSON-RPC 2.0 requests and parse responses in Python

Documentation | API reference | Examples | Changelog | Migration

jsonrpcclient builds JSON-RPC 2.0 requests and parses the responses. It doesn't send anything, so it works with any transport: HTTP, websockets, ZeroMQ, or something of your own.

• Builds requests for any transport. You send them with the library you already use.
• No dependencies outside the standard library.
• Typed, with a py.typed marker. The package passes mypy and pyright in strict mode.
• Requests, notifications and batches, with ids that count up or are hex, random or UUID strings.
• Id generators are safe to share between threads, and CI runs the tests on free-threaded Python 3.14t.
• A malformed response raises InvalidResponse with a message saying what's wrong, such as missing 'id' (new in 4.1.0).
• Supports Python 3.8 to 3.14.

pip install jsonrpcclient

The latest release on PyPI is 4.0.3. This README and the documentation describe 4.1.0, which isn't released yet. The changelog lists the differences.

This sends ping to a JSON-RPC server at http://localhost:8000/, using requests for the HTTP part:

import requests

from jsonrpcclient import Error, Ok, parse, request

url = "http://localhost:8000/"
response = requests.post(url, json=request("ping"), timeout=10)
response.raise_for_status()
parsed = parse(response.json())
if isinstance(parsed, Ok):
    print(parsed.result)
elif isinstance(parsed, Error):
    print("Error:", parsed.message)

Output:

pong

For JSON strings, use request_json and parse_json. The examples show the same thing with urllib, httpx, aiohttp, websockets and ZeroMQ.

The 4.x API is completely different: request builds a request and no longer sends it. A 3.x call such as request("http://example.com", "get") still runs but sends nothing, so read the migration guide before upgrading.

• User guide: requests, notifications, batches, ids, responses and error handling
• API reference
• Transport examples
• FAQ
• Contributing and security policy
• License: MIT

jsonrpcserver processes incoming JSON-RPC requests in Python. It's the server-side companion to this library.

Created by Beau Barker. Maintained by Synapse Research.