Object Configuration

hutch-python allows users to customize certain aspects of objects after instantiation. This page will go through examples of this and how to use these options in your own session.

An example file is provided at the bottom of this page.

Creating a configuration file

Object configuration files are formatted in a simple YAML format, similar to the conf.yml files. The first level should be either a device name or device class. Note that you should not include the namespace in these names, as hutch-python will search for the device names. (fast_motor1 is ok, not sim.fast_motor1)

Under this, configuration directions should be listed.

device_name:
  direction1:
    - value1

DeviceClass:
  direction2:
    - value2

Available configuration directions

Currently, hutch-python supports the following configuration directives. If you would like to add another, please leave an issue or jira ticket.

(please don’t take any of these as suggested modifications)

tab_whitelist

A list of items to reveal in the tab-completion menu.

gon_sx:
  tab_whitelist:
    - kind

tab_blacklist

A list of items to hide from the tab_completion menu. These attributes still exist, and are simply hidden from the tab-completion menu.

at2l0:
  tab_blacklist:
    - blade_01

replace_tablist

A list of items to replace the tab completion list with. This will functionally hide all items and reveal the ones specified.

fast_motor1:
  replace_tablist:
    - position

kind

Modify the ophyd kind of a device and its subcomponents. This is used in ophyd internals to signal if we need to “pay attention” to a device or not.

To modify the kind of the top-level device, list the device name and the desired kind as a key-value pair. To modify the kind of its components, list the component name and the desired kind as a key-value pair.

at2l0:
  kind:
    at2l0: hinted
    blade_01: hinted
    blade_02: config

Order of Operations

The order of the object configuration file determines the order in which modifications are applied. Devices/Classes are modified from top to bottom, and the modifications are applied in the following order:

1. tab whitelist

2. tab blacklist

3. replace tablist

4. kind

Later modifications can override earlier modifications. More explicitly, this means that if an item is added to both the tab_whitelist and tab_blacklist, it will not be shown. Similarly the replace_tablist directive will take priority over the tab_blacklist and tab_whitelist directives.

Loading the configuration file

To use the configuration settings you’ve described, simply reference your configuration yaml file in your conf.yml file with the key obj_config. See obj_conf.

obj_config: /cds/group/pcds/pyps/apps/hutch-python/xxx/tabs.yml

Example obj_conf.yml

# Configuration options can be applied to a single device by name
# this hides at2l0.blade_01, shows at2l0.kind, and changes the
# kind of at2l0.blade_01 and at2l0.blade_02.
at2l0:
  tab_whitelist:
    - kind
  tab_blacklist:
    - blade_01
  kind:
    blade_01: hinted
    blade_02: config

# or to all devices of a specific class
pcdsdevices.epics_motor.IMS:
  tab_whitelist:
    - kind

# This tries to limit the tab completion list to only `kind`
FastMotor:
  replace_tablist:
    - kind

# This will allow `limits` to be seen in specifically `fast_motor1`
# while other simulated fast motors will only see `kind`
fast_motor1:
  tab_whitelist:
    - limits