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.state() PyTango.DeviceProxy API

TangoDevice.stateObj.read(cache=False).rvalue tango or .state agnostic

TangoDevice.getStateObj

TangoDevice.stateObj tango or .factory.getAttribute(state_full_name) agnostic

TangoDevice.getSWState

TangoDevice.state

TangoDevice.getValueObj

TangoDevice.stateObj.read tango or .state agnostic

TangoDevice.getDisplayValue

TangoDevice.stateObj.read().rvalue.name tango or .state.name agnostic

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)