Registry / serialization / jsonrpcclient

jsonrpcclient

JSON →
library4.0.3pypypi✓ verified 85d ago

jsonrpcclient is a Python library for generating JSON-RPC requests and parsing responses according to the JSON-RPC 2.0 specification. It is designed to be transport-agnostic, focusing solely on the protocol messaging rather than the underlying communication method. The current version is 4.0.3, released on February 23, 2023, and the library appears to be actively maintained with periodic updates.

pip install jsonrpcclient
INSTALL
IMPORT
SIG · JSONRPCCLIENT
J
jsonrpcclient
serializationpythonv4.0.3
Install
1.5s avg
Import
31ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.034s · 17.8MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 1.5s · import 0.028s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

request
from jsonrpcclient import request
from jsonrpcclient.clients.http import HTTPClient
The 'clients' module was removed in v4.x; the library now focuses on direct message generation.
parse
from jsonrpcclient import parse
request_json
from jsonrpcclient import request_json
from jsonrpcclient import request; request('method', params=...) # for JSON string output
'request()' returns a Python dictionary-like object; 'request_json()' returns a JSON string.

This quickstart demonstrates how to construct a JSON-RPC request and parse a response using `jsonrpcclient`. It illustrates the library's core functionality for message handling, assuming an external library like `requests` is used for network transport.

import requests import json from jsonrpcclient import request, parse # Define a mock JSON-RPC server URL for demonstration. Replace with your actual endpoint. # For a real server, ensure it's running and accessible. # Example: A simple server might expose a 'subtract' method. jsonrpc_server_url = "http://localhost:5000/jsonrpc" # 1. Create a JSON-RPC request (Python dictionary-like object) # This example requests the 'subtract' method with positional parameters and an ID. request_obj = request("subtract", params=[42, 23], id=1) print(f"Generated JSON-RPC Request: {json.dumps(request_obj, indent=2)}") # 2. Send the request using a transport layer (e.g., 'requests' for HTTP) try: # In a real application, you would send request_obj to your server # and get a response_data from it. Example using 'requests' library: # response_obj_from_server = requests.post(jsonrpc_server_url, json=request_obj).json() # For quickstart, simulate a successful response from a server response_obj_from_server = {"jsonrpc": "2.0", "result": 19, "id": 1} print(f"\nReceived JSON-RPC Response Object: {json.dumps(response_obj_from_server, indent=2)}") # 3. Parse the received response parsed_response = parse(response_obj_from_server) # 4. Handle the parsed response if parsed_response.ok: print(f"\nSuccessfully Parsed Result: {parsed_response.result}") else: print(f"\nError Received from Server (Code: {parsed_response.error.code}): {parsed_response.error.message}") if parsed_response.error.data: print(f" Error Data: {parsed_response.error.data}") except requests.exceptions.ConnectionError: print(f"\nError: Could not connect to the JSON-RPC server at {jsonrpc_server_url}. Please ensure the server is running.") except json.JSONDecodeError: print("\nError: Failed to decode JSON response from the server.") except Exception as e: print(f"\nAn unexpected error occurred: {e}")
Debug
Known issues
breakingVersion 4.0.0 introduced significant breaking API changes. Modules like `jsonrpcclient.clients` and `jsonrpcclient.exceptions` were removed. Code written for `jsonrpcclient` v3.x and earlier is not compatible with v4.x without migration.
fix
Rewrite code to use the new functional API, primarily `from jsonrpcclient import request, parse` for message generation and parsing. Manage transport independently.
affects: >=4.0.0
gotcha`jsonrpcclient` is a protocol library and does not handle network transport (e.g., HTTP, WebSockets) itself. Users must integrate a separate library (like `requests` or `websockets`) for sending and receiving messages over the network.
fix
Always use an external library for the transport layer. For HTTP, `requests.post(url, json=request_object)` is a common pattern after creating `request_object` with `jsonrpcclient.request()`.
affects: All versions
gotchaDistinguish between `request()`/`parse()` (for Python dictionary-like objects) and `request_json()`/`parse_json()` (for raw JSON strings). Misusing these can lead to serialization errors or incorrectly formatted messages.
fix
Use `request(method, params)` when you intend to serialize the message to JSON yourself (e.g., `json.dumps(request(...))`). Use `request_json(method, params)` if you want the library to return the JSON string directly. Similar logic applies to `parse` and `parse_json` for incoming responses.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jsonrpcclient.clients'
Attempting to import from the `jsonrpcclient.clients` module, which was removed in version 4.0.0.
fix
Upgrade your code to the v4.x API, which uses `from jsonrpcclient import request, parse`. If you need client-like functionality, handle the transport manually. Alternatively, downgrade to a v3.x release (e.g., `pip install jsonrpcclient==3.3.6`).
TypeError: Object of type Request is not JSON serializable
You are passing the Python object returned by `jsonrpcclient.request()` directly to a JSON serialization function (e.g., `json.dumps`) or a transport library expecting a raw JSON string, without it being a serializable dictionary.
fix
Ensure that if `jsonrpcclient.request()` is used, its output (a dictionary-like object) is passed to a serialization function like `json.dumps()` or directly to a library that handles dictionary-to-JSON serialization (e.g., `requests.post(url, json=my_dict)`). Alternatively, use `jsonrpcclient.request_json()` to get a pre-serialized JSON string.
Server returned: {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 1}
The method name provided in the JSON-RPC request does not match any method exposed by the target server.
fix
Verify the exact method name, including case sensitivity, against the server's API documentation. Ensure there are no typos.
Server returned: {"jsonrpc": "2.0", "error": {"code": -32602, "message": "Invalid params"}, "id": 1}
The parameters sent in the request do not match the expected type, number, or structure (e.g., positional vs. named arguments) for the specified method on the server.
fix
Consult the server's API documentation to confirm the correct parameter types, order, and whether positional (`[value1, value2]`) or named (`{"key1": value1}`) parameters are expected. Adjust your `params` accordingly.
Upgrade
Version history
4.0.3latest on PyPI · released Feb 23, 2023
Audit
Dependencies
requestsoptionalCommonly used for HTTP transport layer integration, although not a direct dependency of the core library.
Agent activity
2 hits · last 30 days
node
2
Resources
jsonrpcclient — pip install jsonrpcclient · libregistry