1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
.. currentmodule:: aiorpcx
RPC items
=========
The :mod:`aiorpcx` module defines some classes, instances of which
will be returned by some of its APIs. You should not need to
instantiate these objects directly.
An instance of one of these classes is called an :dfn:`item`.
.. class:: RPCRequest
An RPC request or notification that has been received, or an
outgoing notification.
Outgoing requests are represented by :class:`RPCRequestOut` objects.
.. attribute:: method
The RPC method being invoked, a string.
If an incoming request is ill-formed, so that, e.g., its method
could not be determined, then this will be an :class:`RPCError`
instance that describes the error.
.. attribute:: args
The arguments passed to the RPC method. This is a list or a
dictionary, a dictionary if the arguments were passed by
parameter name.
.. attribute:: request_id
The ID given to the request so that responses can be associated
with requests. Normally an integer, or :const:`None` if the
request is a :dfn:`notification`. Rarely it might be a floating
point number or string.
.. method:: is_notification()
Returns :const:`True` if the request is a notification (its
:attr:`request_id` is :const:`None`), otherwise :const:`False`.
.. class:: RPCRequestOut
An outgoing RPC request that is not a notification. A subclass of
:class:`RPCRequest` and :class:`asyncio.Future
<https://docs.python.org/3/library/asyncio-task.html#asyncio.Future>`.
When an outgoing request is created, typically via the
:meth:`send_request` method of a client or server session, you can
specify a callback to be called when the request is done. The
callback is passed the request object, and the result can be
obtained via its :meth:`result` method.
A request can also be await-ed. Currently the result of await-ing
is the same as calling :meth:`result` on the request but this may
change in future.
.. class:: RPCResponse
An incoming or outgoing response. Outgoing response objects are
automatically created by the framework when a request handler
returns its result.
.. attribute:: result
The response result, a Python object. If an error occurred this
will be an :class:`RPCError` object describing the error.
.. attribute:: request_id
The ID of the request this is a repsonse to. Notifications do
not get responses so this will never be :const:`None`.
If :attr:`result` in an :class:`RPCError` their
:attr:`request_id` attributes will match.
.. class:: RPCError
Represents an error, either in an :class:`RPCResponse` object if an
error occurred processing a request, or in a :class:`RPCRequest` if
an incoming request was ill-formed.
.. attribute:: message
The error message as a string.
.. attribute:: code
The error code, an integer.
.. attribute:: request_id
The ID of the request that gave an error if it could be
determined, otherwise :const:`None`.
.. class:: RPCBatch
Represents an incoming or outgoing RPC response batch, or an
incoming RPC request batch.
.. attribute:: items
A list of the items in the batch. The list cannot be empty, and
each item will be an :class:`RPCResponse` object for a response
batch, and an :class:`RPCRequest` object for a request batch.
Notifications and requests can be mixed together.
Batches are iterable through their items, and taking their length
returns the length of the items list.
.. method:: requests
A generator that yields non-notification items of a request
batch, or each item for a response batch.
.. method:: request_ids
A *frozenset* of all request IDs in the batch, ignoring
notifications.
.. method:: is_request_batch
Return :const:`True` if the batch is a request batch.
.. class:: RPCBatchOut
An outgoing RPC batch. A subclass of :class:`RPCBatch` and
:class:`asyncio.Future
<https://docs.python.org/3/library/asyncio-task.html#asyncio.Future>`.
When an outgoing request batch is created, typically via the
:meth:`new_batch` method of a client or server session, you can
specify a callback to be called when the batch is done. The
callback is passed the batch object.
Each non-notification item in an :class:`RPCBatchOut` object is
itself an :class:`RPCRequestOut` object that can be independently
waited on or cancelled. Notification items are :class:`RPCRequest`
objects. Since batches are responded to as a whole, all member
requests will be completed simultaneously. The order of callbacks
of member requests, and of the batch itself, is unspecified.
Cancelling a batch, or calling its :meth:`set_result` or
:meth:`set_exception` methods cancels all its requests.
.. method:: add_request(method, args=None, on_done=None)
Add a request to the batch. A callback can be specified that will
be called when the request completes. Returns the
:class:`RPCRequestOut` request that was added to the batch.
.. method:: add_notification(method, args=None)
Add a notification to the batch.
RPC Protocol Classes
--------------------
RPC protocol classes should inherit from :class:`RPCProtocolBase`.
The base class provides a few utility functions returning
:class:`RPCError` objects. The derived class should redefine some
constant class attributes.
.. class:: RPCProtocolBase
.. attribute:: INTERNAL_ERROR
The integer error code to use for an internal error.
.. attribute:: INVALID_ARGS
The integer error code to use when an RPC request passes invalid
arguments.
.. attribute:: INVALID_REQUEST
The integer error code to use when an RPC request is invalid.
.. attribute:: METHOD_NOT_FOUND
The integer error code to use when an RPC request is for a
non-existent method.
.. classmethod:: JSONRPC.internal_error(request_id)
Return an :class:`RPCError` object with error code
:attr:`INTERNAL_ERROR` for the given request ID. The error message
will be ``"internal error processing request"``.
:param request_id: the request ID, normally an integer or string
:return: the error object
:rtype: :class:`RPCError`
.. classmethod:: JSONRPC.args_error(message)
Return an :class:`RPCError` object with error code
:attr:`INVALID_ARGS` with the given error message and a request ID
of :const:`None`.
:param str message: the error message
:return: the error object
:rtype: :class:`RPCError`
.. classmethod:: JSONRPC.invalid_request(message, request_id=None)
Return an :class:`RPCError` object with error code
:attr:`INVALID_REQUEST` with the given error message and
request ID.
:param str message: the error message
:param request_id: the request ID, normally an integer or string
:return: the error object
:rtype: :class:`RPCError`
.. classmethod:: JSONRPC.method_not_found(message)
Return an :class:`RPCError` object with error code
:attr:`METHOD_NOT_FOUND` with the given error message and a request
ID :const:`None`.
:param str message: the error message
:return: the error object
:rtype: :class:`RPCError`
|
