Metadata-Version: 2.5
Name: jsonrpcclient
Version: 5.0.0rc1
Summary: Create JSON-RPC 2.0 requests and parse responses in Python
Keywords: json-rpc,jsonrpc,json-rpc-2.0,rpc,client
Author-email: Beau Barker <beau@explodinglabs.com>
Maintainer-email: Synapse Research <ben@synapsereality.io>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-Expression: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: pytest ; extra == "qa"
Requires-Dist: pytest-cov ; extra == "qa"
Project-URL: Changelog, https://bensynapse.github.io/jsonrpcclient/changelog/
Project-URL: Documentation, https://bensynapse.github.io/jsonrpcclient/
Project-URL: Homepage, https://bensynapse.github.io/jsonrpcclient/
Project-URL: Issues, https://github.com/bensynapse/jsonrpcclient/issues
Project-URL: Repository, https://github.com/bensynapse/jsonrpcclient
Provides-Extra: qa
Import-Name: jsonrpcclient

<p align="center">
  <a href="https://pypi.org/project/jsonrpcclient/"><img src="https://img.shields.io/pypi/v/jsonrpcclient.svg" alt="PyPI version" /></a>
  <a href="https://github.com/bensynapse/jsonrpcclient/actions/workflows/ci.yml"><img src="https://github.com/bensynapse/jsonrpcclient/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://bensynapse.github.io/jsonrpcclient/#install"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue" alt="Python 3.11 to 3.14" /></a>
  <a href="https://pypistats.org/packages/jsonrpcclient"><img src="https://img.shields.io/pypi/dm/jsonrpcclient" alt="Downloads per month" /></a>
  <a href="https://github.com/bensynapse/jsonrpcclient/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bensynapse/jsonrpcclient" alt="License: MIT" /></a>
</p>

<p align="center">
  <img alt="jsonrpcclient" src="https://raw.githubusercontent.com/bensynapse/jsonrpcclient/main/logo.png" />
</p>

<p align="center">
  <i>Create JSON-RPC 2.0 requests and parse responses in Python</i>
</p>

<p align="center">
  <a href="https://bensynapse.github.io/jsonrpcclient/">Documentation</a> |
  <a href="https://bensynapse.github.io/jsonrpcclient/reference/">API reference</a> |
  <a href="https://bensynapse.github.io/jsonrpcclient/examples/">Examples</a> |
  <a href="https://bensynapse.github.io/jsonrpcclient/changelog/">Changelog</a> |
  <a href="https://bensynapse.github.io/jsonrpcclient/migration/">Migration</a>
</p>

jsonrpcclient builds [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
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

```sh
pip install jsonrpcclient
```

The [changelog](https://bensynapse.github.io/jsonrpcclient/changelog/) lists
what changed in each release.

## Quickstart

This sends `ping` to a JSON-RPC server at `http://localhost:8000/`, using
[requests](https://requests.readthedocs.io/) for the HTTP part:

<!-- requires: requests -->
<!-- server -->
```python
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:

```text
pong
```

For JSON strings, use `request_json` and `parse_json`. The
[examples](https://bensynapse.github.io/jsonrpcclient/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](https://github.com/bensynapse/jsonrpcclient/blob/main/docs/migration.md#from-4x-to-50) lists every change, and
[issue 252](https://github.com/bensynapse/jsonrpcclient/issues/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](https://bensynapse.github.io/jsonrpcclient/migration/)
before upgrading.

## Documentation

- [User guide](https://bensynapse.github.io/jsonrpcclient/requests/): requests,
  notifications, batches, ids, responses and error handling
- [API reference](https://bensynapse.github.io/jsonrpcclient/reference/)
- [Transport examples](https://bensynapse.github.io/jsonrpcclient/examples/)
- [FAQ](https://bensynapse.github.io/jsonrpcclient/faq/)
- [Contributing](https://github.com/bensynapse/jsonrpcclient/blob/main/CONTRIBUTING.md)
  and [security policy](https://github.com/bensynapse/jsonrpcclient/blob/main/SECURITY.md),
  which says how long each release line gets fixes
- [License](https://github.com/bensynapse/jsonrpcclient/blob/main/LICENSE): MIT

## See also

[jsonrpcserver](https://github.com/bensynapse/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](https://synapsereality.io).

