lewis.core.control_client

This module provides client code for objects exposed via JSON-RPC over ZMQ.

See also

The server-part for these client classes is defined in the module control_server.

Members

ControlClient	This class provides an interface to a ControlServer instance on the server side.
ObjectProxy	This class serves as a base class for dynamically created classes on the client side that represent server-side objects.
ProtocolException	An exception type for exceptions related to the transport protocol, i.e. malformed requests etc.
RemoteException	This exception type replaces exceptions that are raised on the server, but unknown (i.e. not in the exceptions-module) on the client side.

class lewis.core.control_client.ControlClient(host='127.0.0.1', port='10000', timeout=3000)

Bases: object

This class provides an interface to a ControlServer instance on the server side. Proxies to exposed objects can be obtained either directly via get_object or, in case the server exposes a collection of objects at the top level, a dictionary of named objects can be obtained via get_object_collection.

If a timeout is supplied, all underlying network operations time out after the specified time (in milliseconds), for no timeout specify None.

Parameters:

• host – Host the control server is running on.

• port – Port on which the control server is listening.

• timeout – Timeout in milliseconds for ZMQ operations.

get_object_collection(object_name='')

If the remote end exposes a collection of objects under the supplied object name (empty for top level), this method returns a dictionary of these objects stored under their names on the server.

This function performs n + 1 calls to the server, where n is the number of objects.

Parameters:

object_name – Object name on the server. This is required if the object collection is not the top level object.

json_rpc(method, *args)

This method takes a ZMQ REQ-socket and submits a JSON-object containing the RPC (JSON-RPC 2.0 format) to the supplied method with the supplied arguments. Then it waits for a reply from the server and blocks until it has received a JSON-response. The method returns the response and the id it used to tag the original request, which is a random UUID (uuid.uuid4).

Parameters:

• method – Method to call on remote.

• args – Arguments to method call.

Returns:

JSON result and request id.

class lewis.core.control_client.ObjectProxy(connection, members, prefix='')

Bases: object

This class serves as a base class for dynamically created classes on the client side that represent server-side objects. Upon initialization, this class takes the supplied methods and installs appropriate proxy methods or properties into the object and class respectively. Because of that class manipulation, this class must never be used directly. Instead, it should be used as a base-class for dynamically created types that mirror types on the server, like this:

proxy = type("SomeClassName", (ObjectProxy,), {})(connection, methods, prefix)

There is however, the class ControlClient, which automates all that and provides objects that are ready to use.

Exceptions on the server are propagated to the client. If the exception is not part of the exceptions-module (builtins for Python 3), a RemoteException is raised instead which contains information about the server side exception.

All RPC method names are prefixed with the supplied prefix, which is usually the object name on the server plus a dot.

Parameters:

• connection – ControlClient-object for remote calls.

• members – List of strings to generate methods and properties.

• prefix – Usually object name on the server plus dot.

exception lewis.core.control_client.ProtocolException

Bases: Exception

An exception type for exceptions related to the transport protocol, i.e. malformed requests etc.

exception lewis.core.control_client.RemoteException(exception_type, message)

Bases: Exception

This exception type replaces exceptions that are raised on the server, but unknown (i.e. not in the exceptions-module) on the client side. To retain as much information as possible, the exception type on the server and the message are stored.

Parameters:

• exception_type – Type of the exception on the server side.

• message – Exception message on the server side.