HDFMapControlCLTemplate

class bapsflib._hdf.maps.controls.templates.HDFMapControlCLTemplate(group: Group)

Bases: HDFMapControlTemplate, ABC

A modified HDFMapControlTemplate template class for mapping control devices that record data around the concept of a command list.

Note

If the control device is NOT structured around a command list, then its mapping class should subclass HDFMapControlTemplate instead.

To fully define a subclass there are several abstract methods that need to be defined, which includes

construct_dataset_name()
_build_configs()

_default_state_values_dict()

abstractmethod _build_configs()

Inspect the HDF5 group and build the configuration dictionary, configs.

Functionality should specifically populate self._configs instead of self.configs. If a mapping fails, then a HDFMappingError should be raised.

abstractmethod _default_state_values_dict(config_name: str) → dict

Returns the default 'state values' dictionary for configuration config_name.

Parameters:: config_name (str) – configuration name

Examples

# define default dict
default_dict = {
    'command': {
        'dset paths':
            self._configs[config_name]['dese paths'],
        'dset field': ('Command index', ),
        're pattern': None,
        'command list':
            self._configs[config_name]['command list'],
        'cl str':
            self._configs[config_name]['command list'],
        'shape': (),
    }
}
default_dict['command']['dtype'] = \
    default_dict['command']['command list'].dtype

# return
return default_dict

If a subclass needs to initialize additional variables before _build_configs is called in the __init__, then those routines can be defined in the _init_before_build_configs method.

_init_before_build_configs()

Any initialization that needs to be performed before executing self._build_configs in __init__.

By default we do nothing, but subclasses can override this for their specific purposes.

Parameters:: group (h5py.Group) – The HDF5 to apply the mapping to.

Attributes Summary

`configs`	Dictionary containing all the relevant mapping information to translate the corresponding device data in the HDF5 file and provide a consistent user interface via `File`.
`contype`	Control device type.
`dataset_names`	List of names of the HDF5 datasets within the mapped group, at the root level.
`device_name`	Name of Control device
`group`	Instance of the HDF5 group that was mapped.
`group_name`	Name of the mapped HDF5 group.
`group_path`	Path of the mapped HDF5 group in the HDF5 file.
`has_command_list`	`True` if the control device utilizes a command list
`info`	Metadata information about the mapping type and the mapped group location in the HDF5 file.
`maptype`	Mapping class type (`MapTypes`).
`one_config_per_dset`	`True` if each control configuration has its own dataset
`subgroup_names`	List of names of the HDF5 subgroups within the mapped group, at the root level.

Methods Summary

`clparse`(config_name)	Return instance of `CLParse` for `config_name`.
`construct_dataset_name`(*args)	Constructs the dataset name corresponding to the input arguments.
`get_config_column_value`(config_name)	For the given configuration name `config_name` get the associated configuration value that would be in the configuration column of the associated HDF5 datasets.
`process_config_name`(config_name)	Process a given configuration name `config_name` and return the conditioned configuration name.
`reset_state_values_config`(config_name[, ...])	Reset the `configs[config_name]['state values']` dictionary.
`set_state_values_config`(config_name, patterns)	Rebuild and set `configs[config_name]['state values']` based on the supplied RE patterns.

Attributes Documentation

configs

Dictionary containing all the relevant mapping information to translate the corresponding device data in the HDF5 file and provide a consistent user interface via File.

Notes

When a control device saves around the concept of a command list, then configs shares the same structure as the HDFMapControlTemplate configs …with a couple alterations. There is now a required 'command list' key, and the 'state values' needs additional information.

The modified required keys look like:

Additional command list required keys for `config = configs['config name']`
Key	Description
config['command list']	A `tuple` representing the original command list. For example, config['command list'] = ( 'VOLT: 20.0', 'VOLT 25.0', 'VOLT 30.0', )
config['state values']	Has all the same keys as before, plus the addition of `'command list'`, `'cl str'`, and `re pattern`. For example, config['state values'] = { 'command': { 'dset paths': config['dset paths'], 'dset field': ('Command index',), 'shape': (), 'dtype': numpy.float32, 'command list': (20.0, 25.0, 30.0), 'cl str': ('VOLT: 20.0', 'VOLT 25.0', 'VOLT 30.0'), 're pattern': re.compile(r'some RE pattern'), }, } where `'re pattern'` is the compiled RE pattern used to parse the original command list, `'cl str'` is the matched string segment of the command list, and `'command list'` is the set of values that will populate the constructed numpy array.

contype: Control device type.

dataset_names: List of names of the HDF5 datasets within the mapped group, at the root level.

device_name: Name of Control device

group: Instance of the HDF5 group that was mapped.

group_name: Name of the mapped HDF5 group.

group_path: Path of the mapped HDF5 group in the HDF5 file.

has_command_list: True if the control device utilizes a command list

info

Metadata information about the mapping type and the mapped group location in the HDF5 file.

Extended Summary

The dictionary will contain the following elements:

info = {
    "group name": "Device",  # name of the mapped HDF5 group
    "group path": "/foo/bar/Device", # internal HDF5 path to the group
    "maptype": self.maptype,  # mapping class type
    "contype": self.contype,  # control device type
}

maptype: Mapping class type (MapTypes).

one_config_per_dset: True if each control configuration has its own dataset

subgroup_names: List of names of the HDF5 subgroups within the mapped group, at the root level.

Methods Documentation

clparse(config_name: str) → CLParse

Return instance of CLParse for config_name.

Parameters:: config_name (str) – configuration name

abstractmethod construct_dataset_name(*args) → str

Constructs the dataset name corresponding to the input arguments.

Returns:: name of dataset
Return type:: str

get_config_column_value(config_name: str | int) → str | None

For the given configuration name config_name get the associated configuration value that would be in the configuration column of the associated HDF5 datasets.

Typically, the column value is just config_name, but subclasses may override this to provide more sophisticated behavior. For example, if config_name is a mash-up of the column value and some other specifier, then this method can be used to do the proper regex to pull out the column value from config_name.

Parameters:: config_name (str or int) – The configuration name used in configs.

process_config_name(config_name: str | int) → str | int

Process a given configuration name config_name and return the conditioned configuration name.

The conditioned configuration name is a key to the mapped configs dictionary.

Typically, the conditioned configuration name is just the given config_name, but subclasses may override this method to allow desired “nicknames” to be conditioned into valid configuration names.

Note

This method is integrated into condition_controls, which is used by HDFReadData and HDFReadControls to condition the respective arguments add_controls and controls. This integration is why the nickname mapping implemented here is available in the HDFReadData and HDFReadControls classes, as well as the read data methods of File.

reset_state_values_config(config_name: str, apply_patterns=False)

Reset the configs[config_name]['state values'] dictionary.

Parameters:

config_name (str) – configuration name
apply_patterns (bool) – Set False (DEFAULT) to reset to _default_state_values_dict(config_name). Set True to rebuild dict using _default_re_patterns.

set_state_values_config(config_name: str, patterns: str | Iterable[str])

Rebuild and set configs[config_name]['state values'] based on the supplied RE patterns.

Parameters:

config_name (str) – configuration name
patterns (Union[str, Iterable[str]]) – list of RE strings