Skip to content

About

Create JSON-RPC 2.0 requests and parse responses in Python

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

127 stars

Watchers

3 watching

Forks

Repository files navigation

PyPI version CI Python 3.11 to 3.14 Downloads per month License: MIT

jsonrpcclient

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.

Features

  • 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.
  • Batches come back as a list, and match_responses pairs each response with its request by id (new in 5.0).
  • A malformed response raises InvalidResponse with a message saying what's wrong, such as missing 'id'. strict=True checks every JSON-RPC 2.0 rule (new in 5.0).
  • Supports Python 3.11 to 3.14.

Install

pip install jsonrpcclient

The changelog lists what changed in each release.

Quickstart

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.

Upgrading from 4.x?

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.

Upgrading from 3.x?

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.

Documentation

See also

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

Credits

Created by Beau Barker. Maintained by Synapse Research.

About

Create JSON-RPC 2.0 requests and parse responses in Python

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

127 stars

Watchers

3 watching

Forks

Releases

Used by

Contributors

Languages