egse.mixin

cgse-common

This code is part of the cgse-common package.

egse.mixin

This module defines Mixin classes that can be used for adding methods and properties to classes without strict inheritance.

Warning

Be careful, some of the Mixin classes require certain attributes to be defined in the outer subclass. Read the docstrings carefully to understand what is needed.

Classes:

Name	Description
CommandType	The type of the command, i.e. read, write, or transaction.
DynamicCommandMixin	This Mixin class defines the functionality to dynamically call specific instrument commands

Functions:

Name	Description
add_cr_lf	Add a carriage return and line feed to the given command string, if not added yet.
add_eot	Add an end-of-transmission EOT (ASCII code 0x04) to the command string.
add_etx	Add an end-of-text ETX (ASCII code 0x03) to the command string.
add_lf	Add a line feed to the given command string, if not added yet.
dynamic_command	Convert an interface method into a dynamic command.

CommandType

Bases: str, Enum

The type of the command, i.e. read, write, or transaction.

DynamicClientCommandMixin

This mixin class contains functionality to forward a device command from a client Proxy class to its control server.

Note

This mixin overrides the __getattribute__ method!

DynamicCommandMixin

DynamicCommandMixin()

This Mixin class defines the functionality to dynamically call specific instrument commands from methods that are defined in the Interface classes for device Controllers.

The mixin uses the self.transport instance variables that shall be defined by the Controller subclass. The self.transport shall be a DeviceTransport object providing the methods to read, write, and query an instrument.

Note

This mixin overrides the __getattribute__ method!

Note

This mixin class shall only be inherited from a Controller class that defines the self.transport attribute.

Methods:

Name	Description
create_command_string	Creates a command string that is understood by the instrument. This can be an SCPI
handle_dynamic_command	Creates a command wrapper calling the appropriate transport methods that are associated

create_command_string staticmethod

create_command_string(func, template_str, *args, **kwargs)

Creates a command string that is understood by the instrument. This can be an SCPI command or a specific proprietary command string. The cmd_str can contain placeholders similar to what is used in string formatting.

As an example, we have a function with two positional arguments 'a', and 'b' and one keyword argument flag:

def func(a, b, flag=True):
    pass

We have the following template string: CREATE:FUN:${a} ${b} [${flag}].

When we call the function as follows: func("TEMP", 23), we would then expect the returned string to be "CREATE:FUN:TEMP 23 [True]"

DynamicCommandMixin.create_command_string(func, template, "TEMP", 23)

Parameters:

Name	Type	Description	Default
func	Callable	a function or method that provides the signature	required
template_str	str	a template for the command	required
args	tuple	positional arguments that will be used in the command string	()
kwargs	dict	keywords arguments that will be used in the command string	{}

handle_dynamic_command

handle_dynamic_command(attr)

Creates a command wrapper calling the appropriate transport methods that are associated with the interface definition as passed into this method with the attr argument.

Parameters:

Name	Type	Description	Default
attr	Callable	The interface method that is decorated as a dynamic_command.	required

Returns:

Type	Description
Callable	Command wrapper with the read or write command, depending on the decorators used for that method in the corresponding Interface class.

Raises:

Type	Description
AttributeError	If the command is not listed in the YAML file and/or has not been listed.

add_cr_lf

add_cr_lf(cmd_string)

Add a carriage return and line feed to the given command string, if not added yet.

Parameters:

Name	Type	Description	Default
cmd_string	str	Command string.	required

Returns:

Type	Description
str	Given command string with a carriage return and line feed appended (if not present yet).

add_eot

add_eot(cmd_string)

Add an end-of-transmission EOT (ASCII code 0x04) to the command string.

Parameters:

Name	Type	Description	Default
cmd_string	str	the unprocessed command string	required

Returns:

Type	Description
str	The command string with the EOT character appended.

add_etx

add_etx(cmd_string)

Add an end-of-text ETX (ASCII code 0x03) to the command string.

Parameters:

Name	Type	Description	Default
cmd_string	str	the unprocessed command string	required

Returns:

Type	Description
str	The command string with the ETX character appended.

add_lf

add_lf(cmd_string)

Add a line feed to the given command string, if not added yet.

Parameters:

Name	Type	Description	Default
cmd_string	str	Command string.	required

Returns:

Type	Description
str	Given command string with a line feed appended (if not present yet).

dynamic_command

dynamic_command(
    *,
    cmd_type,
    cmd_string=None,
    process_response=None,
    process_cmd_string=None,
    process_kwargs=None,
    use_format=False,
    pre_cmd=None,
    post_cmd=None,
)

Convert an interface method into a dynamic command.

The arguments define the type of command and how the response shall be processed.

The command types 'write', 'query', and 'transaction' must be accompanied by a cmd_string argument that defines the formatting of the eventual command string that will be passed to the transport functions. The cmd_string is a template string that contains $-based substitutions for the function arguments. When you specify the use_format=True keyword, the cmd_string will be formatted using the format() function instead of the template substitution. The format option is less secure, but provides the functionality to format the arguments.

A template string looks like:

cmd_string="CREATE:SENS:TEMP ${name} ${type} default=${default}"

The same cmd_string as a format option:

cmd_string="CREATE:SENS:TEMP {name} {type} default={default:0.4f}"
use_format=True

The process_response and process_cmd_string keywords allow you to specify a pure function to process the response before it is returned, and to process the cmd_string before it is sent to the transport function.

The pre_cmd and post_cmd keywords specify a callable/function to be executed before and/or after the actual command was executed (i.e. send to the device). These functions are called with specific keyword arguments that allow additional device interaction and response processing. The pre_cmd function is called with the keyword argument transport= which passes the device transport. This allows the function to interact with the device again through the methods defined by the DeviceTransport interface. The pre_cmd function must not return anything. The post_cmd function is called with the keyword arguments transport= and response=. The response argument contains the response from the command that was previously sent to the device. The post_cmd function can use this response to parse its content and act against this content, although possible, it is usually not a good idea to alter the content of the response argument. The post_cmd function shall return (i.e. pass through) the response.

This decorator can add the following static attributes to the method:

• __dynamic_interface
• __read_command, __write_command, __query_command, __transaction_command
• __cmd_string
• __process_response
• __process_cmd_string
• __use_format
• __pre_cmd
• __post_cmd

Parameters:

Name	Type	Description	Default
cmd_type	str	one of 'read', 'write', 'query', or 'transaction' [required keyword]	required
cmd_string	str	format string for the generation of the instrument command	None
process_response	Callable	function to process the response	None
process_cmd_string	Callable	function to process the command string after substitution	None
process_kwargs	Callable	function to expand the kwargs after substitution	None
use_format	bool	use string formatting instead of string templates	False
pre_cmd	Callable	the function to execute before the command is executed	None
post_cmd	Callable	the function to execute after the command is executed	None

expand_kwargs

expand_kwargs(kwargs)

Expand keyword arguments and their values as 'key=value' separated by spaces.