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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.034s · 17.8MB
glibcpy 3.10–3.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}")
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.
fixUpgrade 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.
fixEnsure 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.
fixVerify 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.
fixConsult 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.