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`	Create the instrument command string from a template or from a provider callable.
`handle_dynamic_command`	Creates a command wrapper calling the appropriate transport methods that are associated

create_command_string `staticmethod` ¶

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

Create the instrument command string from a template or from a provider callable.

The resulting string can be an SCPI command or a specific proprietary command string.

The provider argument controls how the raw command string is produced:

If provider is a callable, it is invoked as provider(*args, **kwargs) and must return the fully formed command string. This allows arbitrary construction logic (e.g. conditional pieces, lookups, or complex formatting) outside the template mechanics used below.
If provider is a string, it is treated as a template and variables are substituted from the bound arguments of func. Two string styles are supported:
- Template style using string.Template with $name placeholders (safe substitution).
- Format style using str.format with {name} placeholders, activated when the wrapped func has the __use_format attribute set.

The code binds args and kwargs to func's signature to produce a mapping of parameter names to values. For parameters declared as **kwargs the mixin will expand them with a __process_kwargs callable if present on func, otherwise it uses the default expand_kwargs. When template substitution is used, enum values are converted to their .value.

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]".This function will be called as:

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

Note

The processing attributes __process_kwargs and __use_format are only used when provider is a string. The attribute __process_cmd_string is used when provider is a template/format string or when it's a callable. The __process_cmd_string is the last action taken before the result is returned.

Parameters:

Name	Type	Description	Default
`func`	`Callable`	a function or method that provides the signature which defines the names available for substitution. The function may also carry processing attributes (`__use_format`, `__process_kwargs`, `__process_cmd_string`).	required
`provider`	`str \| Callable`	a template/format string or a function that returns a string	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	`{}`

Returns:

Type	Description
`str`	the final command string ready to be sent to the transport.

Raises:

Type	Description
`CommandError`	if `args`/`kwargs` cannot be bound to `func`'s signature.

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,
    cmd_string_func=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`
`cmd_string_func`	`Callable`	DIY function that will create a command string	`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.

egse.mixin

egse.mixin ¶

CommandType ¶

DynamicClientCommandMixin ¶

DynamicCommandMixin ¶

create_command_string staticmethod ¶

handle_dynamic_command ¶

add_cr_lf ¶

add_eot ¶

add_etx ¶

add_lf ¶

dynamic_command ¶

expand_kwargs ¶

create_command_string `staticmethod` ¶