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.typedmarker. 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.
- Batches come back as a list, and
match_responsespairs each response with its request by id (new in 5.0). - A malformed response raises
InvalidResponsewith a message saying what's wrong, such asmissing 'id'.strict=Truechecks every JSON-RPC 2.0 rule (new in 5.0). - Supports Python 3.11 to 3.14.
pip install jsonrpcclientThe changelog lists what changed in each release.
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.
5.0 is in release candidates: pip install --pre jsonrpcclient gets the
latest one, and pip install jsonrpcclient keeps installing 4.x until 5.0.0.
Most 4.x code runs unchanged. The
migration guide lists every change, and
issue 252 tracks
the release. Upgrade to 4.2.0 first: it warns about the calls 5.0 handles
differently.
Since 4.x the API is completely different: request builds a request and no
longer sends it. A 3.x call such as request("http://example.com", "get")
raises TypeError in 5.0. On 4.x it runs but sends nothing. 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, which says how long each release line gets fixes
- 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.
