0
# JSON-RPC
1
2
A comprehensive Python implementation of JSON-RPC 1.0 and 2.0 transport specification. This library provides protocol implementation only, without transport functionality, making it transport-agnostic and suitable for integration with any transport mechanism like HTTP, WebSockets, or message queues.
3
4
## Package Information
5
6
- **Package Name**: json-rpc
7
- **Language**: Python
8
- **Installation**: `pip install json-rpc`
9
- **Python Support**: 2.6+, 3.3+, PyPy
10
- **Optional Integrations**: Django, Flask
11
12
## Core Imports
13
14
```python
15
from jsonrpc import JSONRPCResponseManager, dispatcher
16
```
17
18
For specific components:
19
20
```python
21
from jsonrpc import Dispatcher
22
from jsonrpc.manager import JSONRPCResponseManager
23
from jsonrpc.exceptions import JSONRPCError, JSONRPCDispatchException
24
from jsonrpc.jsonrpc import JSONRPCRequest
25
```
26
27
## Basic Usage
28
29
```python
30
from jsonrpc import JSONRPCResponseManager, dispatcher
31
32
# Method 1: Using the global dispatcher
33
@dispatcher.add_method
34
def add(a, b):
35
return a + b
36
37
@dispatcher.add_method
38
def subtract(a, b):
39
return a - b
40
41
# Handle JSON-RPC request
42
request_data = '{"jsonrpc": "2.0", "method": "add", "params": [5, 3], "id": 1}'
43
response = JSONRPCResponseManager.handle(request_data, dispatcher)
44
print(response.json)
45
# Output: {"jsonrpc": "2.0", "result": 8, "id": 1}
46
47
# Method 2: Creating a custom dispatcher
48
from jsonrpc import Dispatcher
49
50
my_dispatcher = Dispatcher()
51
my_dispatcher.add_method(lambda x: x * 2, name="double")
52
my_dispatcher["echo"] = lambda s: s
53
54
request_data = '{"jsonrpc": "2.0", "method": "double", "params": [21], "id": 2}'
55
response = JSONRPCResponseManager.handle(request_data, my_dispatcher)
56
print(response.json)
57
# Output: {"jsonrpc": "2.0", "result": 42, "id": 2}
58
```
59
60
## Architecture
61
62
The json-rpc library follows a clean separation of concerns:
63
64
- **Protocol Layer**: Handles JSON-RPC 1.0 and 2.0 protocol specifics (request/response format validation)
65
- **Dispatcher**: Maps method names to callable functions with flexible registration patterns
66
- **Manager**: Orchestrates request processing, method dispatch, and error handling
67
- **Transport Agnostic**: No built-in transport - integrates with any HTTP framework, WebSocket library, or messaging system
68
- **Backend Integrations**: Ready-to-use Django and Flask integrations for web applications
69
70
This design enables the library to serve as a foundation for JSON-RPC implementations across different transport mechanisms and frameworks.
71
72
## Capabilities
73
74
### Core JSON-RPC Protocol
75
76
Complete implementation of JSON-RPC 1.0 and 2.0 protocols with automatic version detection, batch request support, and comprehensive error handling.
77
78
```python { .api }
79
class JSONRPCResponseManager:
80
@classmethod
81
def handle(cls, request_str: str, dispatcher: dict, context: dict = None): ...
82
83
@classmethod
84
def handle_request(cls, request, dispatcher: dict, context: dict = None): ...
85
```
86
87
[Core JSON-RPC Protocol](./core-jsonrpc.md)
88
89
### Request and Response Objects
90
91
Structured request and response objects for both JSON-RPC versions with automatic serialization, validation, and batch processing support.
92
93
```python { .api }
94
class JSONRPCRequest:
95
@classmethod
96
def from_json(cls, json_str: str): ...
97
98
@classmethod
99
def from_data(cls, data: dict): ...
100
101
class JSONRPC20Request:
102
def __init__(self, method: str = None, params = None, _id = None, is_notification: bool = None): ...
103
104
class JSONRPC10Request:
105
def __init__(self, method: str = None, params = None, _id = None, is_notification: bool = None): ...
106
```
107
108
[Requests and Responses](./requests-responses.md)
109
110
### Method Dispatching
111
112
Flexible method registration and dispatch system supporting functions, classes, objects, and decorators with context injection.
113
114
```python { .api }
115
class Dispatcher:
116
def __init__(self, prototype = None): ...
117
def add_method(self, f = None, name: str = None, context_arg: str = None): ...
118
def add_class(self, cls): ...
119
def add_object(self, obj): ...
120
def add_dict(self, dict: dict, prefix: str = ''): ...
121
```
122
123
[Method Dispatching](./dispatcher.md)
124
125
### Exception and Error Handling
126
127
Comprehensive error handling with predefined JSON-RPC error types and custom exception support for robust error reporting.
128
129
```python { .api }
130
class JSONRPCError:
131
def __init__(self, code: int = None, message: str = None, data = None): ...
132
133
class JSONRPCDispatchException(Exception):
134
def __init__(self, code: int = None, message: str = None, data = None, *args, **kwargs): ...
135
```
136
137
[Exceptions and Error Handling](./exceptions.md)
138
139
### Backend Integrations
140
141
Ready-to-use integrations for Django and Flask frameworks providing HTTP endpoints, URL routing, and request handling.
142
143
```python { .api }
144
# Django backend
145
from jsonrpc.backend.django import JSONRPCAPI
146
147
# Flask backend
148
from jsonrpc.backend.flask import JSONRPCAPI
149
```
150
151
[Backend Integrations](./backends.md)
152
153
## Types
154
155
```python { .api }
156
# Core dispatcher type
157
dispatcher: Dispatcher
158
159
# Version information
160
__version__: str
161
version: str
162
163
# Project information
164
__project__: str
165
PROJECT: str
166
```