JSON-RPC Client

Common errors

• ModuleNotFoundError: No module named 'jsonrpcclient.clients'

  cause 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

  cause 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}

  cause 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}

  cause 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.

Warnings

• breaking Version 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.
• 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()`.
• gotcha Distinguish 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.

Install

• pip install jsonrpcclient Install stable version

Imports

• request
  wrong:

  from jsonrpcclient.clients.http import HTTPClient

  correct:

  from jsonrpcclient import request

  The 'clients' module was removed in v4.x; the library now focuses on direct message generation.
• parse

  from jsonrpcclient import parse

• request_json
  wrong:

  from jsonrpcclient import request; request('method', params=...) # for JSON string output

  correct:

  from jsonrpcclient import request_json

  'request()' returns a Python dictionary-like object; 'request_json()' returns a JSON string.

Quickstart

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}")