jsonrpc-requests: a compact JSON-RPC client library backed by requests

This is a compact (~100 SLOC) and simple JSON-RPC client implementation written while debugging a picky server.

Project Status (please read)

This repository is a fork of the original gciotta/jsonrpc-requests, whose GitHub repository has since been deleted (last archived alive 2018-06-11, first archived as 404 2024-06-16; the exact deletion date is unknown). I (@vaab) used it in personal projects and contributed back in 2015: I proposed a few PRs (my last contribution is dated 2015-05-04), most of which were accepted upstream and released in version 0.2 (2015-06-21). Upstream then continued without me up to 0.4.0 (2017-02-11) before its repository disappeared, while my fork kept a few divergent changes of its own (an ApplicativeError exception class, response/request id consistency checking, session support).

I reassessed the situation on 2026-07-08. Because I have a very limited usage of this package and no time to deal properly with the situation, I decided not to publish my version on PyPI — only here on GitHub. Note that the last version available on PyPI as jsonrpc-requests is 0.4.0 (uploaded 2017-02-11, by the original author) and is not API-compatible with this fork: it has no ApplicativeError, and its exceptions carry different arguments. This fork is only installable directly from git, e.g.:

pip install "jsonrpc-requests @ git+https://github.com/0k/jsonrpc-requests.git@0.5.0"

Versions are tagged when convenient for my own dependent projects; there is no roadmap, no support, and no stability promise beyond that.

This package has limited value for external users. If you are looking for a real, alive, recently maintained library in this lineage, you should probably head towards Emily Watson's continuation forks:

• jsonrpc-async — asyncio/aiohttp client
• jsonrpc-websocket — asyncio websocket client
• jsonrpc-base — their shared protocol core

Note these are async-only; no maintained synchronous requests-backed variant is known. The original 0.4.0 git history is preserved in the GitHub fork network (e.g. pellepim/jsonrpc-requests) and in this repository's own tags.

Main Features

• Python 2.7 & 3.4 compatible
• Exposes requests options
• Supports nested namespaces (eg. app.users.getUsers())
• 100% test coverage

TODO

• Batch requests (http://www.jsonrpc.org/specification#batch)

Usage

from jsonrpc_requests import Server
server = Server('http://localhost:8080')
server.foo(1, 2)
server.foo(bar=1, baz=2)
server.foo.bar(baz=1, qux=2)

A notification:

from jsonrpc_requests import Server
server.foo(bar=1, _notification=True)

Pass through arguments to requests (see also requests documentation)

from jsonrpc_requests import Server
server = Server('http://localhost:8080', auth=('user', 'pass'), headers={'x-test2': 'true'})

Pass through requests exceptions

from jsonrpc_requests import Server, TransportError
server = Server('http://unknown-host')
try:
    server.foo()
except TransportError as transport_error:
    print(transport_error.args[1]) # this will hold a `requests.exceptions.RequestException` instance

Tests

Install the Python tox package and run tox, it'll test this package with Python 2.7 and 3.4.

Credits

@mbroadst for providing full support for nested method calls, JSON-RPC RFC compliance and other improvements.