{"id":9056,"library":"jsonrpcclient","title":"JSON-RPC Client","description":"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.","status":"active","version":"4.0.3","language":"en","source_language":"en","source_url":"https://github.com/explodinglabs/jsonrpcclient","tags":["json-rpc","rpc","client","api","protocol"],"install":[{"cmd":"pip install jsonrpcclient","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Commonly used for HTTP transport layer integration, although not a direct dependency of the core library.","package":"requests","optional":true}],"imports":[{"note":"The 'clients' module was removed in v4.x; the library now focuses on direct message generation.","wrong":"from jsonrpcclient.clients.http import HTTPClient","symbol":"request","correct":"from jsonrpcclient import request"},{"symbol":"parse","correct":"from jsonrpcclient import parse"},{"note":"'request()' returns a Python dictionary-like object; 'request_json()' returns a JSON string.","wrong":"from jsonrpcclient import request; request('method', params=...) # for JSON string output","symbol":"request_json","correct":"from jsonrpcclient import request_json"}],"quickstart":{"code":"import requests\nimport json\nfrom jsonrpcclient import request, parse\n\n# Define a mock JSON-RPC server URL for demonstration. Replace with your actual endpoint.\n# For a real server, ensure it's running and accessible.\n# Example: A simple server might expose a 'subtract' method.\njsonrpc_server_url = \"http://localhost:5000/jsonrpc\"\n\n# 1. Create a JSON-RPC request (Python dictionary-like object)\n# This example requests the 'subtract' method with positional parameters and an ID.\nrequest_obj = request(\"subtract\", params=[42, 23], id=1)\nprint(f\"Generated JSON-RPC Request: {json.dumps(request_obj, indent=2)}\")\n\n# 2. Send the request using a transport layer (e.g., 'requests' for HTTP)\ntry:\n    # In a real application, you would send request_obj to your server\n    # and get a response_data from it. Example using 'requests' library:\n    # response_obj_from_server = requests.post(jsonrpc_server_url, json=request_obj).json()\n\n    # For quickstart, simulate a successful response from a server\n    response_obj_from_server = {\"jsonrpc\": \"2.0\", \"result\": 19, \"id\": 1}\n\n    print(f\"\\nReceived JSON-RPC Response Object: {json.dumps(response_obj_from_server, indent=2)}\")\n\n    # 3. Parse the received response\n    parsed_response = parse(response_obj_from_server)\n\n    # 4. Handle the parsed response\n    if parsed_response.ok:\n        print(f\"\\nSuccessfully Parsed Result: {parsed_response.result}\")\n    else:\n        print(f\"\\nError Received from Server (Code: {parsed_response.error.code}): {parsed_response.error.message}\")\n        if parsed_response.error.data:\n            print(f\"  Error Data: {parsed_response.error.data}\")\n\nexcept requests.exceptions.ConnectionError:\n    print(f\"\\nError: Could not connect to the JSON-RPC server at {jsonrpc_server_url}. Please ensure the server is running.\")\nexcept json.JSONDecodeError:\n    print(\"\\nError: Failed to decode JSON response from the server.\")\nexcept Exception as e:\n    print(f\"\\nAn unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Rewrite code to use the new functional API, primarily `from jsonrpcclient import request, parse` for message generation and parsing. Manage transport independently.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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()`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to import from the `jsonrpcclient.clients` module, which was removed in version 4.0.0.","error":"ModuleNotFoundError: No module named 'jsonrpcclient.clients'"},{"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.","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.","error":"TypeError: Object of type Request is not JSON serializable"},{"fix":"Verify the exact method name, including case sensitivity, against the server's API documentation. Ensure there are no typos.","cause":"The method name provided in the JSON-RPC request does not match any method exposed by the target server.","error":"Server returned: {\"jsonrpc\": \"2.0\", \"error\": {\"code\": -32601, \"message\": \"Method not found\"}, \"id\": 1}"},{"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.","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.","error":"Server returned: {\"jsonrpc\": \"2.0\", \"error\": {\"code\": -32602, \"message\": \"Invalid params\"}, \"id\": 1}"}]}