Add documentation of the rpc module

aiorpcx/rpc.py

@@ -40,7 +40,7 @@ class RPCRequest(object):
     '''An RPC request or notification that has been received, or an
     outgoing notification.
 
-    Outgong requests are represented by RPCRequestOut.
+    Outgoing requests are represented by RPCRequestOut.
     '''
 
     def __init__(self, method, args, request_id):
@@ -100,6 +100,7 @@ class RPCResponse(object):
     '''
 
     def __init__(self, result, request_id):
+        assert request_id is not None
         # result is an RPCError object if an error was returned
         self.result = result
         self.request_id = request_id
@@ -146,7 +147,9 @@ def __repr__(self):
 
 
 class RPCBatch(object):
-    '''An RPC request or response batch, incoming or outgoing.'''
+    '''An incoming or outgoing RPC response batch, or an incoming RPC
+    request batch.
+    '''
 
     def __init__(self, items):
         self.items = items

docs/index.rst

@@ -48,6 +48,7 @@ Documentation
 .. toctree::
 
    json-rpc
+   rpc
 
 Indices and tables
 ==================

docs/json-rpc.rst

@@ -1,4 +1,4 @@
-.. currentmodule:: jsonrpc
+.. currentmodule:: aiorpcx
 
 JSON RPC
 ========
@@ -75,33 +75,33 @@ passed over the network after framing.
 
 .. classmethod:: JSONRPC.request_message(item)
 
-   Convert an :class:`RPCRequest` item to a message.
+   Convert a request item to a message.
 
-   :param RPCRequest item: the request item
+   :param item: an :class:`RPCRequest` item
    :return: the message
    :rtype: bytes
 
 .. classmethod:: JSONRPC.response_message(item)
 
-   Convert an :class:`RPCResponse` item to a message.
+   Convert a response item to a message.
 
-   :param RPCResponse item: the response item
+   :param item: an :class:`RPCResponse` item
    :return: the message
    :rtype: bytes
 
 .. classmethod:: JSONRPC.error_message(item)
 
-   Convert an :class:`RPCError` item to a message.
+   Convert an error item to a message.
 
-   :param RPCError item: the error item
+   :param item: an :class:`RPCError` item
    :return: the message
    :rtype: bytes
 
 .. classmethod:: JSONRPC.batch_message(item)
 
-   Convert an :class:`RPCError` item to a message.
+   Convert a batch item to a message.
 
-   :param RPCBatch item: the batch item
+   :param item: an :class:`RPCBatch` item
    :return: the message
    :rtype: bytes
 
@@ -113,8 +113,9 @@ passed over the network after framing.
    of `payload` if that is a dictionary, otherwise :const:`None`.
 
    :param payload: a Python object that can be represented as JSON.
-      Numbers, strings, lists, dictionaries, :const:`True`,
-      :const:`False` and :const:`None` are all valid.
+                   Numbers, strings, lists, dictionaries,
+                   :const:`True`, :const:`False` and :const:`None` are
+                   all valid.
    :return: a JSON message
    :rtype: bytes
 
@@ -132,7 +133,7 @@ appropriately for the class's protocol version.
    error for the given request ID.  The error message will be "internal
    error processing request".
 
-   :param item: the request ID, normally an integer or string
+   :param request_id: the request ID, normally an integer or string
    :return: the error object
    :rtype: :class:`RPCError`
 

docs/rpc.rst

@@ -0,0 +1,163 @@
+.. currentmodule:: aiorpcx
+
+rpc
+===
+
+The :mod:`rpc` module defines some RPC object classes that will be
+returned by other APIs in :mod:`aiorpcX`.  You should not 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 independenlty
+  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.
+
+  .. method:: add_notification(method, args=None)
+
+    Add a notification to the batch.