instrumentserver.blueprints

Blueprints Module

This module contains all objects that are being sent between client and server. This includes all of the blueprints and other messaging objects (and its parts) like ServerInstruction and ServerResponse.

This module is responsible for defining them, present tools to create them and serializing them and deserializing them.

Any object that is ment to be sent, should have the method “toJson” implemented and should return a dictionary object with all of its item json compatible. This however does not apply to any argument or keyword argument inside those objects. These will each be tried to be serialized as best as possible. If an arbitrary class that is sent inside one of the objects present in this module needs to be serialized, this class must have an attribute called “attributes” inside listing all of the arguments that are needed to deserialize the class, these arguments must also be accepted by the constructor of the class.

After passing the string through the json.loads function, to deserialize the object we call the deserialize_obj. If we pass a dictionary containing the key ‘_class_type’. the function assumes that that dictionary is representing an object that must be instantiated. If the key is missing, it will try to deserialize any value in the keys and return the dictionary. If a list is passed, the function will go through the items in the list and deserialize them.

More Specifics for Developers

The server and client only communicate by sending a class that is in this module. You can split them in to 2 different categories: blueprints and instructions/information. The blueprints are used to represent instruments, functions, and parameters for the client to utilize. While instructions/information are classes used to ask for commands or request items and their responses.

All of the classes in the module contain the toJson method inside of them. For blueprints, their toJson calls the function bluePrintToDict, which returns the blueprint in a dict representation with all the values as strings. The function is smart enough such that if a blueprint has another blueprint inside, the inside blueprint gets properly deserialized. This occurs for all attributes inside the blueprint.

The rest of the classes each handles its own serialization in their own toJson function. There are occasions when classes like ServerInstruction, contain other classes of this module inside of it. When this happens the toJson function of that class is called.

Special care is placed in serializing the args and kwargs fields of all of those classes, as they do not have specified types and often require special handling. Because args always comes inside iterables, to serialize those the function iterable_to_serialize_dict is called. The function goes through each item and serializes them one by one. This ensures that any nested classes gets properly serialized. For kwargs, a similar process happens but for a dictionary, the function dict_to_serialized_dict is called instead.

To deserialize objects the function deserialize_obj is called. If an object is a dictionary or an iterable (except string) the function will go through all of the items inside of it trying to deserialize them as best as it can. A few helper functions are used like _is_numeric and _convert_dict_to_obj. If a string is passed, it will try and pass json.load to the string in case this happens because the first round of deserialization missed some nested object, otherwise, it will keep it as a string.

Functions

bluePrintFromInstrumentModule(path, ins)
bluePrintFromMethod(path, method)
bluePrintFromParameter(path, param)
bluePrintToDict(bp[, json_type])	Converts a blueprint into a dictionary.
deserialize_obj(data)	Tries to deserialize any object.
dict_to_serialized_dict([dct])	Same idea as iterable_to_serialized_dict but for dictionaries.
iterable_to_serialized_dict([iterable])	Goes through an iterable (lists, tuples, sets) and serialize each object inside of it.
to_dict(data)	Converts object to json serializable.

Classes

CallSpec(target[, args, kwargs, _class_type])	Spec for executing a call on an object in the station.
InstrumentCreationSpec(instrument_class[, ...])	Spec for creating an instrument instance.
InstrumentModuleBluePrint(name, path, ...[, ...])	Spec necessary for creating instrument proxies.
MethodBluePrint(name, path, ...[, ...])	Spec necessary for creating method proxies
Operation(value)	Valid operations for the server.
ParameterBluePrint(name, path, base_class, ...)	Spec necessary for creating parameter proxies.
ParameterBroadcastBluePrint(name, action[, ...])	Blueprint to broadcast parameter changes.
ParameterSerializeSpec(path, attrs, args, ...)
ServerInstruction(operation, ...)	Instruction spec for the server.
ServerResponse([message, error, _class_type])	Spec for what the server can return.

class instrumentserver.blueprints.CallSpec(target: str, args: Any | None = None, kwargs: Dict[str, Any] | None = None, _class_type: str = 'CallSpec')

Bases: object

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

args: Any | None = None

Positional arguments to pass.

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

kw args to pass.

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.

toJson()

class instrumentserver.blueprints.InstrumentCreationSpec(instrument_class: str, name: str = '', args: Tuple | None = None, kwargs: Dict[str, Any] | None = None, _class_type: str = 'InstrumentCreationSpec')

Bases: object

Spec for creating an instrument instance.

args: Tuple | None = None

Arguments to pass to the constructor.

instrument_class: str

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

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

kw args to pass to the constructor.

name: str = ''

toJson()

class instrumentserver.blueprints.InstrumentModuleBluePrint(name: str, path: str, base_class: str, instrument_module_class: str, docstring: str = '', parameters: Dict[str, ParameterBluePrint] | None = None, methods: Dict[str, MethodBluePrint] | None = None, submodules: Dict[str, InstrumentModuleBluePrint] | None = None, _class_type: str = 'InstrumentModuleBluePrint')

Bases: object

Spec necessary for creating instrument proxies.

base_class: str

docstring: str = ''

instrument_module_class: str

methods: Dict[str, MethodBluePrint] | None

name: str

parameters: Dict[str, ParameterBluePrint] | None

path: str

submodules: Dict[str, InstrumentModuleBluePrint] | None

toJson()

tostr(indent=0)

class instrumentserver.blueprints.MethodBluePrint(name: str, path: str, call_signature_str: str, signature_parameters: dict, docstring: str = '', _class_type: str = 'MethodBluePrint')

Bases: object

Spec necessary for creating method proxies

call_signature_str: str

docstring: str = ''

name: str

path: str

signature_parameters: dict

classmethod signature_str_and_params_from_obj(sig: Signature) → Tuple[str, dict]

toJson()

tostr(indent=0)

class instrumentserver.blueprints.Operation(value)

Bases: Enum

Valid operations for the server.

call = 'call'

Make a call to an object.

create_instrument = 'create_instrument'

Create a new instrument.

get_blueprint = 'get_blueprint'

Get the blueprint of an object.

get_existing_instruments = 'get_existing_instruments'

Get a list of instruments the server has instantiated.

get_gui_config = 'get_gui_config'

Gets the GUI configuration for an instrument.

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.blueprints.ParameterBluePrint(name: str, path: str, base_class: str, parameter_class: str, gettable: bool = True, settable: bool = True, unit: str = '', docstring: str = '', setpoints: List[str] | None = None, _class_type: str = 'ParameterBluePrint')

Bases: object

Spec necessary for creating parameter proxies.

base_class: str

docstring: str = ''

gettable: bool = True

name: str

parameter_class: str

path: str

setpoints: List[str] | None = None

settable: bool = True

toJson()

tostr(indent=0)

unit: str = ''

class instrumentserver.blueprints.ParameterBroadcastBluePrint(name: str, action: str, value: int | None = None, unit: str = '', _class_type: str = 'ParameterBroadcastBluePrint')

Bases: object

Blueprint to broadcast parameter changes.

action: str

name: str

pprint(indent=0)

toJson()

unit: str = ''

value: int | None = None

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

Bases: object

args: Any | None

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

attrs: List[str]

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

kwargs: Dict[str, Any] | None

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

path: str | None = None

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

toJson()

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

Bases: object

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.

args: List[Any] | None

Generic arguments.

call_spec: CallSpec | None = None

Specification for executing a call.

create_instrument_spec: InstrumentCreationSpec | None = None

Specification for creating an instrument.

kwargs: Dict[str, Any] | None

Generic keyword arguments.

operation: Operation

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

requested_path: str | None = None

Name of the instrument for which we want the blueprint.

serialization_opts: ParameterSerializeSpec | None = None

Options for serialization.

set_parameters: Dict[str, Any] | None

Setting parameters in bulk with a paramDict.

toJson()

validate()

class instrumentserver.blueprints.ServerResponse(message: Any | None = None, error: None | str | Warning | Exception | dict = None, _class_type: str = 'ServerResponse')

Bases: object

Spec for what the server can return. If the message is a string, it will assume it is a serialized json object and will try and deserialize it

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.

error: None | str | Warning | Exception = None

Any error message occurred during execution of the instruction.

message: Any | None = None

The return message.

toJson()

instrumentserver.blueprints.bluePrintFromInstrumentModule(path: str, ins: Instrument | InstrumentChannel | InstrumentBase) → InstrumentModuleBluePrint | None

instrumentserver.blueprints.bluePrintFromMethod(path: str, method: Callable) → MethodBluePrint | None

instrumentserver.blueprints.bluePrintFromParameter(path: str, param: Parameter | ParameterWithSetpoints) → ParameterBluePrint | None

instrumentserver.blueprints.bluePrintToDict(bp: ParameterBluePrint | MethodBluePrint | InstrumentModuleBluePrint | ParameterBroadcastBluePrint, json_type=True) → dict

Converts a blueprint into a dictionary.

Parameters:

• bp – The blueprint to convert

• json_type – If True, the values are str. If False, the values remain the objects that are in the blueprint. Defaults True.

instrumentserver.blueprints.deserialize_obj(data: Any)

Tries to deserialize any object. If the object is a dictionary and contains the key ‘_class_type’ it means that that dictionary represents a serialized object that needs to be instantiated. The function will try and deserailize any other item in the dictionary.

instrumentserver.blueprints.dict_to_serialized_dict(dct: Dict[str, Any] | None = None)

Same idea as iterable_to_serialized_dict but for dictionaries.

instrumentserver.blueprints.iterable_to_serialized_dict(iterable: Iterable[Any] | None = None)

Goes through an iterable (lists, tuples, sets) and serialize each object inside of it. If trying to serialize an arbitrary object, this object must have a class attribute “attributes” for the serialization to happen correctly.

returns a list with the args as serialized dictionaries.

The current rules:

• Any arbitrary object that is being serialized here must have a class attribute listing all the classes attributes that

the constructor needs to create an identical instance of that class - The serialized dictionary need to have the field: ‘_class_type’, to indicate what it is that needs to be instantiated.

instrumentserver.blueprints.to_dict(data) → Dict[str, str] | str

Converts object to json serializable. This is done by calling the method toJson of the object being passed. Strings are returned without any more processing.