jsonrpcclient 1.0.11

JSON-RPC 2.0 client library for Python 3

Make remote procedure calls with JSON-RPC 2.0.

Installation

pip install jsonrpcclient

Usage

Set the server details, then start making requests.

>>> from jsonrpcclient import Server
>>> server = Server('http://example.com/api')
>>> server.request('add', 2, 3)
5

Hint

To see the underlying messages going back and forth, set the logging level to INFO:

logging.getLogger('jsonrpcclient').setLevel(logging.INFO)

The first argument to request is the method; everything else is passed as params. You can pass any number of positional or keyword arguments, and they will be translated into JSON-RPC.

>>> server.request('find', 42, name='Foo')
--> {"jsonrpc": "2.0", "method": "find", "params": [42, {"name": "Foo"}], "id": 1}
<-- 200 {"jsonrpc": "2.0", "result": "Bar", "id": 1}
Bar

Note

To conform strictly to JSON-RPC 2.0 protocol, one should use either positional or keyword parameters, but not both in the same request. See link.

If you don’t need any data returned, use notify instead of request.

>>> server.notify('go')
--> {"jsonrpc": "2.0", "method": "go"}
<-- 200 OK

Alternate usage

If you prefer, there’s another way to call a remote procedure:

>>> server.add(2, 3, response=True)

Which is the same as saying server.request('add', 2, 3).

Use response=True to get a response; without that it’s a notification.

Authentication

To make authenticated requests, pass a second argument to Server.

>>> server = Server('http://example.com/api', auth=('user', 'pass'))

For more options, see the requests package which handles the authentication.

Exceptions

Catch the base exception JsonRpcClientError when communicating with the server. This will be raised when there’s an issue such as connection problems, or if the server responded with an error response.

from jsonrpcclient.exceptions import JsonRpcClientError
try:
    server.request('go')
except JsonRpcClientError as e:
    print(str(e))

Issue tracker is here.

If you need a server, try my jsonrpcserver library.

Todo

• Ability to make GET requests.

• Ability to configure the http header. Currently Content-Type is hard-coded as “application/json”, but perhaps should be “application/json-rpc”. See http://jsonrpc.org/historical/json-rpc-over-http.html#http-header

Changelog

1.0.11 - 2014-12-12

• Rewrote an internal function, rpc.request.

1.0.10 - 2014-12-11

• Exceptions have been cleaned up. The base exception is now named JsonRpcClientError.

• Tests added for 100% code coverage.

1.0.9 - 2014-12-02

• Added authentication.

• Messages are now output on the INFO log level.

1.0.8 - 2014-12-02

• Show the response status code in the log.

1.0.7 - 2014-11-21

• When using the “alternate” (server.add) method to make a request, only send “id” if response=True is explicitly passed (fixed)

• The underlying JSON messages are now hidden by default. To see them you should increase the logging level (see above).

• Tests moved into separate “tests” dir.