Documentation

Author: charlesbaynham

sipyco/pc_rpc.py

@@ -27,10 +27,6 @@
 logger = logging.getLogger(__name__)
 
 
-class RPCConnectionError(ConnectionError):
-    pass
-
-
 class AutoTarget:
     """Use this as target value in clients for them to automatically connect
     to the target exposed by the server. Servers must have only one target."""
@@ -43,6 +39,13 @@ class IncompatibleServer(Exception):
     pass
 
 
+class RPCConnectionError(ConnectionError):
+    """Raised by the client when a method called fails due to connection
+    problems with the RPC server.
+    """
+    pass
+
+
 _init_string = b"ARTIQ pc_rpc\n"
 
 
@@ -78,18 +81,18 @@ class Client:
     automatically attempted. The user must call :meth:`~sipyco.pc_rpc.Client.close_rpc` to
     free resources properly after initialization completes successfully.
 
-    If the remote server shuts down during operation, ConnectionAbortedError is
-    raised by Client methods. The user should call
-    :meth:`~sipyco.pc_rpc.Client.close_rpc` and then discard this object. 
+    If the remote server shuts down during operation, RPCConnectionError is
+    raised by future calls to Client methods. The user should call
+    :meth:`~sipyco.pc_rpc.Client.close_rpc` and then discard this object.
 
     :param host: Identifier of the server. The string can represent a
         hostname or a IPv4 or IPv6 address (see
         ``socket.create_connection`` in the Python standard library).
     :param port: TCP port to use.
     :param target_name: Target name to select. ``IncompatibleServer`` is
         raised if the target does not exist.
-        Use :class:`.AutoTarget` for automatic selection if the server has only one
-        target.
+        Use :class:`.AutoTarget` for automatic selection if the server has 
+        only one target.
         Use ``None`` to skip selecting a target. The list of targets can then
         be retrieved using :meth:`~sipyco.pc_rpc.Client.get_rpc_id`
         and then one can be selected later using :meth:`~sipyco.pc_rpc.Client.select_rpc_target`.
@@ -143,11 +146,15 @@ def get_local_host(self):
         return self.__socket.getsockname()[0]
 
     def get_valid_methods(self):
-        """Returns a set of names of valid methods of the target"""
+        """Returns a set of names of methods which can be called on
+        the server"""
         return self.__valid_methods.copy()
 
     def is_closed(self):
-        """Return True if the connection to the server has been closed"""
+        """Return True if the connection to the server has been closed
+
+        This method will actively query the server for data to check
+        if the connection is working. """
         self.__closed = not self.__socket_is_open()
 
         return self.__closed
@@ -231,9 +238,10 @@ class AsyncioClient:
     uses ``asyncio`` instead of blocking calls.
 
     All RPC methods are coroutines. As with :class:`sipyco.pc_rpc.Client`,
-    methods will raise ConnectionAbortedError if the server closes the
-    connection. The user should call :meth:`~sipyco.pc_rpc.AsyncioClient.close_rpc`
-    and then discard this object.
+    methods will raise RPCConnectionError if the server closes the
+    connection. The user should call
+    :meth:`~sipyco.pc_rpc.AsyncioClient.close_rpc` and then discard this
+    object.
 
     Concurrent access from different asyncio tasks is supported; all calls
     use a single lock.
@@ -248,8 +256,8 @@ def __init__(self):
 
     async def connect_rpc(self, host, port, target_name):
         """Connects to the server. This cannot be done in __init__ because
-        this method is a coroutine. See :class:`sipyco.pc_rpc.Client` for a description of the
-        parameters."""
+        this method is a coroutine. See :class:`sipyco.pc_rpc.Client` for a
+        description of the parameters."""
         self.__reader, self.__writer = \
             await asyncio.open_connection(host, port, limit=100*1024*1024)
         try:
@@ -329,7 +337,7 @@ def __send(self, obj):
         line = pyon.encode(obj) + "\n"
         self.__writer.write(line.encode())
 
-    async def __recv(self):        
+    async def __recv(self):
         if not self.__closed:
             line = await self.__reader.readline()
         if self.__closed or not line: