Taurus 3.x to 4.x migration guide

Taurus 4 was released in July 2016 with the main goal of making Taurus scheme-agnostic (i.e. not relying on Tango for its core functionalities).

Being a major version change, it is not fully backwards-compatible with the previous taurus 3.x versions.

However, a design goal for the 4.x series was to smooth the transition from 3.x as much as possible, and a backwards-compatibility layer which will mark old taurus code as deprecated but otherwise attempt to transparently support it in Taurus4 whenever that is possible.

Thanks to this compatibility layer, a Taurus 3 application is likely to run on taurus 4 after minimal or even no changes (but typically producing deprecation warnings and possibly with some functionality slightly altered).

A good strategy for migrating a taurus 3 application or widget to taurus 4 is to attempt to run it as-is with taurus 4 and then try to remove any deprecation warnings one by one. Most changes will be related to one of the following:

  • renamed methods and APIs (see the API changes section below),
  • differences between Tango states and Taurus states (see the Working with States section below)
  • Use of quantities for values (see the Working with quantities section below)

Note

The main sources of information regarding the changes introduced in Taurus 4 are the following two Enhancement proposals:

These changes are also treated in the Taurus 4 slides

API Changes

The following is a table of Taurus 3.x public members (classes, methods, attributes, etc) that became deprecated in Taurus 4

This list is a best-effort to document changes, but it may not be 100% complete (please feel free to suggest changes)

IMPORTANT: in some cases, the proposed alternative can be used as a drop-in replacement of the deprecated code, but in some others the code may need some adaptation.

Member Alternative(s)
TaurusConfigValue TaurusAttribute / TaurusAttrValue
TaurusConfigurationProxy TaurusAttribute
TaurusConfiguration TaurusAttribute
Configuration (helper) Attribute (helper)
Database (helper) Authority (helper)
TaurusManager.{g,s}etOperationMode
   
xxxAttrValue.<foo> (where <foo> is any config option) xxxAttribute.<foo>
xxxAttribute.value xxxAttribute.rvalue
xxxAttribute.w_value xxxAttribute.wvalue
xxxAttribute.has_failed xxxAttribute.error
   
TangoAttribute.{g,s}etDescription TangoAttribute.description
TangoAttribute.isInformDeviceOfErrors
TangoAttribute.displayValue str
TangoAttribute.getDisplayValue TangoAttribute.getLabel
TangoAttribute.getDisplayUnit TangoAttribute.rvalue.units
TangoAttribute.getStandardUnit TangoAttribute.rvalue.units
TangoAttribute.getUnit TangoAttribute.rvalue.units
TangoAttribute.unit TangoAttribute.rvalue.units
TangoAttribute.getDisplayWriteValue
TangoAttribute.getWritable TangoAttribute.isWritable
TangoAttribute.is{Scalar,Spectrum,Image} TangoAttribute.data_format
TangoAttribute.getMaxDim{X,Y} TangoAttribute.getMaxDim
TangoAttribute.getShape introspect the value shape if applicable
TangoAttribute.getParam TangoAttribute.getAttributeInfoEx
TangoAttribute.setParam use PyTango
TangoAttribute.getConfig self (merged)
TangoAttribute.getCRanges TangoAttribute .range + .alarms + .warnings
TangoAttribute.getCLimits TangoAttribute.range
TangoAttribute.getMinValue TangoAttribute.range
TangoAttribute.getMaxValue TangoAttribute.range
TangoAttribute.climits TangoAttribute.range
TangoAttribute.getCAlarms TangoAttribute.alarms
TangoAttribute.getMinAlarm TangoAttribute.alarms
TangoAttribute.getMaxAlarm TangoAttribute.alarms
TangoAttribute.min_alarm TangoAttribute.alarms
TangoAttribute.max_alarm TangoAttribute.alarms
TangoAttribute.calarms TangoAttribute.alarms
TangoAttribute.getCWarnings TangoAttribute.warnings
TangoAttribute.getMinWarning TangoAttribute.warnings
TangoAttribute.getMaxWarning TangoAttribute.warnings
TangoAttribute.min_warning TangoAttribute.warnings
TangoAttribute.max_warning TangoAttribute.warnings
TangoAttribute.cwarnings TangoAttribute.warnings
   
TangoDevice.getState TangoDevice.stateObj.read().rvalue tango or .state agnostic
TangoDevice.getStateObj TangoDevice.stateObj tango or .factory.getAttribute(state_full_name) agnostic
TangoDevice.getSWState TangoDevice.state
TangoDevice.getValueObj TangoDevice.state agnostic or stateObj.read tango
TangoDevice.getDisplayValue TangoDevice.state().name
TangoDevice.getHWObj TangoDevice.getDeviceProxy
TangoDevice.isValidDev (TangoDevice.getDeviceProxy() is not None)
TangoDevice.getDescription TangoDevice.description
   
TangoDatabase TangoAuthority
TangoAuthority.getHWObj TangoAuthority.getDeviceProxy
TangoAuthority.getValueObj TangoAuthority.getTangoDB
TangoAuthority.getDisplayValue TangoAuthority.getFullName
TangoAuthority.getDescription TangoAuthority.description
   
TangoFactory.getAttributeInfo TangoFactory.getAttribute
TangoFactory.getConfiguration TangoFactory.getAttribute
TangoDevice.{g,s}etOperationMode

Working with quantities

One of the most visible changes in Taurus 4 is its use of quantities for the values of numeric attributes.

In Taurus 4 all the values of numeric (float or integer) attributes and their associated properties (such as limits, warning levels, etc.) are pint.Quantity objects provided by the pint python module. A Quantity is essentially the combination of a magnitude and a unit. In taurus 3.x all values were just “magnitudes”, and their units were either implicit or loosely described as a free string property, but not enforced in any way.

By using Quantities Taurus 4 can automatically verify the dimensional validity of operations and provide support for I/O using user-preferred units.

Taurus 3 applications use .value or .w_value to get the read or write magnitude of a taurus value, respectively. In taurus 4 these would be equivalent to .rvalue.magnitude and .wvalue.magnitude, but the recommended way to adapt a Taurus 3 application is to use the Quantity objects, not their magnitudes (i.e., rvalue and wvalue) and refactor the code if necessary.

For example, given the following taurus 3 code where we assume that ampli is in meters:

v = taurus.Attribute('sys/tg_test/1/ampli').read()
foo = 5 + v.value  # here "5" is implicitly assumed to mean "5 meters"

a lazy conversion to avoid deprecation warnings in taurus 4 would be:

v = taurus.Attribute('sys/tg_test/1/ampli').read()
foo = 5 + v.rvalue.magnitude

...which is a very direct translation (and exactly what the automated backwards compatibility layer already does for you). However, the recommended conversion should use Quantities rather than magnitudes, e.g:

from taurus.core.units import UR  # import the taurus unit registry
v = taurus.Attribute('sys/tg_test/1/ampli').read()
foo = 5 * UR.meters + v.value  # use explicit units

Or, using the Quantity constructor instead of the Unit Registry:

from taurus.core.units import Q_  # import the taurus Quantity factory
v = taurus.Attribute('sys/tg_test/1/ampli').read()
foo = Q_("5 meters")  + v.value

Finally, note that when using Quantities, you do not need to care about matching the units, as long as they are dimensionally compatible:

foo = Q_("15 feet") + v.value

Working with Device states

Taurus 4 is all about being “scheme-agnostic”. This means that the taurus core (and ideally the main widgets as well) should not assume that the model objects (attributes, devices, authorities) are of one specific source type (Tango, Epics, Evaluation...)

This implies that the APIs should be scheme-agnostic. In Taurus 3, the concept of device state is completely “tango-centric” and it has been replaced in Taurus 4 by a much more generic one where the devices are either “ready” or “not ready” (this is of course much less informative, but it is generic enough to accomodate schemes where the sources of data may not even be hardware-related).

In Taurus 4, the Taurus device states are defined in the taurus.core.TaurusDevState enumeration, and the tango device states are supported by the tango scheme in taurus.core.tango.DevState enumeration, which is a numerically-compatible translation of PyTango.DevState

Some taurus 3.x applications may implement logic that depends on Tango states, or maybe display information based on the rich palette of Tango state colors. In these cases, when converting the application to Taurus 4 one needs to decide if the simple Taurus states are enough (in which case one should refactor the logic and use device.state to get the Taurus device state) or if the richer tango states are required to the point of sacrificing the scheme-agnosticism of the application (in which case one can use device.stateObj.read().rvalue to obtain the Tango device state)