Code Documentation

Server

instrumentserver.server.core

Core functionality of the instrument server.

class instrumentserver.server.core.Operation(value)

Valid operations for the server.

get_existing_instruments = 'get_existing_instruments'

Get a list of instruments the server has instantiated.

create_instrument = 'create_instrument'

Create a new instrument.

get_blueprint = 'get_blueprint'

Get the blueprint of an object.

call = 'call'

Make a call to an object.

get_param_dict = 'get_param_dict'

Get the station contents as parameter dict.

set_params = 'set_params'

Set station parameters from a dictionary.

class instrumentserver.server.core.InstrumentCreationSpec(instrument_class: str, name: str = '', args: Optional[Tuple] = None, kwargs: Optional[Dict[str, Any]] = None)

Spec for creating an instrument instance.

instrument_class: str

Driver class as string, in the format “global.path.to.module.DriverClass”.

args: Optional[Tuple] = None

Arguments to pass to the constructor.

kwargs: Optional[Dict[str, Any]] = None

kw args to pass to the constructor.

class instrumentserver.server.core.CallSpec(target: str, args: Optional[Any] = None, kwargs: Optional[Dict[str, Any]] = None)

Spec for executing a call on an object in the station.

target: str

Full name of the callable object, as string, relative to the station object. E.g.: “instrument.my_callable” refers to station.instrument.my_callable.

args: Optional[Any] = None

Positional arguments to pass.

kwargs: Optional[Dict[str, Any]] = None

kw args to pass.

class instrumentserver.server.core.ParameterBluePrint(name: str, path: str, base_class: str, parameter_class: str, gettable: bool = True, settable: bool = True, unit: str = '', vals: Optional[Validator] = None, docstring: str = '', setpoints: Optional[List[str]] = None)

Spec necessary for creating parameter proxies.

class instrumentserver.server.core.MethodBluePrint(name: str, path: str, call_signature: Signature, docstring: str = '')

Spec necessary for creating method proxies.

class instrumentserver.server.core.InstrumentModuleBluePrint(name: str, path: str, base_class: str, instrument_module_class: str, docstring: str = '', parameters: ~typing.Optional[~typing.Dict[str, ~instrumentserver.server.core.ParameterBluePrint]] = <factory>, methods: ~typing.Optional[~typing.Dict[str, ~instrumentserver.server.core.MethodBluePrint]] = <factory>, submodules: ~typing.Optional[~typing.Dict[str, ~instrumentserver.server.core.InstrumentModuleBluePrint]] = <factory>)

Spec necessary for creating instrument proxies.

class instrumentserver.server.core.ParameterBroadcastBluePrint(name: str, action: str, value: Optional[int] = None, unit: Optional[str] = None)

Blueprint to broadcast parameter changes.

toDictFormat()

Formats the blueprint for easy conversion to dictionary later.

class instrumentserver.server.core.ParameterSerializeSpec(path: Optional[str] = None, attrs: List[str] = <factory>, args: Optional[Any] = <factory>, kwargs: Optional[Dict[str, Any]] = <factory>)

path: Optional[str] = None

Path of the object to serialize. None refers to the station as a whole.

attrs: List[str]

Which attributes to include for each parameter. Default is [‘values’].

args: Optional[Any]

Additional arguments to pass to the serialization function serialize.toParamDict().

kwargs: Optional[Dict[str, Any]]

Additional kw arguments to pass to the serialization function serialize.toParamDict().

class instrumentserver.server.core.ServerInstruction(operation: ~instrumentserver.server.core.Operation, create_instrument_spec: ~typing.Optional[~instrumentserver.server.core.InstrumentCreationSpec] = None, call_spec: ~typing.Optional[~instrumentserver.server.core.CallSpec] = None, requested_path: ~typing.Optional[str] = None, serialization_opts: ~typing.Optional[~instrumentserver.server.core.ParameterSerializeSpec] = None, set_parameters: ~typing.Optional[~typing.Dict[str, ~typing.Any]] = <factory>, args: ~typing.Optional[~typing.List[~typing.Any]] = <factory>, kwargs: ~typing.Optional[~typing.Dict[str, ~typing.Any]] = <factory>)

Instruction spec for the server.

Valid operations:

• Operation.get_existing_instruments – get the instruments currently instantiated in the station.

  • Required options: -

  • Return message: dictionary with instrument name and class (as string).

• Operation.create_instrument – create a new instrument in the station.

  • Required options: create_instrument_spec

  • Return message: None

• Operation.call – make a call to an object in the station.

  • Required options: call_spec

  • Return message: The return value of the call.

• Operation.get_blueprint – request the blueprint of an object

  • Required options: requested_path

  • Return message: The blueprint of the object.

• Operation.get_param_dict – request parameters as dictionary Get the parameters of either the full station or a single object.

  • Options: serialization_opts

  • Return message: param dict.

operation: Operation

This is the only mandatory item. Which other fields are required depends on the operation.

create_instrument_spec: Optional[InstrumentCreationSpec] = None

Specification for creating an instrument.

call_spec: Optional[CallSpec] = None

Specification for executing a call.

requested_path: Optional[str] = None

Name of the instrument for which we want the blueprint.

serialization_opts: Optional[ParameterSerializeSpec] = None

Options for serialization.

set_parameters: Optional[Dict[str, Any]]

Setting parameters in bulk with a paramDict.

args: Optional[List[Any]]

Generic arguments.

kwargs: Optional[Dict[str, Any]]

Generic keyword arguments.

class instrumentserver.server.core.ServerResponse(message: Optional[Any] = None, error: Union[None, str, Warning, Exception] = None)

Spec for what the server can return.

If the requested operation succeeds, message will the return of that operation, and error is None. See ServerInstruction for a documentation of the expected returns. If an error occurs, message is typically None, and error contains an error message or object describing the error.

message: Optional[Any] = None

The return message.

error: Union[None, str, Warning, Exception] = None

Any error message occured during execution of the instruction.

class instrumentserver.server.core.StationServer(parent: Optional[QObject] = None, port: int = 5555, allowUserShutdown: bool = False, addresses: List[str] = [], initScript: Optional[str] = None)

The main server object.

Encapsulated in a separate object so we can run it in a separate thread.

Port should always be an odd number to allow the next even number to be its corresponding publishing port.

messageReceived

Signal(str, str) – emit messages for display in the gui (or other stuff the gui wants to do with it. Arguments: the message received, and the reply sent.

serverStarted

Signal(int) – emitted when the server is started. Arguments: the port.

finished

Signal() – emitted when we shut down.

instrumentCreated

Signal(Dict) – emitted when a new instrument was created. Argument is the blueprint of the instrument.

parameterSet

Signal(str, Any) – emitted when a parameter was set Arguments: full parameter location as string, value.

parameterGet

Signal(str, Any) – emitted when a parameter was retrieved Arguments: full parameter location as string, value.

funcCalled

Signal(str, List[Any], Dict[str, Any], Any) – emitted when a function was called Arguments: full function location as string, arguments, kw arguments, return value.

startServer() → None

Start the server. This function does not return until the ZMQ server has been shut down.

executeServerInstruction(instruction: ServerInstruction) → Tuple[ServerResponse, str]

This is the interpreter function that the server will call to translate the dictionary received from the proxy to instrument calls.

Parameters

instruction – The instruction object.

Returns

The results returned from performing the operation.

instrumentserver.server.core.startServer(port: int = 5555, allowUserShutdown: bool = False, addresses: List[str] = [], initScript: Optional[str] = None) → Tuple[StationServer, QThread]

Create a server and run in a separate thread.

Returns

The server object and the thread it’s running in.

Client

Base client

class instrumentserver.client.core.BaseClient(host='localhost', port=5555, connect=True, timeout=5000)

Simple client for the StationServer. When a timeout happens, a RunTimeError is being raised. This error is there just to warn the user that a timeout has occurred. After that the client will restart the socket to continue the normal work.

Parameters

• host – The host address of the server, defaults to localhost.

• port – The port of the server, defaults to the value of DEFAULT_PORT.

• connect – If true, the server connects as it is being constructed, defaults to True.

• timeout – Amount of time that the client waits for an answer before declaring timeout in ms. Defaults to 5000.

recv_timeout

Timeout for server replies.

Proxy module

Client:

class instrumentserver.client.proxy.Client(host='localhost', port=5555, connect=True, timeout=5000)

Client with common server requests as convenience functions.

list_instruments() → Dict[str, str]

Get the existing instruments on the server.

find_or_create_instrument(instrument_class: str, name: str, *args: Any, **kwargs: Any) → ProxyInstrumentModule

Create a new instrument on the server and return a proxy for the new instrument.

Parameters

• instrument_class – Class of the instrument to create or a string of of the class.

• name – Name of the new instrument.

• args – Positional arguments for new instrument instantiation.

• kwargs – Keyword arguments for new instrument instantiation.

Returns

A new virtual instrument.

SubClient:

class instrumentserver.client.proxy.SubClient(instruments: Optional[List[str]] = None, sub_host: str = 'localhost', sub_port: int = 5556)

Specific subscription client used for real-time parameter updates.

update

Signal(str) – emitted when the server broadcast either a new parameter or an update to an existing one.

connect()

Connects the subscription client with the broadcast and runs an infinite loop to check for updates.

It should always be run on a separate thread or the program will get stuck in the loop.